HTTP conventions and payment status
Authentication and permissions
Authorization header from your server. Each operation lists its required scope.401 means the supplied credential or Webhook signing Secret was rejected. HTTP 403 means the Key lacks the required scope. Unknown or inaccessible Payment resources return 404. Do not use the browser login session or payment_id in place of an API Key.Requests, retries and idempotency
Idempotency-Key. It must be nonblank and at most 255 bytes. Keep it stable for a single intent, including network retries. Reusing a Key with different input returns 409. order_ref does not replace idempotency and may be absent or repeated.Retry-After when returned for throttling or temporary unavailability. Do not repeat permanently rejected requests without correcting their input or credentials.err, msg and retryable fields, with optional operation-specific details. Use err for classification. msg is explanatory text, not a stable programmatic discriminator. An API failure may return 503 merchant_api_temporarily_unavailable without proving whether a prior write succeeded.Amounts and time
amount_raw must be a canonical positive integer string containing 1 to 78 ASCII digits, with no leading zero. Zero, signs, decimal points and exponent notation are rejected. Decimals come from the configured currency or crypto pricing source. Requests do not supply decimals. Fiat is a pricing unit, not a promise of card or fiat payment support.X-Server-Time as the authoritative response time, in UTC RFC 3339 with exactly three millisecond digits. Standard Date is a transport diagnostic. Do not infer a body server_time field. Other timestamps describe when the Payment was created, activated or updated.Payment status
| Status in API and app | Integration handling |
|---|---|
open | Wait for payment facts. A created Payment can still be awaiting first activation. |
paid | Process the authoritative result according to your fulfillment policy. |
partially_paid | Apply your underpayment policy; do not equate it with paid. |
overpaid | Apply your overpayment policy; the API does not automatically refund. |
expired | The activation deadline or payment window ended. Continue to use authoritative facts for exceptions. |
cancelled | A permitted merchant cancellation was recorded. |
review_required | Require review; do not infer success without authoritative status. |
activated_at is null and payment_expires_at is the deadline for first opening Checkout. When your customer first opens Checkout successfully, the API sets activated_at and resets payment_expires_at to the payment deadline. Creation, creation retries and queries from your server do not activate the Payment. Reopening an activated Checkout does not extend its payment window.status_version or emit payment.updated. Read GET /v1/payments/{payment_id} when you need the current activation time or payment deadline.status_version orders facts within one Payment, not across different Payments. A late or duplicate event must not overwrite a newer version. Payment states derive from authoritative facts and must not be treated as immutable browser success flags.