APICheckout sessions
Create a checkout session
Hosted, branded payment page. Customer enters card on maxfi-api.exezine.az/checkout/<id> — never on your domain. We handle 3DS, retries, multi-language, and dispatch a signed webhook on result. PCI scope: SAQ A.
POST
/v2/payments/checkoutsk_live_ / sk_test_
Request body
| Field | Type | Description |
|---|---|---|
| amount* | integer | Amount in minor units (e.g. 4900 = $49.00). Always integer — no decimals. |
| currency* | string(3) | ISO 4217. Supported: USD, EUR, RUB, AZN, KZT, TRY, GBP. |
| description | string(500) | Shown to customer on checkout. Appears in dashboard. |
| order_id | string(128) | Your internal order number. Returned verbatim in webhooks. |
| language | string | Checkout UI language: en, ru, az. Default en. |
| customer | object | Optional. email, phone, name, country. Used for fraud signals + receipt. |
| success_url | string (url) | Where the customer lands after a successful payment. {CHECKOUT_SESSION_ID} placeholder is interpolated. Put this at the top level (Stripe-compatible). For back-compat settings.success_url is still accepted — top-level wins when both are set. |
| cancel_url | string (url) | Where the customer lands if they click "Back" on the checkout page or the session expires. Also accepted inside settings.cancel_url. |
| settings | object | Presentation overrides: payment_methods[] (whitelist card/wallet/bnpl), button_text, auto_return (ms), customer_fields. Legacy place for success_url/cancel_url. |
| webhook_url | string (url) | Per-session override for event delivery. Wins over the merchant-wide webhook URL configured in your dashboard. |
| metadata | object | Free-form key/value. Returned in every webhook event for this payment. Max 50 keys. |
| test_mode | boolean | Force sandbox even with a live key. Useful for E2E tests in production builds. |
Headers
| Header | Description |
|---|---|
| Authorization* | Bearer sk_live_… or Bearer sk_test_… (recommended, Stripe-compatible).Legacy alternative: X-API-Key: sk_live_…. Pick one per request, don't send both. |
| Idempotency-Key | Same key within 24h returns the originally created session — safe to retry. |
| Content-Type | application/json |
Response
| Field | Type | Description |
|---|---|---|
| id | string | Session id, format cs_*. Use it everywhere — list, get, refund. |
| checkout_url | string | Where to redirect the customer. |
| expires_at | datetime | ISO timestamp. Default 30 minutes from creation. |
| amount | integer | Echoed from request. |
| currency | string | Echoed from request. |
| status | string | open | processing | requires_action | succeeded | failed | expired. |
| livemode | boolean | false when created with sk_test_. |
Errors
| HTTP | Code | Reason |
|---|---|---|
| 400 | VALIDATION_ERROR | Bad amount / currency / url shape. |
| 401 | UNAUTHORIZED | Missing or invalid Authorization header. |
| 402 | NO_CONNECTOR | Merchant has no acquirer configured for the requested currency. Contact us. |
| 409 | IDEMPOTENCY_CONFLICT | Same Idempotency-Key used with a different body within 24h. |
| 429 | RATE_LIMIT_EXCEEDED | 100 requests / 60 seconds per API key (see /docs/errors). |