MAXFI Payments API — v2.0.0

One API for cards, wallets, BNPL, payouts and KYC. Hosted-checkout-first with first-class direct-API support. Idempotent, signed webhooks, deterministic sandbox.

Servers

- https://maxfi-api.exezine.az — Production (use sk_test_ keys for sandbox)

Endpoints

POST /v2/payments/checkout

Create a checkout session

Tags: Checkout

Operation ID: createCheckoutSession

GET /v2/payments/checkout/{id}

Get a checkout session

Tags: Checkout

Operation ID: getCheckoutSession

GET /checkout/{sessionId}/methods

Effective method catalog for a hosted checkout session

Tags: Payment Methods

Operation ID: getCheckoutMethods

Returns the list of payment methods actually enabled for this session. This is the intersection of Merchant Connector Account (MCA) allowed methods, global Connector Method Capability (CMC), and per-merchant MCS overrides. Called by the MAXFI Checkout page on load. Fail-open to card-only if the catalog lookup errors — end customers always see at least one method.

POST /checkout/{sessionId}/submit-method

Submit a non-card payment method (SBP, SberPay, TPay, YooMoney, Apple/Google Pay, recurrent)

Tags: Payment Methods

Operation ID: submitCheckoutMethod

Called by the MAXFI Checkout page when the end customer picks any method other than card. Card payments continue to use the PCI SAQ A-EP /checkout/:sessionId/pay endpoint with the 2-phase 3DS flow. Response carries next_action telling the browser whether to render a QR code, open a deeplink, redirect, show an ACS iframe or poll. The checkout page polls GET /checkout/:sessionId/status until the session settles into a terminal state.

POST /widget/v1/session

Bootstrap a widget session and return a hosted checkout URL

Tags: Widget

Operation ID: createWidgetSession

Called by the Widget SDK (Maxfi class, loaded from /widget/v1/maxfi.js) when the user clicks the Pay button. Creates a regular checkout session and returns its URL so the widget can embed /checkout/:sessionId in an iframe. Accepts initial_method to pre-select a tab on the checkout page — handy when the widget renders its own method picker.

GET /widget/v1/methods

Effective method catalog for the authenticated merchant (widget context)

Tags: Widget

Operation ID: getWidgetMethods

Returns the same shape as GET /checkout/:sessionId/methods but keyed by merchant (no session required). Fail-open to card-only on any lookup error.

GET /sbp/members

Full list of SBP (Faster Payments System) member banks

Tags: Payment Methods

Operation ID: listSbpMembers

Returns MAXFI's mirror of the public NSPK dictionary (qr.nspk.ru/proxyapp/c2bmembers.json). Includes every active SBP-connected bank with a 12-digit member_id (nspkId), localised names (en/ru/az), logo URL and iOS / Android deeplinks. Use this endpoint when you need to render your own bank picker before submitting an SBP payment, or when you want to validate a member_id server-side before calling MAXFI. No auth required — list is considered public information.

GET /sbp/members/popular

Top-N popular SBP member banks

Tags: Payment Methods

Operation ID: listSbpMembersPopular

Curated subset of /sbp/members sorted by display_order. MAXFI Ops maintains the popular list so hosted checkout can render a compact grid (top-12 banks by SBP traffic share) instead of the full 200-bank catalogue. Returns the same entry shape as /sbp/members.

GET /checkout/{sessionId}/sbp-members

SBP member banks scoped to a hosted checkout session

Tags: Payment Methods

Operation ID: getCheckoutSbpMembers

Same list as /sbp/members/popular but tied to a running checkout session. Returns an empty array and currency_supported: false when the session currency is not RUB (SBP is a ruble-only rail). Used by the MAXFI hosted checkout page to render the bank picker grid inside the SBP tab.

GET /widget/v1/sbp-members

SBP member banks for embedded Widget SDK

Tags: Widget

Operation ID: getWidgetSbpMembers

Authenticated with your publishable key. Returns the same popular-list shape as the public /sbp/members/popular endpoint, cached for 5 minutes on the CDN edge.

GET /v2/payments

List payments

Tags: Payments

Operation ID: listPayments

POST /v2/payments

Create a direct payment

Tags: Payments

Operation ID: createPayment

GET /v2/payments/{id}

Get a payment

Tags: Payments

Operation ID: getPayment

POST /v2/payments/{id}/capture

Capture an authorisation

Tags: Payments

Operation ID: capturePayment

POST /v2/payments/{id}/refund

Refund a payment (full or partial)

Tags: Payments

Operation ID: refundPayment

POST /v2/payments/{id}/cancel

Cancel an authorisation or pending payment

Tags: Payments

Operation ID: cancelPayment

POST /v2/payouts

Create a payout

Tags: Payouts

Operation ID: createPayout

GET /v1/balance

Get your balance

Tags: Balance

Operation ID: getBalance

Per-currency balances of the authenticated merchant, in minor units (4900 = 49.00). available can be paid out, pending is waiting for settlement, reserve is the rolling reserve. An empty balances array means no ledger accounts yet — they are created on the first successful payment. If the ledger is temporarily unavailable the API answers 503 BALANCE_UNAVAILABLE instead of zero balances: retry with backoff and never treat this response as an empty balance.

GET /v1/channels

List channels

Tags: Channels

Operation ID: listChannels

Returns all channels of the authenticated merchant. By default soft-deleted channels are excluded.

POST /v1/channels

Create a channel

Tags: Channels

Operation ID: createChannel

Slug (code) must be unique within your merchant. Returns the new Channel including the freshly minted public_id and webhook_secret (when set).

GET /v1/channels/{id}

Retrieve a channel

Tags: Channels

Operation ID: getChannel

id accepts the UUID, the ch_xxx public id, or the merchant-defined slug.

PATCH /v1/channels/{id}

Update a channel

Tags: Channels

Operation ID: updateChannel

Partial update — branding, webhook URL/secret/enabled, currencies, name. The code of the default channel is immutable.

DELETE /v1/channels/{id}

Soft-delete (default) or hard-delete (?hard=true)

Tags: Channels

Operation ID: deleteChannel

Soft-delete is reversible — the row stays in DB and restore brings it back. Hard-delete is blocked when MCAs / API keys / transactions still reference the channel; the response is 409 with a references array enumerating the blockers. The default channel cannot be deleted at all.

POST /v1/channels/{id}/promote-default

Make this channel the default

Tags: Channels

Operation ID: promoteChannelDefault

Demotes the previous default channel in the same call. The new default automatically inherits any unscoped requests.

POST /v1/channels/{id}/pause

Pause a channel

Tags: Channels

Operation ID: pauseChannel

Temporarily hides the channel from routing without losing any history. The default channel cannot be paused.

POST /v1/channels/{id}/resume

Resume a paused channel

Tags: Channels

Operation ID: resumeChannel

POST /v1/channels/{id}/restore

Restore a soft-deleted channel

Tags: Channels

Operation ID: restoreChannel

GET /v2/health

Service health

Tags: Health

Operation ID: health

GET /auth/me

Authenticated session profile (now includes counterparty_role_codes)

Tags: Auth

Operation ID: authMe

Returns the merchant-portal session profile. Since v3.0 the response includes counterparty_role_codes — the list of roles this counterparty currently holds in CRM. Merchant Portal access requires merchant to be in the list. During the rollout window tokens without the claim are accepted with a warning; once MERCHANT_ROLE_STRICT=true is set on the BFF the gate becomes hard.