---
name: bank131-card-payments
description: Use when the user asks about accepting bank card payments: methods `session/create`, `session/init/payment`, `session/start/payment`, and the synchronous one-request mode `session/init/payment/sync`, card data in `payment_details`/`card`/`bank_card` (`number`, `expiration_month`, `expiration_year`, `security_code`), handling 3D Secure via `customer_interaction.redirect`, checking the result with `session/status`, and the difference between the regular flow and the sync mode (no webhooks, `payment_options.return_url`, `pending` status).
---

### How it works

This flow is for services that can collect and store card data on their own side (PCI DSS). If you do not want to handle card data yourself, use the Bank's payment form instead.

### Card payment flow (regular)

1. Create a session with `session/create`. In the response you get the session id.
2. Send the payment with `session/start/payment`, passing the `session_id` and the card data in `payment_details`.
3. Wait for the `ready_to_confirm` webhook — the Bank is ready to process the payment and is waiting for your confirmation. Respond with HTTP 200 OK.
4. Confirm the payment with `session/confirm` or cancel it with `session/cancel`.
5. If the user's card requires 3D Secure, you will get an `action_required` webhook with redirection data in `customer_interaction.redirect.url`. Redirect the user by that link.
6. Wait for the `payment_finished` webhook or check the status with `session/status`. The result is in the `status` field of the `acquiring_payments`/`payment_list` array: `succeeded` means the payment succeeded, `failed` means it failed due to an error.

You can create a session and send the payment at the same time — with `session/init/payment`. In this case pass all payment parameters at once and skip step 2.

### Card data

Card data (`payment_details`):

- `type` — `card`;
- `card.type` — `bank_card`;
- `card.bank_card.number` — the card number;
- `card.bank_card.expiration_month` — the expiry month;
- `card.bank_card.expiration_year` — the expiry year;
- `card.bank_card.security_code` — the card security code.

### 3D Secure

If the user's card requires 3D Secure, Bank 131 sends an `action_required` webhook. Its body contains `customer_interaction` with `type: redirect` and `redirect.url` — the address to redirect the user to for 3D Secure. After the user passes verification, the payment result comes in the `payment_finished` webhook or via `session/status`.

### Synchronous mode (session/init/payment/sync)

For services that want to send a payment with a single request and without intermediate steps, there is the `session/init/payment/sync` method. Inform the Bank 131 manager that you want to use it.

In this mode you will **not receive webhooks** from Bank 131. To find out the operation status, use `session/status`.

Send the request with:

- `payment_details` with `type: card` and the `bank_card` data;
- `payment_options.return_url` — **required**, the address to return the user to after the payment.

The payment result is returned directly in the response, in the `status` field of the `payments`/`payout_list` array:

- `succeeded` — the payment succeeded;
- `failed` — the payment failed due to an error;
- `pending` — the user needs to pass 3D Secure.

This method is not recommended unless you have already implemented it earlier.

### When the result does not come

Sometimes the final payment status is not returned in the response to the request:

- If the payment takes longer than 40 seconds, the response contains the intermediate status `in_progress`. Send `session/status` to find out the final status.
- If the user's card requires 3D Secure, the response contains redirection data. Redirect the user to `customer_interaction.redirect.url`, then send `session/status` to find out the final payment status.