Skip to main content

Payout to a bank card with a token

You can use this method if:

  • You already have a tokenized card number.

  • You accept payments, including recurring payments. In this case, you can use tokens for recurring payouts.

  • You have PCI DSS but its level does not allow you to store card data. To start using this method, contact your manager in Bank 131.

Note that:

  • This method does not depend on the project (X-PARTNER-PROJECT in the request header) within which you got the token.
  • You can also make payouts with a token from settlement accounts and escrow accounts.

Step 1. Generate a token​

If you have PCI DSS but its level does not allow you to store card data, use the tokenize/elements method to get a tokenized card number to further use it for payouts.

If you already have a token, skip this step.

Step 2. Create a payment session​

Send a session/create request.

Request example
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: signature' \
-d '{}'
Response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "created",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z"
  }
}

Step 3. Start the payout​

Send a session/start/payout request.

In the request, specify:

  • the session identifier received at the previous step in the request
  • one of the parameters depending on what data you have:

To get token details and the last 4 digits of the tokenized card, use the token/info method.

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: signature' \
-d '{
  "session_id": "ps_3230",
  "payment_method": {
    "type": "card",
    "card": {
      "type": "tokenized_card",
      "tokenized_card": {
        "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivanov Ivan"
    }
  },
  "metadata": "good"
}'
Response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "type": "tokenized_card",
            "tokenized_card": {
              "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44"
            }
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}'

When making payouts with a token, you can also use the following methods:

Step 4. Wait for a notification that the Bank is ready to perform the payout​

Bank 131 will send you a ready_to_confirm webhook (using the webhook 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 operation. The webhook body will contain all the details of the payout.

Reply with the 200 HTTP code.

Webhook example
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "ready_to_confirm",
  "session": {
    "id": "ps_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": "po_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user123@test.ru"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "type": "tokenized_card",
            "tokenized_card": {
              "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44"
            }
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}'

Step 5. Confirm or cancel the payout​

Check the payout details and either confirm it (using session/confirm), or cancel it (using session/cancel).

Example (session/confirm)
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: signature' \
-d '{
  "session_id": "ps_3230"
}'
Example (session/cancel)
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: signature' \
-d '{
  "session_id": "ps_3230"
}'

Step 6. Wait for the results​

Bank 131 will send you a payment_finished webhook. The webhook body will contain all the payout details. The payout result is in the payment.status field.

More about the payout statuses

Example of how to handle 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
}