{
"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": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}Create a payment session
Create a new payment session. The server derives the source system from the merchant store and returns a checkout URL.
{
"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": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"decline_code": "<string>",
"request_log_url": "<string>",
"charge": "<string>"
},
"request_id": "<string>",
"timestamp": 123
}Authorizations
Bearer API Key, for example Bearer sk_live_xxx.
Unix timestamp in seconds. Must be within 5 minutes of server time.
Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.
Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.
Headers
Unix timestamp in seconds. Must be within 5 minutes of server time.
Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.
16 - 64Lowercase hex HMAC-SHA256 of {timestamp}.{nonce}.{requestBody} signed with the merchant API Secret. For GET requests, requestBody is an empty string.
Body
Payment amount in the minor unit of the currency.
x >= 1Merchant ledger currency, for example USD.
Merchant order ID. Must be unique for the merchant.
Overrides the Merchant Portal underpayment tolerance for an individual payment session.
| API parameter | Effective behavior |
|---|---|
Omit allowed_shortfall | Use the Merchant Portal underpayment tolerance policy |
allowed_shortfall: 0 | Use the API override and require full payment |
allowed_shortfall > 0 | Use the API override; payment may succeed when the difference between the target and received amounts does not exceed this value |
- The value must be an
int64and must not be negative. - The value uses the actual on-chain settlement currency's (USDT or USDC) minor unit, with the same semantics as the fixed-amount tolerance configured in Merchant Portal.
allowed_shortfallmust be less than the stablecoin target payment amount generated after the exchange rate is locked.- The API parameter takes precedence over Merchant Portal settings. When supplied, neither the Portal percentage nor fixed-amount underpayment tolerance participates in the session's underpayment decision.
- This parameter affects underpayments only. Overpayment handling continues to use the Merchant Portal policy.
- When the same
order_idis used to create a session again,allowed_shortfallmust match the original request.
x >= 0Order description, stored in session metadata.
Line items. If provided, amount must equal item subtotal plus tax and shipping.
Show child attributes
Show child attributes
Tax amount in minor units.
x >= 0Shipping amount in minor units.
x >= 0Redirect URL after successful payment.
Redirect URL after payment cancellation.
Payer email. Optional, but strongly recommended for payment notifications, customer identification, and post-payment reconciliation. Stored as metadata.email.
Merchant metadata key-value pairs. Non-string values are returned as strings.
Show child attributes
Show child attributes
Response
Payment session created.
Payment session ID.
Total amount in minor units.
Merchant ledger currency, returned in lowercase.
Payment status. confirming is returned as processing; completed is returned as paid.
pending, processing, paid, failed, expired, canceled Creation time, Unix seconds.
Expiration time, Unix seconds.
Checkout URL.
Line items.
Show child attributes
Show child attributes
Tax amount in minor units.
Shipping amount in minor units.
Exchange rate when currency conversion applies.
Actual on-chain payment currency, for example USDT.
Target amount in target-currency minor units.
Rate lock time, Unix seconds.
Related subscription ID, returned for subscription payments.
Related invoice ID, returned for invoice or subscription payments.
Merchant metadata.
Show child attributes
Show child attributes
Was this page helpful?