Skip to main content
POST
/
api
/
v1
/
checkout
/
sessions
/
create
{
  "id": "<string>",
  "amount_total": 123,
  "currency": "<string>",
  "payment_status": "pending",
  "created": 123,
  "expires_at": 123,
  "url": "<string>",
  "line_items": [
    {
      "price_data": {
        "currency": "<string>",
        "unit_amount": 2,
        "product_data": {
          "name": "<string>",
          "description": "<string>"
        }
      },
      "quantity": 2
    }
  ],
  "tax_amount": 123,
  "shipping_amount": 123,
  "exchange_rate": "<string>",
  "target_currency": "<string>",
  "target_amount_total": 123,
  "rate_locked_at": 123,
  "subscription_id": "<string>",
  "invoice_id": "<string>",
  "metadata": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer API Key, for example Bearer sk_live_xxx.

​
X-StablePay-Timestamp
string
header
required

Unix timestamp in seconds. Must be within 5 minutes of server time.

​
X-StablePay-Nonce
string
header
required

Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.

​
X-StablePay-Signature
string
header
required

Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.

Headers

​
X-StablePay-Timestamp
string
required

Unix timestamp in seconds. Must be within 5 minutes of server time.

​
X-StablePay-Nonce
string
required

Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.

Required string length: 16 - 64
​
X-StablePay-Signature
string
required

Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.

Body

application/json
​
amount
integer<int64>
required

Payment amount in the minor unit of the currency.

Required range: x >= 1
​
currency
string
required

Merchant ledger currency, for example USD.

​
order_id
string
required

Merchant order ID. Must be unique for the merchant.

​
description
string

Order description, stored in session metadata.

​
line_items
object[]

Line items. If provided, amount must equal item subtotal plus tax and shipping.

​
tax_amount
integer<int64>

Tax amount in minor units.

Required range: x >= 0
​
shipping_amount
integer<int64>

Shipping amount in minor units.

Required range: x >= 0
​
success_url
string<uri>

Redirect URL after successful payment.

​
cancel_url
string<uri>

Redirect URL after payment cancellation.

​
email
string<email>

Payer email. Optional, but strongly recommended for payment notifications, customer identification, and post-payment reconciliation. Stored as metadata.email.

​
metadata
object

Merchant metadata key-value pairs. Non-string values are returned as strings.

Response

Payment session created.

​
id
string
required

Payment session ID.

​
amount_total
integer<int64>
required

Total amount in minor units.

​
currency
string
required

Merchant ledger currency, returned in lowercase.

​
payment_status
enum<string>
required

Payment status. confirming is returned as processing; completed is returned as paid.

Available options:
pending,
processing,
paid,
failed,
expired,
canceled
​
created
integer<int64>
required

Creation time, Unix seconds.

​
expires_at
integer<int64>
required

Expiration time, Unix seconds.

​
url
string<uri>

Checkout URL.

​
line_items
object[]

Line items.

​
tax_amount
integer<int64>

Tax amount in minor units.

​
shipping_amount
integer<int64>

Shipping amount in minor units.

​
exchange_rate
string

Exchange rate when currency conversion applies.

​
target_currency
string

Actual on-chain payment currency, for example USDT.

​
target_amount_total
integer<int64>

Target amount in target-currency minor units.

​
rate_locked_at
integer<int64>

Rate lock time, Unix seconds.

​
subscription_id
string

Related subscription ID, returned for subscription payments.

​
invoice_id
string

Related invoice ID, returned for invoice or subscription payments.

​
metadata
object

Merchant metadata.

Last modified on April 30, 2026