Payment methods

MAXFI has eight payment method codes. The MAXFI payment page shows the methods enabled for your account, so your integration stays the same whichever methods are switched on. The saved card is the exception: it is charged only through the API.

The same list is used by the Widget SDK.

Method codes

Every method_code is one of these:

Which methods a payment shows

MAXFI builds the list for each payment on its side. A method is shown only when all three conditions hold:

1. MAXFI has enabled it for your account.
2. The processing route used for your account supports it, and it is not switched off across the platform.
3. You have not switched it off in merchant portal → Settings → Payment methods. A method you have not changed there is shown.

Methods appear in the order you set on that page, otherwise in MAXFI’s default order. If you renamed a method there (in English, Russian or Azerbaijani), the payment page uses your name.

A session created with settings.payment_methods (POST /v2/payments/checkout) shows only the methods from that list that meet these conditions, and refuses payment by any other method. initial_method chooses which of them opens first.

SBP, SberPay, T-Pay and YooMoney are offered only for payments in RUB: a payment in another currency does not show them.

The saved card (recurrent) is not offered on the payment page or in the widget window, in test or live mode, and it is never in the method list of a session. Charge a saved card from your server with POST /v2/payments (payment_method_data.recurrent).

In test mode the payment page offers the methods of the MAXFI test environment — all except Apple Pay, Google Pay and the saved card — unless you have switched them off in merchant portal → Settings → Payment methods. The Apple Pay and Google Pay buttons need your registration with Apple and Google, so in test mode these two methods, like the saved card, are tested only through POST /v2/payments. Test cards, test phone numbers and the MAXFI test page are described in the Quickstart.

Methods that need extra setup

Some methods can be switched on only after extra setup — for example Apple Pay and Google Pay, which need registration with Apple and Google. Until MAXFI completes it for your account, merchant portal → Settings → Payment methods shows the method as “Awaiting verification” (or “Needs contract” when a separate agreement is required), and you cannot switch it on. To start the setup, contact MAXFI.

Once the setup is complete, the payment page shows the Apple Pay or Google Pay button to customers whose browser and device support it. Your integration does not change.

Method list of a session

The payment page loads its list from GET /checkout/{sessionId}/methods. The session id identifies the payment, so no API key is needed. You can call this endpoint from your server or app too, for example to check what a session will show.

curl https://maxfi-api.exezine.az/checkout/cs_4f0c9a2e7b1d4e8f9a6b3c5d7e9f1a2b/methods

# Response for a session in RUB
{
  "data": [
    {
      "code": "card",
      "display_name": { "en": "Card", "ru": "Карта", "az": "Kart" },
      "icon": "…",
      "render_mode": "inline_form",
      "required": {
        "cardData": true, "phone": false, "email": false,
        "savedToken": false, "bankSelection": false
      },
      "features": {
        "preauth": true, "refund": true,
        "partialRefund": true, "recurring": true
      },
      "display_order": 1
    },
    {
      "code": "sbp",
      "display_name": {
        "en": "SBP QR (Faster Payments)",
        "ru": "СБП — Система быстрых платежей",
        "az": "SBP (Cəld Ödənişlər Sistemi)"
      },
      "icon": "…",
      "render_mode": "qr_code",
      "required": {
        "cardData": false, "phone": false, "email": false,
        "savedToken": false, "bankSelection": false
      },
      "features": {
        "preauth": false, "refund": true,
        "partialRefund": true, "recurring": false
      },
      "display_order": 2
    }
  ],
  "total": 2,
  "default_code": "card"
}

default_code is the method the page opens first: initial_method from the query string or, if it is absent or not in the list, the initial_method of the session; if that is not in the list either, the first method. If the session was created with settings.payment_methods, the list contains only those methods. If MAXFI cannot build the list, the response is data: [], total: 0, default_code: null and unavailable: true, and the payment page shows the card form. An unknown session returns 404.

Paying with another method

Card details go only through the MAXFI payment page. For every other method the page calls POST /checkout/{sessionId}/submit-method with method_code and a payload object:

curl https://maxfi-api.exezine.az/checkout/cs_4f0c9a2e7b1d4e8f9a6b3c5d7e9f1a2b/submit-method \
  -H "Content-Type: application/json" \
  -d '{
    "method_code": "sbp",
    "payload": { "dynamic": true }
  }'

# Response: show the QR code, then poll /status
{
  "status": "requires_action",
  "next_action": {
    "type": "show_qr",
    "image_data_url": "data:image/png;base64,iVBORw0KGgo…",
    "raw_payload": "https://qr.nspk.ru/…",
    "deeplink": "https://qr.nspk.ru/…"
  }
}

The response contains status — processing, requires_action, succeeded or failed — plus next_action when the customer has to do something and error_message when the payment failed.

A session takes one submit-method call, before any payment on it has started. Otherwise the response is 409: the session has already finished, or a payment on it is in progress (payment_in_progress). A missing method_code, method_code: "card" or a method outside the session’s settings.payment_methods returns 400; an unknown session returns 404. A method that is not available for the payment — switched off for your account or, like SBP, SberPay, T-Pay and YooMoney, not offered in its currency — ends the payment with a decline: the response has status: failed.

next_action

next_action tells the payment page what to show next. type is one of:

next_action can be missing, for example when the payment has already succeeded or failed. GET /checkout/{sessionId}/status returns it too.

SBP: choosing the bank

SBP works only in RUB. So that the customer can open their bank’s app directly, the payment page shows popular SBP banks. Two endpoints return this list (limit: 12 by default, up to 50):

• GET /checkout/{sessionId}/sbp-members?limit=12 — by session id, no API key. For a session not in RUB it returns an empty list and currency_supported: false.
• GET /widget/v1/sbp-members?limit=12 — with your secret key, from your server only.

curl "https://maxfi-api.exezine.az/checkout/cs_4f0c9a2e7b1d4e8f9a6b3c5d7e9f1a2b/sbp-members?limit=1"

# Response
{
  "data": [
    {
      "member_id": "100000000111",
      "name": { "en": "…", "ru": "…", "az": "…" },
      "logo_url": "https://…",
      "deeplink_ios": "…",
      "deeplink_android": "…",
      "is_popular": true,
      "display_order": 1
    }
  ],
  "count": 1,
  "currency_supported": true
}

Each bank has member_id, name, logo_url, deeplink_ios, deeplink_android, is_popular and display_order (name in en, ru and az). The chosen bank’s member_id goes to submit-method as payload.extra.memberId; MAXFI checks it against its list of SBP participants before sending the payment.

curl https://maxfi-api.exezine.az/checkout/cs_4f0c9a2e7b1d4e8f9a6b3c5d7e9f1a2b/submit-method \
  -H "Content-Type: application/json" \
  -d '{
    "method_code": "sbp",
    "payload": {
      "dynamic": true,
      "extra": { "memberId": "100000000111" }
    }
  }'

Widget SDK

The Widget SDK (/widget/v1/maxfi.js) wraps all of this. Your server creates the session with your secret key; the page loads the SDK with your publishable key, shows the method picker in a window and opens the payment page for that session in a frame. Card details never pass through your page — the frame handles them. The SDK refuses secret keys.

List your sites first. The payment page opens in a frame only on sites you add in merchant portal → Form Builder → Sites allowed to embed (https://shop.example.com or https://*.example.com, up to 20). On any other site the browser blocks the frame. Sending the customer to the checkout URL works without this list.

In the widget window the customer picks a method, and the payment page opens on it. initial_method passed when your server creates the session (POST /widget/v1/session, secret key) applies when the picked method is not available for the session, when the window could not offer methods (then it shows no method tabs) or when the customer opens the session’s checkout_url directly. Full guide: Widget SDK.

<script src="https://maxfi-api.exezine.az/widget/v1/maxfi.js"></script>
<script>
  const maxfi = new Maxfi("pk_live_…");   // publishable key only
  document.getElementById("pay-button").onclick = () =>
    maxfi.openCheckout({
      // your server: POST /widget/v1/session with { amount: 49000, currency: "RUB" }
      // and the secret key, returns { session_id }
      fetchSession: () => fetch("/create-maxfi-session", { method: "POST" }).then(r => r.json()),
      amount: 49000,                     // window header only
      currency: "RUB",                   // header + methods available in RUB
    });
</script>