Paying with PCI DSS
This scenario describes how bank card payments are accepted and processed by PCI DSS certificate services (using this certificate, you can collect and store card data on your side).
A payment with later capture (a payment where funds are frozen on the card and then debited) is described here. You can skip this step.
This payment is subject to approval: When the bank is ready to accept the payment, it sends you a webhook
ready_to_captureand waits for a response (see Steps 4–5). You can exclude this step and process all payments following the other scenario: without approval.
Step 1. Create a payment session
Send a request for session creation (session/create). You will receive the payment session identifier in response. You can perform several actions within a single session: for example, you can accept and then refund a payment.
Request headers should be used to pass your project identifier and the request's signature.
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()
->createPaymentSession()
->setAmount(10000, 'rub')
->setMetadata('order123')
->build();
$response = $client->session()->create($request);
Step 2. Initiate a payment
Send a request to perform a payment using the session/start/payment method (this method works if a session has been created). In the session_id parameter, pass the identifier of the session created in step 1. In the field payment_method.type, specify the value card. In the object card, transmit user's bank card details.
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": {
"number": "4242424242424242",
"expiration_month":"12",
"expiration_year":"22",
"security_code":"123",
"cardholder_name":"John Doe"
}
},
"customer": {
"reference": "lucky"
},
"metadata": "good"
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;
$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()
->startPaymentSession('session_id')
->setCard(
new BankCard(
'4242424242424242',
'02',
'22',
'123',
'cardholder name'
)
)
->setCustomer(new Customer('lucky'))
->setMetadata('good')
->build();
$response = $client->session()->startPayment($request);
Step 3. Wait for notification that the Bank is ready to perform the payment
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 payment can be performed and the Bank is waiting for you to confirm (or cancel).
The webhook body will contain all the data needed for the payment, which you need to check.
You then reply with the 200 HTTP code.
Webhook example: ready_to_confirm
ccurl -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",
"acquiring_payments": [
{
"id": "2018",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_details": {
"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 payment
Check the payment details and confirm that you are ready to perform the payment (using the confirm_request request) or cancel it (using the cancel_request 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. Lead the user through 3D Secure
If the user's card requires 3D Secure, Bank 131 will send you the webhook action_required with redirection details. Redirect the user to the address that will be specified in the field customer_interaction.redirect.url.
Webhook example: action_required
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "action_required",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [{
"id": "131",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference":"user@131.ru"
},
"payment_details": {
"type": "card",
"card": {
"brand": "visa",
"last4": "8801"
}
},
"amount_details": {
"amount": 15000,
"currency": "rub"
},
"customer_interaction": {
"type": "redirect",
"redirect": {
"url": "https://bank131.ru?foo=bar",
"base_url": "https://bank131.ru"
"method": "POST",
"qs": {
"foo": "bar"
},
"params": {
"paReq": "sdfew^//asdhbv",
"MD": "abc75daefnn"
}
}
}
}]
}
}
}'
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::ACTION_REQUIRED) {
$session = $hook->getSession();
//do your logic here
}
Step 6. Wait for the ready_to_capture webhook
Through the ready_to_capture, webhook, Bank 131 informs you that the payment amount has successfully been put on hold on the user's bank card.
Webhook example: ready_to_capture
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_capture",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [
{
"id": "2018",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_details": {
"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_CAPTURE) {
$session = $hook->getSession();
//do your logic here
}
Step 7. Proceed with debiting, or cancel
Debit the amount put on hold (capture_request) or cancel the capture (cancel_request).
Request example: capture_request
curl -X POST \
https://demo.bank131.ru/api/v1/session/capture \
-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()->capture('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 8. Learn the payment result
Wait for the webhook payment_finished or request the payment status using the method session/status.
The result of the payment can be found in the payment.status field.
If the status is succeeded, then the payment has been successful. If the status is failed, then the payment has not been completed because of an error.
All done, the payment has been performed.
Payment with PCI DSS (without a payment form)
