CryptoinfraDocs

#Gateway

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

Open as MarkdownFor AI assistants

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

EndpointSummary
GET /v1/paymentsList payments
POST /v1/paymentsCreate a payment for one order (hosted checkout or your own)
GET /v1/payments/assetsThe coins a payment can be paid with right now, with the USD rate it would lock
GET /v1/payments/settingsThe project's gateway settings, including the callback_secret
POST /v1/payments/settingsChange the default lifetime, the underpaid tolerance (0–5%), the support your customers see, or rotate the callback_secret
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}One payment by your order_id
GET /v1/payments/{id}/transfersEvery on-chain transfer seen against a payment
POST /v1/payments/{id}/cancelCancel a pending payment nothing has been sent to
GET /v1/payment-linksList payment links, with how many payments each made and how much was paid
POST /v1/payment-linksCreate a reusable payment link — a fixed price, or open (the payer types the amount, e.g. donations)
GET /v1/payment-links/{id}One payment link
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

NameInTypeRequiredDescription
statusquerystringno— (one of pending, confirming, paid, overpaid, underpaid, expired, expired_paid, cancelled)
qquerystringnoorder_id contains, or a payment id
limitqueryintegerno— (default 50; min 1; max 200)
offsetqueryintegerno— (default 0; min 0)

#Responses

StatusBodyMeaning
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

FieldTypeDescription
order_id requiredstringYour order reference: letters, digits and . : @ / # - (no spaces). (maxLength 128; pattern ^[A-Za-z0-9_.:@/#-]+$)_
amount requiredstringUSD.
currencystring(one of USD; default "USD")
asset_idstringLock the coin now (see GET /v1/payments/assets).
descriptionstring(maxLength 200)
callback_urlstringhttps; receives the payment.* events for this payment, signed with the project callback_secret.
return_urlstringWhere the hosted page sends the payer once paid.
customer_emailstring—
metadataobjectEchoed back on every read and event.
ttl_secondsintegerDefault: the project setting (3600). (min 300; max 86400)

#Responses

StatusBodyMeaning
200—Replayed — the existing payment for this order_id.
201PaymentCreated.
409—orderidconflict

201 response body — Payment

FieldTypeDescription
idstring—
order_idstring—
projectstring—
statusstring(one of pending, confirming, paid, overpaid, underpaid, expired, expired_paid, cancelled)
checkout_urlstring—
amountstringUSD
currencystring(one of USD)
asset_idstring—
networkstring—
exchange_ratestringUSD per whole coin, locked
addressstring—
payer_amountstring—
payer_amount_basestring—
paid_amountstring—
remaining_amountstring—
credited_amountstringwhat reached your balance after the fee
paid_late_amountstring—
metadataobject—
expires_atstring<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

StatusBodyMeaning
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

StatusBodyMeaning
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

FieldTypeDescription
projectstringProject id (prj_…); a project key acts in its own project
default_ttl_secondsinteger(min 300; max 86400)
underpaid_tolerancenumber(min 0; max 5)
rotate_callback_secretboolean—
support_emailstringShown to the customer on the payment page as "Need help?"; empty or null clears it (maxLength 254)
support_urlstringAn https:// link (help page, chat) shown the same way; preferred over supportemail; empty or null clears it (maxLength 300)_

#Responses

StatusBodyMeaning
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

NameInTypeRequiredDescription
idpathstringyes—

#Responses

StatusBodyMeaning
200PaymentThe payment.

200 response body — Payment

FieldTypeDescription
idstring—
order_idstring—
projectstring—
statusstring(one of pending, confirming, paid, overpaid, underpaid, expired, expired_paid, cancelled)
checkout_urlstring—
amountstringUSD
currencystring(one of USD)
asset_idstring—
networkstring—
exchange_ratestringUSD per whole coin, locked
addressstring—
payer_amountstring—
payer_amount_basestring—
paid_amountstring—
remaining_amountstring—
credited_amountstringwhat reached your balance after the fee
paid_late_amountstring—
metadataobject—
expires_atstring<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

NameInTypeRequiredDescription
orderIdpathstringyes—

#Responses

StatusBodyMeaning
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

NameInTypeRequiredDescription
idpathstringyes—

#Responses

StatusBodyMeaning
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

NameInTypeRequiredDescription
idpathstringyes—

#Responses

StatusBodyMeaning
200—Cancelled.
409—paymentclosed / paymentstarted

#Example request

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

List payment links, with how many payments each made and how much was paid · Auth: bearer API key

#Responses

StatusBodyMeaning
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

FieldTypeDescription
kind requiredstring(one of fixed, open)
title requiredstring(maxLength 80)
descriptionstring(maxLength 500)
amountstringUSD; required for fixed, not allowed for open
min_amountstringUSD; open only
max_amountstringUSD; open only
return_urlstring—
callback_urlstringhttps; every payment made through the link calls it
ttl_secondsinteger(min 300; max 86400)

#Responses

StatusBodyMeaning
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"
}'

One payment link · Auth: bearer API key

#Parameters

NameInTypeRequiredDescription
idpathstringyes—

#Responses

StatusBodyMeaning
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

NameInTypeRequiredDescription
idpathstringyes—

#Responses

StatusBodyMeaning
200—The link.

#Example request

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