Payouts with our widget
If you cannot comply with all the PCI DSS requirements, use our tokenization widget. The widget securely collects bank card data and returns it in a tokenized form. Use the received token for further payouts.
Step 1. Generate a public token
The public token is needed to work with the widget. Send a token request to create a token, specifying the tokenize_widget
widget type. You will receive a 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 widget on your site
To do this, initialize the widget using the public token you obtained at the previous step.
After this, the recipient can enter their bank card details into the widget form.
How to add the tokenization widget >
Step 3. 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.
Creating a session
- cURL
- PHP
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 '{
"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 4. 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 received from the widget.
You can find information on the token or card using 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
- PHP
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": "encrypted_card",
"encrypted_card": {
"number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09",
"expiration_date_hash": "f4286b9a8e0eb7974f34a996ee732fd861868f2fc7aaa7ed5cca8de2489534ad",
"cardholder_name_hash": "dd6cce1e06790019dd266c6f70430f87dd378df802c6b7494395156f62533ce6",
"security_code_hash": "7756b897e88c035f34c6658a147e263b29b480a5cdf76581012ff10ede478c4c"
}
}
},
"metadata": "good"
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\EncryptedCard;
$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()
->startPayoutSession('session_id')
->setCard(
new EncryptedCard(
'number_hash',
'expiration_date_hash',
'cardholder_name_hash',
'security_code_hash'
)
)
->setMetadata('good')
->build();
$response = $client->session()->startPayout($request);
Step 5. 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": "user@gmail.com"
}]
},
"payment_method": {
"type": "card",
"card": {
"last4": "4242",
"brand": "visa"
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"metadata": "good"
}]
}
}'
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::READY_TO_CONFIRM) {
//do your logic here
}
Step 6. 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
).
Confirming the session
- cURL
- PHP
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"
}'
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');
Canceling the session
- cURL
- PHP
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"
}'
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 7. 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.
More about the 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
}