APICheckout sessions

Create a checkout session

Creates a session on the MAXFI payment page. Redirect the customer to checkout_url: they choose a payment method and pay on maxfi-api.exezine.az/checkout/<id>, so card details never pass through your servers. MAXFI runs bank verification (3-D Secure) when the bank requires it and reports the result with webhooks.

The page is available in English, Russian and Azerbaijani. It shows the payment methods enabled for your account; settings.payment_methods narrows the list for one session.

POST/v2/payments/checkout

sk_live_ / sk_test_

Request body

Field	Type	Description
amount (required)	integer	Amount in minor units, a positive integer: `4900` = 49.00.
currency (required)	string(3)	`AZN`, `USD`, `EUR` or `RUB`. The currency must be enabled for the channel of the payment; otherwise the API returns `400 CURRENCY_NOT_ALLOWED`.
description	string(500)	Shown to the customer on the payment page.
order_id	string(128)	Your order number. Returned as `order_number` in webhook events and in `GET /v2/payments/checkout/{id}`. If omitted, MAXFI generates one.
language	string	Language of the page: `en`, `ru` or `az`. If you pass it, the page opens in this language; the customer can still switch it on the page. If you omit it, the page uses the language of the customer’s browser, and otherwise the default language set in merchant portal → Form Builder. Languages switched off there are not used.
initial_method	string	Payment method whose tab the page opens first: `card`, `sbp`, `sberpay`, `tpay`, `yoomoney`, `recurrent`, `apple_pay` or `google_pay`. If this method is not available for the payment — `recurrent` never is: a saved card is charged only with `POST /v2/payments` — the page opens the first method in the list.
customer	object	`email` — the customer’s email. It is stored with the session and sent as `customer_email` in webhook events. `ip` — the customer’s IP address (IPv4 or IPv6) for risk checks; without it the payment page uses the address of the customer’s browser. An invalid address is ignored.
success_url	string (url)	The success screen of the payment page links to this address. Opening the page of a paid session redirects here.
cancel_url	string (url)	Return address after an unsuccessful payment, for payment steps that take the customer away from the MAXFI page (for example, a bank or wallet page).
webhook_url	string (url)	Sends this session’s `payment.requires_action`, `payment.succeeded` and `payment.failed` events to this address instead of your account’s webhook URL; `payment.refunded` and `payment.expired` still go to the account URL. Events are signed with your account’s webhook secret, if one is set. Deliveries go only to public HTTPS addresses.
metadata	object	Your key–value pairs; values must be strings. Returned in `data.metadata` of payment status webhook events. Keys `merchant_id` and `channel_id` are reserved: MAXFI removes them and sets `channel_id` itself.
channel_id	string(64)	Channel for this payment: its code, `ch_…` ID or UUID. Omit it to use the default channel or the channel of a channel-bound key. See Channels.
settings	object	`payment_methods` — an array of method codes (the same values as `initial_method`): the session offers only these methods, and a payment by another method is refused. If none of them is available for this payment — for example, only SBP for a payment that is not in RUB, or only `recurrent`, which the payment page does not offer — the API returns `400 PAYMENT_METHODS_UNAVAILABLE`. `settings.success_url` and `settings.cancel_url` are still read for older integrations; the top-level fields take precedence. Other `settings` fields (`button_text`, `auto_return`, `customer_fields`) are not supported and return `400 UNSUPPORTED_PARAMETER`.
test_mode	boolean	Not needed: the key sets the mode (`sk_test_` or `sk_live_`). A value that matches the key changes nothing; a value that contradicts it returns `400 TEST_MODE_MISMATCH`.

Headers

Header	Description
Authorization*	`Bearer sk_live_…` or `Bearer sk_test_…`. Alternative: `X-API-Key: sk_…`. Send one of the two.
Content-Type	`application/json`
Idempotency-Key	A key you choose, up to 255 characters, that makes retries safe (see below).

Send an Idempotency-Key header so that a retry after a timeout does not create a second session. A repeat with the same key and the same body within 24 hours returns the stored response — the same session — with the idempotent-replay: true header. The same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED; a repeat while the first request is still running returns 409 IDEMPOTENCY_IN_PROGRESS. Errors are not stored, so a request that failed can be repeated with the same key. Use a new key for every new session: a session expires after 30 minutes, but its stored response is returned for 24 hours.

Response

Field	Type	Description
id	string	Session ID (`cs_…`). Use it with `GET /v2/payments/checkout/{id}`; payments made on the page use it as their ID in webhooks and refunds.
checkout_url	string	Payment page address. Redirect the customer here.
expires_at	datetime	30 minutes after creation. After that the session cannot be opened or paid, and `GET /v2/payments/checkout/{id}` returns `404`.
amount	integer	Echoed from the request.
currency	string	Echoed from the request.
status	string	`open` for a new session.
livemode	boolean	`true` for a live key, `false` for a test key.

With a test key (sk_test_) the session opens the same MAXFI payment page, but no money moves: pay with the test cards; steps that a bank or wallet would show open a MAXFI test page where you choose the result. Responses and webhook events carry "livemode": false.

Errors

HTTP	Code	Reason
400	VALIDATION_ERROR	The body does not match the schema: amount, currency, URL format, field length, or an unknown method code in `initial_method` or `settings.payment_methods`.
400	BAD_REQUEST	The channel in `channel_id` was not found, or it is paused, deleted or inactive.
400	CURRENCY_NOT_ALLOWED	The currency is not enabled for the channel of the payment. The channel’s currencies are set in the merchant portal, on the Channels page.
400	TEST_MODE_MISMATCH	`test_mode` contradicts the mode of the key.
400	UNSUPPORTED_PARAMETER	The request has `settings.button_text`, `settings.auto_return` or `settings.customer_fields`.
400	PAYMENT_METHODS_UNAVAILABLE	None of the methods in `settings.payment_methods` is available for this payment.
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	A live key before live mode is enabled, a channel-bound key with another channel’s `channel_id`, or a restricted key without `payments:write`.
409	LIVE_PAYMENTS_NOT_CONFIGURED	A live key, but live payments are not set up for your account yet. Contact MAXFI.
409	IDEMPOTENCY_KEY_REUSED	The `Idempotency-Key` was already used with a different request.
409	IDEMPOTENCY_IN_PROGRESS	A request with the same `Idempotency-Key` is still being processed. Retry later.
429	RATE_LIMIT_EXCEEDED	More than 100 requests in 60 seconds from your IP address.
500	INTERNAL_ERROR	Unexpected error. Retry later and quote `request_id` to support.