Skip to main content

Payouts with a token

If you comply with all the PCI DSS requirements, but do not want to transmit card data directly to the Bank, you can create a token once and use it for payouts.

info

You can also make payouts with a token from your settlement and escrow accounts.

You can get a token:

A token does not depend on the project (X-PARTNER-PROJECT) within which it was created.

Step 1. Create a payment session​

Create a session using the session/create method. You will receive the payment session identifier in response. You will need it in the subsequent steps.

Alternatively, you can use the session/init/payout method to create a session and a payout at the same time. In this case, specify all the parameters for a payout with tokenized data right away and skip the next step. This option is not recommended.

If you make a payout from your escrow account, use the session/init/payout/nominal method, and if from your settlement account, use the session/init/payout/rko method. In this case, specify all the parameters for a payout with tokenized data right away and skip the next step.

Creating a session
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 2. Start the payout​

Start the payout using the session/start/payout method. Pass the session identifier along with all the parameters for a payout with tokenized data, including the token you have.

info

You can find information on the token or card through the token/info method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to.

Request example
curl -X POST \
  https://demo.bank131.ru/api/v1/session/start/payout \
  -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"
    }]
  }
}'

Step 3. Wait for a webhook saying the payout is ready​

Bank 131 will send you a ready_to_confirm webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel).

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 4. Confirm or cancel the payout​

Check the payout details and confirm that you are ready to perform the payout (session/confirm ) or cancel it (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 5. Wait for a webhook with the payout results​

Bank 131 will send you a payment_finished webhook. The result of the payout can be found in the status field of the payments/payout_list object.

If the status is succeeded, then the payout was successful. If the status is failed, then an error occurred during the payout.

How to fix an error >

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
}




Ask AI