What scenarios there are
Payouts via API can be performed using a token or without a token.
The choice of scenario depends on the how the payment is received and whether you have a PCI DSS security certificate.
Payout to a bank card without PCI DSS
In this case, you cannot store and send the recipient's bank card details with open parameters, which means the payout can only be performed using a token, via the tokenization widget.
The widget allows you to obtain the user's card details and pass them within your request in a secure tokenized form.
Payout to a bank card with PCI DSS, bank account, or QIWI wallet
No need to use a token: all the payout parameters can be passed with open parameters.
The payment session
All API operations are carried out within a payment session
PaymentSession) – payouts,
payments, and refunds. You can perform payouts in two ways:
- initiate the
payout when you start the session (as a single request,
create a session and only then perform the payout (making two
session/start/payout), for example, to immediately obtain the session identifier and use it to monitor what is happening with the payout.
Main payout scenario
These steps are necessary for payouts with the widget only
- You create the widget with this token, show it to the user, and obtain card details in tokenized form.
Tokenized card details can be saved so you can send money to that card later.
- You perform the payout however you prefer:
- either you first send a request for payment session creation
session/create), then a separate request for payout creation using this session's identifier (
- or you create the session and the payout simultaneously
In the request for payout creation, you pass the method of receiving the payment and all the parameters mandatory for that method.
- Bank 131 then sends you the
ready_to_confirmwebhook, which means that the Bank is ready to perform the payout and is waiting for your confirmation.
- You confirm
confirm_request) or cancel (
- Bank 131 sends you the
payment_finishedwebhook containing the result of the payout. If the status is
succeeded, the payout has been performed successfully.
The scenario of payouts to self-employed people
If you are paying out to self-employed people, the scenario will be slightly different.
- Before the start of the payout (at the very beginning), you check
that the person really is self-employed and is linked to Bank 131
(using their INN, with a couple of requests –
- If the INN belongs to the self-employed person but is not linked to Bank 131, you immediately link it using the special linking widget.
- If everything is fine, you perform the payout as in the general
scenario. Together with the payment, you send fiscalization details:
For payouts to bank accounts or to cards with PCI DSS, there is a
simplified scenario: you send the payout using the
and obtain the result from the
payment_finished webhook or
The status of the payout is returned in the
status field of the
Payment object. To query it, wait for a webhook from Bank 131 or send
session/status request with
the identifier of the session containing this payout. You can choose any
of these options or combine them as you wish.
Possible payout statuses: