Payout from an escrow account to a bank card

This scenario describes how to make a payout from an escrow account to a bank card. The payout consists of two transactions, first, the payment amount itself, and second, the payment commission. Details of both transactions are presented in the appropriate bank statement that can be accessed via the online bank.

You can obtain tokenized card details using the tokenization widget, and then send the payout securely.

Step 1. Generate a public token

The token is needed to work with the widget. Send a request to create a token, and use it to pass the type of widget you want to work with. You will receive the token in response.

Request example

cURL
PHP

curl -X POST \
http://demo.bank131.ru/api/v1/token \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tokenize_widget": {
    "access": true
  }
}'

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()
    ->issuePublicTokenBuilder()
    ->setTokenizeWidget()
    ->build();

$response    = $client->widget()->issuePublicToken($request);
$publicToken = $response->getPublicToken();

Step 2. Show the details collection form to the recipient

To do this, you will need to access our JavaScript library and add the tokenization widget to the page, where the recipient will then be able to fill in the form with their card details.

The recipient then enters their card details, and you will receive tokenized details that you can use to perform the payout.

You can initialize the widget using the token you have obtained at the previous step.

How to add the tokenization widget

Step 3. Begin the payout

Send a request for payment session creation (session/multi/create/nominal), then a separate request for payout creation using this session's identifier session/multi/start/payment/nominal. In the encrypted_card object, pass the tokenized bank card details obtained from the widget.

You can find information about the token or card through the token/info method. This includes receiving the last 4 digits of the card, in order to show the user the payment destination.

When paying from an escrow account, the beneficiary_id parameter is mandatory for any card type.

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. to pay 100 rubles, pass 10000 in the amount_details.amount field)

View the parameters for payouts to Russian cards

How to specify the beneficiary's details

Sending payouts from an escrow account requires you to specify the beneficiary's details, namely, the beneficiary's INN. You should pass the beneficiary's INN within the participant_details object as the sender's or recipient's details, depending on their role in the transaction. Before you send any payout from an escrow account, you should provide the list of your beneficiaries to your manager in Bank 131.

Creating a session

curl -X POST \
https://demo.bank131.ru//api/v1/session/multi/create/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_nominal_account",
      "transfer_from_nominal_account": {
        "description": "Purpose of payment"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "****************"
      }
    }
  },
  "participant_details": {
    "sender": {
      "full_name": "Sender's details",
      "beneficiary_id": "1234567890"
    },
    "recipient": {
      "full_name": "John Doe"
    }
  },
  "amount_details": {
    "amount": 293400,
    "currency": "USD"
  },
  "customer": {
    "reference": "123456789012"
  }
}'

Starting a payout

curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230",
  "metadata": "good"
}'

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

Bank 131 will send you a 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're recommended to keep the confirm_information object for confirmation purposes.

You then 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_14667043",
    "status": "in_progress",
    "created_at": "2022-09-14T09:32:19.891392Z",
    "updated_at": "2022-09-14T09:32:20.494410Z",
    "payments": [
      {
        "id": "po_7639847",
        "status": "pending",
        "created_at": "2022-09-14T09:32:20.100149Z",
        "customer": {
          "reference": "123456789012"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "mastercard",
            "last4": "8371",
            "country_iso3": "RUS"
          }
        },
        "amount_details": {
          "amount": 293400,
          "currency": "RUB"
        },
        "amounts": {
          "net": {
            "amount": 293400,
            "currency": "RUB"
          },
          "gross": {
            "amount": 293400,
            "currency": "RUB"
          }
        },
        "participant_details": {
          "sender": {
            "full_name": "ACME",
            "beneficiary_id": "123456789"
          },
          "recipient": {
            "full_name": "John Doe"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_6933973",
        "status": "pending",
        "created_at": "2022-09-14T09:32:20.099952Z",
        "customer": {
          "reference": "123456789012"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "Payment under the contract",
              "card_mask": "553691******8371"
            }
          }
        },
        "amount_details": {
          "amount": 293400,
          "currency": "RUB"
        },
        "amounts": {
          "net": {
            "amount": 293400,
            "currency": "RUB"
          },
          "gross": {
            "amount": 293400,
            "currency": "RUB"
          }
        },
        "participant_details": {
          "sender": {
            "full_name": "ACME",
            "beneficiary_id": "1234567890"
          },
          "recipient": {
            "full_name": "John Doe"
          }
        }
      }
    ],
    "next_action": "confirm"
  },
  "confirm_information": {
    "transfer_details": {
      "payment_method": {
        "type": "card",
        "card": {
          "brand": "mastercard",
          "last4": "8371",
          "country_iso3": "RUS"
        }
      },
      "customer": {
        "account_number": "40702810700200000000",
        "name": "ACME",
        "bank_name": "Bank 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "recipient": {
        "account_number": "30233810000000000000",
        "name": "Bank 131",
        "bank_name": "Bank 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "purpose": "Payment under the contract",
      "amount": {
        "amount": 293400,
        "currency": "RUB"
      }
    }
  }
}'

Step 5. Confirm or cancel the payout

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

Confirming the session

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_14667043",
  "confirm_information": {
    "transfer_details": {
      "payment_method": {
        "type": "card",
        "card": {
          "brand": "mastercard",
          "last4": "8371",
          "country_iso3": "RUS"
        }
      },
      "customer": {
        "account_number": "40702810700200000000",
        "name": "ACME",
        "bank_name": "Bank 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "recipient": {
        "account_number": "30233810000000000000",
        "name": "Bank 131",
        "bank_name": "Bank 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "purpose": "Payment under the contract",
      "amount": {
        "amount": 293400,
        "currency": "RUB"
      }
    }
  }
}'

Canceling the session

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_14667043",
  "confirm_information": {
    "transfer_details": {
      "payment_method": {
        "type": "card",
        "card": {
          "brand": "mastercard",
          "last4": "8371",
          "country_iso3": "RUS"
        }
      },
      "customer": {
        "account_number": "40702810700200000000",
        "name": "ACME",
        "bank_name": "Bank 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "recipient": {
        "account_number": "30233810000000000000",
        "name": "Bank 131",
        "bank_name": "Bank 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "purpose": "Payment under the contract",
      "amount": {
        "amount": 293400,
        "currency": "RUB"
      }
    }
  }
}'

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

Bank 131 will send you a 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.

Handling the 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
}

Step 1. Generate a public token​

Step 2. Show the details collection form to the recipient​

Step 3. Begin the payout​

How to specify the beneficiary's details​

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

Step 5. Confirm or cancel the payout​

Step 6. Wait to be notified of the results of the payout​