Sessions

Create a checkout session

POST/api/pay/v1/sessions

Create server-side, then send the customer to checkout_url (or pass id to the embed script).

Price the order in ONE of two ways — send amounts or price_usd, never both and never neither (PAY_AMOUNT_INVALID, 422):

amounts — you name the figure in each coin you accept, and the customer picks one. Coinland converts nothing: you price, the customer pays exactly that.
price_usd — you name one USD figure and Coinland quotes it in every coin you accept, at the live rate, at creation time. Those quotes ARE the rate lock and the session's own expires_at is its window; there is no separate rate-lock timer. A coin with no live rate is omitted from the quotes; if nothing can be priced the request is refused with PAY_RATE_UNAVAILABLE (503).

Authorization

bearerKey

AuthorizationBearer <token>

Authorization: Bearer clpay_live_<64 hex> for the checkout routes, Authorization: Bearer clpay_payout_<64 hex> for the payout routes. The wrong class on a route is PAY_WRONG_KEY_KIND (403).

A key may additionally carry an IP allowlist set in the business console. Empty (the default) places no restriction; with entries, a call from an unlisted address is UNAUTHORIZED (401).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reference_id*string

Your order id — the idempotency key.

Lengthlength <= 128

title*string

What the customer is paying for (widget headline).

Lengthlength <= 128

customer*

WHO this order is for — YOUR customer record, mandatory on every create-session call (there is no opt-out). At least these identifiers per customer, so the AML binding holds three ways: your internal user id, the Latin full name, and the email. At first payment the paying Coinland account is PERMANENTLY bound to id after an explicit consent ceremony and a name check against the account's verified identity; from then on only that account can pay this customer's sessions. Replaying a reference_id with a different customer is PAY_DUPLICATE_REFERENCE.

description?string

Lengthlength <= 512

amounts?array<>

One entry per coin you price this order in. Mutually exclusive with price_usd.

Items1 <= items <= 10

price_usd?string

One USD figure, as a positive decimal string with at most 8 decimal places, quoted into every coin you accept at creation. Mutually exclusive with amounts.

return_url?string

https URL the customer is redirected to after paying, with ?receipt=<token>&payment_id=<id> appended. Hint-only — fulfil on the webhook/API, not the redirect.

Formaturi

cancel_url?string

https URL for "back to store" when the customer cancels.

Formaturi

metadata?

Free-form passthrough, echoed on reads and webhooks.

ttl_minutes?integer

Overrides your configured session lifetime.

Range5 <= value <= 1440

Response Body

`application/json`

curl -X POST "https://example.com/api/pay/v1/sessions" \  -H "Content-Type: application/json" \  -d '{    "reference_id": "string",    "title": "string",    "customer": {      "id": "string",      "name": "string",      "email": "string"    }  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "reference_id": "string",  "status": "open",  "title": "string",  "description": "string",  "amounts": [    {      "currency": "string",      "amount": "string",      "usd_value": "string"    }  ],  "pricing_mode": "usd",  "price_usd": "string",  "checkout_url": "http://example.com",  "return_url": "string",  "cancel_url": "string",  "metadata": {},  "payment": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "receipt_no": "string",    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",    "reference_id": "string",    "status": "completed",    "currency": "string",    "amount": "string",    "charged_amount": "string",    "fee_amount": "string",    "fee_bearer": "merchant",    "net_amount": "string",    "usd_value": "string",    "payer_id": "7bded2ff-6743-4a0e-a147-77540fb16606",    "metadata": {},    "receipt": "string",    "paid_at": "2019-08-24T14:15:22Z"  },  "expires_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}

Fetch a session

GET/api/pay/v1/sessions/{id}

Authoritative state. When completed, the payment summary is embedded.

Authorization

bearerKey

AuthorizationBearer <token>

Authorization: Bearer clpay_live_<64 hex> for the checkout routes, Authorization: Bearer clpay_payout_<64 hex> for the payout routes. The wrong class on a route is PAY_WRONG_KEY_KIND (403).

A key may additionally carry an IP allowlist set in the business console. Empty (the default) places no restriction; with entries, a call from an unlisted address is UNAUTHORIZED (401).

In: header

Path Parameters

id*string

Session id (UUID) or your reference_id.

Response Body

`application/json`

curl -X GET "https://example.com/api/pay/v1/sessions/string"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "reference_id": "string",  "status": "open",  "title": "string",  "description": "string",  "amounts": [    {      "currency": "string",      "amount": "string",      "usd_value": "string"    }  ],  "pricing_mode": "usd",  "price_usd": "string",  "checkout_url": "http://example.com",  "return_url": "string",  "cancel_url": "string",  "metadata": {},  "payment": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "receipt_no": "string",    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",    "reference_id": "string",    "status": "completed",    "currency": "string",    "amount": "string",    "charged_amount": "string",    "fee_amount": "string",    "fee_bearer": "merchant",    "net_amount": "string",    "usd_value": "string",    "payer_id": "7bded2ff-6743-4a0e-a147-77540fb16606",    "metadata": {},    "receipt": "string",    "paid_at": "2019-08-24T14:15:22Z"  },  "expires_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}

Cancel an open session

POST/api/pay/v1/sessions/{id}/cancel

Idempotent — cancelling a cancelled session returns it unchanged. A completed session cannot be cancelled (PAY_SESSION_STATE, 409): money that has moved stays moved.

Authorization

bearerKey

AuthorizationBearer <token>

Authorization: Bearer clpay_live_<64 hex> for the checkout routes, Authorization: Bearer clpay_payout_<64 hex> for the payout routes. The wrong class on a route is PAY_WRONG_KEY_KIND (403).

A key may additionally carry an IP allowlist set in the business console. Empty (the default) places no restriction; with entries, a call from an unlisted address is UNAUTHORIZED (401).

In: header

Path Parameters

id*string

Session id (UUID) or your reference_id.

Response Body

`application/json`

curl -X POST "https://example.com/api/pay/v1/sessions/string/cancel"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "reference_id": "string",  "status": "open",  "title": "string",  "description": "string",  "amounts": [    {      "currency": "string",      "amount": "string",      "usd_value": "string"    }  ],  "pricing_mode": "usd",  "price_usd": "string",  "checkout_url": "http://example.com",  "return_url": "string",  "cancel_url": "string",  "metadata": {},  "payment": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "receipt_no": "string",    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",    "reference_id": "string",    "status": "completed",    "currency": "string",    "amount": "string",    "charged_amount": "string",    "fee_amount": "string",    "fee_bearer": "merchant",    "net_amount": "string",    "usd_value": "string",    "payer_id": "7bded2ff-6743-4a0e-a147-77540fb16606",    "metadata": {},    "receipt": "string",    "paid_at": "2019-08-24T14:15:22Z"  },  "expires_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}

Sessions

201application/json

409application/json

422application/json

503application/json

200application/json

404application/json

200application/json

409application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`