Payout to a bank card with PCI DSS

This scenario describes how to perform a payout to a bank card if you can obtain and store bank card details on your side (i.e. you have a PCI DSS certificate).

In this case, you have two options: create a payment session and perform the payout with a single request; or create a payment session first, and then perform the payout.

Here, only one option is described, the one that involves creating a session separately.

Payout to a card with separate session creation

Step 1. Create a payment session

Send a request for session creation (session/create). You will receive the payment session identifier in response. More about payment sessions

Request headers should be used to pass your project identifier and the request's signature. More about request format

Request example: session creation

curl -X POST \
  https://demo.bank131.ru/api/v1/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
    "amount_details": {
        "amount": 10000,
        "currency": "rub"
    },
    "metadata": "order123"
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$request = RequestBuilderFactory::create()
    ->createPayoutSession()
    ->setAmount(10000, 'rub')
    ->setMetadata('order123')
    ->build();

$response = $client->session()->create($request);

Step 2. Begin the payout

Send a request to perform a payout using the session/start/payout method (you should use this method if the session has already been created). In the session_id parameter, pass the identifier of the session created in step 1. In the PaymentMethod.type parameter, pass the card value. In the BankCard object, pass the recipient's bank card details.

If you are sending money to a Russian bank card, you will need the following: card number; recipient's name; amount in ruble decimal format (e.g. if you are paying 100 rubles, you will need to pass 10000 in the amount_details.amount field).

View the parameters for payouts to Russian cards

If you are sending money to a foreign bank card, you will need the following: card number; recipient's name; amount in minor units – cents, kopecks, or other depending on the currency (e.g. if you are paying 100 euros, you will need to pass 10000 in the amount_details.amount field); currency code; payer details: name, company name, address, country, city; recipient's name.

View the parameters for payouts to foreign cards

Request example

curl -X POST \
  https://demo.bank131.ru/api/v1/session/start \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: e05794ee22f47ee5f674e63303ea227e6113f42359f332945304f1e958542fff' \
  -d '{
    "session_id": "3230",
    "payment_method": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "4242424242424242"
            }
        }
    },
    "participant_details": {
        "recipient": {
            "full_name": "Ivanov Ivan"
        }
    },
    "metadata": "good"
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;
use Bank131\SDK\DTO\Participant;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$participant = new Participant();
$participant->setFullName('Ivanov Ivan');

$request = RequestBuilderFactory::create()
    ->startPayoutSession('3230')
    ->setCard(new BankCard('4242424242424242'))
    ->setRecipient($participant)
    ->setMetadata('good')
    ->build();

$response = $client->session()->startPayout($request);

Step 3. Wait for notification that the Bank is ready to perform the payout

Bank 131 will send you the mandatory ready_to_confirm webhook (using the webhooks address you provided to your Bank 131 manager previously). This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). The webhook body will contain all the details of the payout.

You then reply with the 200 HTTP code.

Webhook example: ready_to_confirm

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -d '{
    "type": "ready_to_confirm",
    "session": {
        "id": "3230",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "next_action": "confirm",
        "payments": [
            {
                "id": "2018",
                "status": "pending",
                "created_at": "2018-05-27T02:03:00.000000Z",
                "customer": {
                    "reference": "user123",
                    "contacts": [
                        {
                            "email": "user@gmail.com"
                        }
                    ]
                },
                "payment_method": {
                    "type": "card",
                    "card": {
                        "last4": "4242",
                        "brand": "visa"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "metadata": "good"
            }
        ]
    }
}'

An example of handling a webhook using SDK

use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem'),
    file_get_contents('/path/to/bank131/public_key.pem')
);

$client = new Client($config);

$hook = $client->handleWebHook('sign from headers', 'request body');

if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) {
    $session = $hook->getSession();
    //do your logic here
}

Step 4. Confirm or cancel the payout

Check the payout details and confirm that you are ready to perform the payout (using the confirm_request request) or cancel it (using the cancel_request).

Request example: confirm_request

curl -X POST \
  https://demo.bank131.ru/api/v1/session/confirm \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
  -d '{
    "session_id": "3230"
}'
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$response = $client->session()->confirm('session_id');

Request example: cancel_request

curl -X POST \
  https://demo.bank131.ru/api/v1/session/cancel \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
  -d '{
    "session_id": "3230"
}'
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$response = $client->session()->cancel('session_id');

Step 5. Wait to be notified of the results of the payout

Bank 131 will send you the mandatory payment_finished webhook. The webhook body will contain all the details of the payout. The result of the payout can be found in the payment.status field.

If the status is succeeded, then the payout has been successful. If the status is failed, then the payout has not been completed because of an error.

More about payout statuses

An example of handling a webhook using SDK

use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem'),
    file_get_contents('/path/to/bank131/public_key.pem')
);

$client = new Client($config);

$hook = $client->handleWebHook('sign from headers', 'request body');

if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) {
    $session = $hook->getSession();
    //do your logic here
}
← Single-request payoutPayout to a self-employed person with fiscal receipt →