# Gateway

Per-order USD payments with a hosted checkout — what a store plugin or your checkout uses

13 endpoints. Generated from `docs/openapi.yaml` v1.0.0.

| Endpoint | Summary |
| --- | --- |
| [`GET /v1/payments`](#get-v1-payments) | List payments |
| [`POST /v1/payments`](#post-v1-payments) | Create a payment for one order (hosted checkout or your own) |
| [`GET /v1/payments/assets`](#get-v1-payments-assets) | The coins a payment can be paid with right now, with the USD rate it would lock |
| [`GET /v1/payments/settings`](#get-v1-payments-settings) | The project's gateway settings, including the callback_secret |
| [`POST /v1/payments/settings`](#post-v1-payments-settings) | Change the default lifetime, the underpaid tolerance (0–5%), the support your customers see, or rotate the callback_secret |
| [`GET /v1/payments/{id}`](#get-v1-payments-id) | One payment (status derived live — an expired payment reads expired even before any worker ran) |
| [`GET /v1/payments/by-order/{orderId}`](#get-v1-payments-by-order-orderid) | One payment by your order_id |
| [`GET /v1/payments/{id}/transfers`](#get-v1-payments-id-transfers) | Every on-chain transfer seen against a payment |
| [`POST /v1/payments/{id}/cancel`](#post-v1-payments-id-cancel) | Cancel a pending payment nothing has been sent to |
| [`GET /v1/payment-links`](#get-v1-payment-links) | List payment links, with how many payments each made and how much was paid |
| [`POST /v1/payment-links`](#post-v1-payment-links) | Create a reusable payment link — a fixed price, or open (the payer types the amount, e.g. donations) |
| [`GET /v1/payment-links/{id}`](#get-v1-payment-links-id) | One payment link |
| [`POST /v1/payment-links/{id}`](#post-v1-payment-links-id) | Change a link (title, description, amounts, urls) or switch it off and on (`active`) |

## GET /v1/payments

**List payments**  ·  _Auth: bearer API key_

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | `string` | no | — _(one of `pending`, `confirming`, `paid`, `overpaid`, `underpaid`, `expired`, `expired_paid`, `cancelled`)_ |
| `q` | query | `string` | no | order_id contains, or a payment id |
| `limit` | query | `integer` | no | — _(default `50`; min `1`; max `200`)_ |
| `offset` | query | `integer` | no | — _(default `0`; min `0`)_ |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | A page of payments. |

#### Example request

```bash
curl -X GET 'https://api.cryptoinfra.build/v1/payments' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## POST /v1/payments

**Create a payment for one order (hosted checkout or your own)**  ·  _Auth: bearer API key_

One payment per `order_id` per project — the create is idempotent on it: the same
order with the same terms returns the original (200), different terms are a 409
`order_id_conflict`. "Terms" are `amount`, `asset_id` (when given), `callback_url` and
`metadata.install` (a store plugin's install id);
to charge a changed order again, send a new order id (for example with a `-2` suffix).
Priced in USD. Leave `asset_id` out and the payer picks the coin on the hosted page
(`checkout_url`); give it and the response also carries `address` + `payer_amount`
for your own checkout. The fee is your ordinary deposit fee, taken from what
arrives — nothing is added to your price.

#### Request body

`application/json` · required

| Field | Type | Description |
| --- | --- | --- |
| `order_id` **required** | `string` | Your order reference: letters, digits and . : @ / # - _ (no spaces). _(maxLength `128`; pattern `^[A-Za-z0-9_.:@/#-]+$`)_ |
| `amount` **required** | `string` | USD. |
| `currency` | `string` |  _(one of `USD`; default `"USD"`)_ |
| `asset_id` | `string` | Lock the coin now (see GET /v1/payments/assets). |
| `description` | `string` |  _(maxLength `200`)_ |
| `callback_url` | `string` | https; receives the payment.* events for this payment, signed with the project callback_secret. |
| `return_url` | `string` | Where the hosted page sends the payer once paid. |
| `customer_email` | `string` | — |
| `metadata` | `object` | Echoed back on every read and event. |
| `ttl_seconds` | `integer` | Default: the project setting (3600). _(min `300`; max `86400`)_ |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | Replayed — the existing payment for this order_id. |
| `201` | `Payment` | Created. |
| `409` | — | order_id_conflict |

**`201` response body** — `Payment`

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | — |
| `order_id` | `string` | — |
| `project` | `string` | — |
| `status` | `string` |  _(one of `pending`, `confirming`, `paid`, `overpaid`, `underpaid`, `expired`, `expired_paid`, `cancelled`)_ |
| `checkout_url` | `string` | — |
| `amount` | `string` | USD |
| `currency` | `string` |  _(one of `USD`)_ |
| `asset_id` | `string` | — |
| `network` | `string` | — |
| `exchange_rate` | `string` | USD per whole coin, locked |
| `address` | `string` | — |
| `payer_amount` | `string` | — |
| `payer_amount_base` | `string` | — |
| `paid_amount` | `string` | — |
| `remaining_amount` | `string` | — |
| `credited_amount` | `string` | what reached your balance after the fee |
| `paid_late_amount` | `string` | — |
| `metadata` | `object` | — |
| `expires_at` | `string<date-time>` | — |

```json
{
  "id": "string",
  "order_id": "string",
  "project": "string",
  "status": "pending",
  "checkout_url": "string",
  "amount": "string",
  "currency": "USD",
  "asset_id": "string",
  "network": "string",
  "exchange_rate": "string",
  "address": "string",
  "payer_amount": "string",
  "payer_amount_base": "string",
  "paid_amount": "string",
  "remaining_amount": "string",
  "credited_amount": "string",
  "paid_late_amount": "string",
  "metadata": {},
  "expires_at": "2026-08-31T09:15:00.000Z"
}
```

#### Example request

```bash
curl -X POST 'https://api.cryptoinfra.build/v1/payments' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "order_id": "string",
  "amount": "49.99"
}'
```

## GET /v1/payments/assets

**The coins a payment can be paid with right now, with the USD rate it would lock**  ·  _Auth: bearer API key_

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | Payable assets. |

#### Example request

```bash
curl -X GET 'https://api.cryptoinfra.build/v1/payments/assets' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## GET /v1/payments/settings

**The project's gateway settings, including the callback_secret**  ·  _Auth: bearer API key_

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | Settings. |

#### Example request

```bash
curl -X GET 'https://api.cryptoinfra.build/v1/payments/settings' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## POST /v1/payments/settings

**Change the default lifetime, the underpaid tolerance (0–5%), the support your customers see, or rotate the callback_secret**  ·  _Auth: bearer API key_

#### Request body

`application/json` · optional

| Field | Type | Description |
| --- | --- | --- |
| `project` | `string` | Project id (prj_…); a project key acts in its own project |
| `default_ttl_seconds` | `integer` |  _(min `300`; max `86400`)_ |
| `underpaid_tolerance` | `number` |  _(min `0`; max `5`)_ |
| `rotate_callback_secret` | `boolean` | — |
| `support_email` | `string` | Shown to the customer on the payment page as "Need help?"; empty or null clears it _(maxLength `254`)_ |
| `support_url` | `string` | An https:// link (help page, chat) shown the same way; preferred over support_email; empty or null clears it _(maxLength `300`)_ |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | Settings. |

#### Example request

```bash
curl -X POST 'https://api.cryptoinfra.build/v1/payments/settings' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## GET /v1/payments/{id}

**One payment (status derived live — an expired payment reads expired even before any worker ran)**  ·  _Auth: bearer API key_

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | `string` | yes | — |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | `Payment` | The payment. |

**`200` response body** — `Payment`

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | — |
| `order_id` | `string` | — |
| `project` | `string` | — |
| `status` | `string` |  _(one of `pending`, `confirming`, `paid`, `overpaid`, `underpaid`, `expired`, `expired_paid`, `cancelled`)_ |
| `checkout_url` | `string` | — |
| `amount` | `string` | USD |
| `currency` | `string` |  _(one of `USD`)_ |
| `asset_id` | `string` | — |
| `network` | `string` | — |
| `exchange_rate` | `string` | USD per whole coin, locked |
| `address` | `string` | — |
| `payer_amount` | `string` | — |
| `payer_amount_base` | `string` | — |
| `paid_amount` | `string` | — |
| `remaining_amount` | `string` | — |
| `credited_amount` | `string` | what reached your balance after the fee |
| `paid_late_amount` | `string` | — |
| `metadata` | `object` | — |
| `expires_at` | `string<date-time>` | — |

```json
{
  "id": "string",
  "order_id": "string",
  "project": "string",
  "status": "pending",
  "checkout_url": "string",
  "amount": "string",
  "currency": "USD",
  "asset_id": "string",
  "network": "string",
  "exchange_rate": "string",
  "address": "string",
  "payer_amount": "string",
  "payer_amount_base": "string",
  "paid_amount": "string",
  "remaining_amount": "string",
  "credited_amount": "string",
  "paid_late_amount": "string",
  "metadata": {},
  "expires_at": "2026-08-31T09:15:00.000Z"
}
```

#### Example request

```bash
curl -X GET 'https://api.cryptoinfra.build/v1/payments/pay_0123456789abcdef01234567' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## GET /v1/payments/by-order/{orderId}

**One payment by your order_id**  ·  _Auth: bearer API key_

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | `string` | yes | — |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | The payment. |

#### Example request

```bash
curl -X GET 'https://api.cryptoinfra.build/v1/payments/by-order/string' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## GET /v1/payments/{id}/transfers

**Every on-chain transfer seen against a payment**  ·  _Auth: bearer API key_

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | `string` | yes | — |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | Transfers |

#### Example request

```bash
curl -X GET 'https://api.cryptoinfra.build/v1/payments/string/transfers' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## POST /v1/payments/{id}/cancel

**Cancel a pending payment nothing has been sent to**  ·  _Auth: bearer API key_

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | `string` | yes | — |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | Cancelled. |
| `409` | — | payment_closed / payment_started |

#### Example request

```bash
curl -X POST 'https://api.cryptoinfra.build/v1/payments/string/cancel' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## GET /v1/payment-links

**List payment links, with how many payments each made and how much was paid**  ·  _Auth: bearer API key_

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | Links. |

#### Example request

```bash
curl -X GET 'https://api.cryptoinfra.build/v1/payment-links' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## POST /v1/payment-links

**Create a reusable payment link — a fixed price, or open (the payer types the amount, e.g. donations)**  ·  _Auth: bearer API key_

Every payer who uses the link (its `url`, or the embeddable button) makes a NEW payment
with its own order id (`link-…`), listed under GET /v1/payments and firing the same
payment.* events, with `metadata.link` = this link's id.

#### Request body

`application/json` · required

| Field | Type | Description |
| --- | --- | --- |
| `kind` **required** | `string` |  _(one of `fixed`, `open`)_ |
| `title` **required** | `string` |  _(maxLength `80`)_ |
| `description` | `string` |  _(maxLength `500`)_ |
| `amount` | `string` | USD; required for fixed, not allowed for open |
| `min_amount` | `string` | USD; open only |
| `max_amount` | `string` | USD; open only |
| `return_url` | `string` | — |
| `callback_url` | `string` | https; every payment made through the link calls it |
| `ttl_seconds` | `integer` |  _(min `300`; max `86400`)_ |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `201` | — | The link |

#### Example request

```bash
curl -X POST 'https://api.cryptoinfra.build/v1/payment-links' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "fixed",
  "title": "string"
}'
```

## GET /v1/payment-links/{id}

**One payment link**  ·  _Auth: bearer API key_

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | `string` | yes | — |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | The link. |

#### Example request

```bash
curl -X GET 'https://api.cryptoinfra.build/v1/payment-links/pl_0123456789abcdef01234567' \
  -H 'Authorization: Bearer ck_live_your_key'
```

## POST /v1/payment-links/{id}

**Change a link (title, description, amounts, urls) or switch it off and on (`active`)**  ·  _Auth: bearer API key_

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | `string` | yes | — |

#### Responses

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | — | The link. |

#### Example request

```bash
curl -X POST 'https://api.cryptoinfra.build/v1/payment-links/string' \
  -H 'Authorization: Bearer ck_live_your_key'
```
