Payments & Checkout API

Endpoints for creating payments, retrieving payment details, and public checkout operations.

Create Payment Checkout

Create a new payment and get a checkout URL to redirect the customer.

POST /api/payment/checkout
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Authentication: OAuth2 token or Client Token with payments.create scope.

Request Body

{
  "amount": 10000,
  "currencyCode": "USD",
  "reference": "ORDER-123",
  "referenceLabel": "Order #123",
  "clientId": "your_client_id_here",
  "redirectUrl": "https://yoursite.com/success",
  "expiresAt": "2026-03-15T12:00:00Z"
}

Parameters

Parameter	Type	Required	Description
`amount`	integer	Yes	Payment amount in smallest unit (e.g., cents)
`currencyCode`	string	Yes	Currency code (must exist in configured currencies)
`reference`	string	Yes	Your order/payment reference
`referenceLabel`	string	Yes	Display label for the reference
`clientId`	string	Yes*	Payment application client ID (*or provide `siteId`)
`siteId`	string	Yes*	Payment site UUID (*or provide `clientId`)
`redirectUrl`	string	No	URL to redirect customer after payment
`blockchainSlug`	string	No	Specific blockchain to use
`productId`	string	No	Associated product UUID
`settlementCurrencyCode`	string	No	Currency for settlement
`expiresAt`	string	No	Checkout URL expiration (ISO 8601)

Response

{
  "data": {
    "checkoutUrl": "https://yourdomain.com/checkout/550e8400-e29b-41d4-a716-446655440000?expires=1742044800&signature=abc123def456..."
  }
}

The checkoutUrl includes an HMAC-SHA256 signature for security. Redirect your customer to this URL to complete payment.

Get Payment

Retrieve payment details.

GET /api/payment/{paymentId}
Authorization: Bearer YOUR_TOKEN

Authentication: OAuth2 token or Client Token with payments.get scope.

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "...",
    "status": "RECEIVED",
    "reference": "ORDER-123",
    "referenceLabel": "Order #123",
    "currencyCode": "USD",
    "settlementCurrencyCode": "USDT",
    "amount": {
      "value": 100.00,
      "amount": 10000,
      "formatted": "$100.00"
    },
    "receivedAmount": {
      "value": 100.00,
      "amount": 10000,
      "formatted": "$100.00"
    },
    "confirmedAt": "2026-01-15T10:30:00Z",
    "foundAt": "2026-01-15T10:15:00Z",
    "date": "2026-01-15T10:00:00Z",
    "checkoutUrl": "https://..."
  }
}

List Payments

Get a paginated list of payments for your payment applications.

GET /api/payment
Authorization: Bearer YOUR_OAUTH_TOKEN

Authentication: OAuth2 token only.

Query Parameters

Parameter	Type	Description
`paymentApplicationId`	string	Filter by payment application UUID

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "CONFIRMED",
      "reference": "ORDER-123",
      "referenceLabel": "Order #123",
      "currencyCode": "USD",
      "amount": {
        "value": 100.00,
        "amount": 10000,
        "formatted": "$100.00"
      },
      "date": "2026-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 150,
      "count": 20,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 8
    }
  }
}

Get Payment Instructions

Get payment instructions for a specific provider and method.

GET /api/payment/{paymentId}/provider/{provider}/method/{method}
Authorization: Bearer YOUR_TOKEN

Authentication: OAuth2 token or Client Token with payments.user-instructions.get scope.

Returns provider-specific payment instructions (e.g., blockchain address, QR code, bank details).

Amount Fields

All monetary values are returned as amount objects with the following structure:

Field	Type	Description
`value`	float	Decimal value (e.g., `100.00`)
`amount`	integer	Value in smallest currency unit / cents (e.g., `10000`)
`formatted`	string	Formatted display string (e.g., `"$100.00"`)
`currency`	object	Currency details (code, name, decimals)
`decimals`	integer	Number of decimal places
`symbol`	string	Currency symbol (e.g., `"$"`)

Response examples in this documentation show a simplified subset (value, amount, formatted). The full object includes all fields listed above.

Payment Statuses

Status	Description
`OPEN`	Payment created, awaiting payment
`FOUND`	Funds detected on blockchain but not yet confirmed
`UNDERPAID`	Received amount is less than requested
`RECEIVED`	Full payment received and confirmed
`CONFIRMED`	Merchant webhook executed successfully
`CANCELLED`	Payment cancelled by merchant
`ERROR`	Error during payment processing
`REFUND`	Payment has been refunded

Checkout Endpoints (Public)

These endpoints are used by the hosted checkout page. They do not require authentication — the checkout URL signature provides security.

Get Checkout Payment Status

GET /api/checkout/payment/{paymentId}

Returns payment details along with merchant settings (e.g., whether underpayment or overpayment is allowed).

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "OPEN",
    "reference": "ORDER-123",
    "referenceLabel": "Order #123",
    "currencyCode": "USD",
    "amount": {
      "value": 100.00,
      "amount": 10000,
      "formatted": "$100.00"
    }
  }
}

Get Available Payment Methods

GET /api/checkout/{paymentId}/payment-methods

Returns the list of cryptocurrencies and payment methods the merchant has configured for their payment application.

Get Checkout Payment Instructions

GET /api/checkout/payment/{paymentId}/provider/{provider?}/method/{method?}

Returns the payment address, amount, and other instructions specific to the selected cryptocurrency and network. Link expiration and signature are validated.