Skip to main content

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).

In some cases, to accept payments you need to collect your users’ device fingerprints and pass them to the Bank. Contact your manager to find out whether it is required for you.

To automatically collect your users’ device fingerprints and pass them to the Bank, add the fp.js script to the payment page between the <head> and </head> tags as show in the following example. If a user passes several pages while making a payment, the script should be added to each of them:

<script src="https://widget.bank131.ru/fp.js" async></script>
Script example 
<html lang="ru">
  <head>
    <meta charset="utf-8" />
    <title>Example of adding the fp.js script | Bank 131</title>

    <meta
      name="description"
      content="E-commerce forms and elements integration examples. Bank 131."
    />

    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <meta name="format-detection" content="telephone=no" />

    <!-- Embedding the script. -->
    <script src="https://widget-demo.bank131.ru/fp.js" async></script>
  </head>

  <body>
    <main>
      <header>
        <h1>Example of adding the fp.js script</h1>
      </header>
    </main>
  </body>
</html>

A delayed capture payment (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 will send you a ready_to_capture webhook and 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.

Request headers should be used to pass your project identifier and the request's signature.

More about request format

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 '{
  "customer": {
    "reference": "user123",
    "contacts": [
      {
        "email": "user@gmail.com"
      }
    ]
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "metadata": "order123"
}'

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 payment_method.type field, specify card. In the bank_card object, transmit user's bank card details.

Starting a payout 
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": {
      "number": "4242424242424242",
      "expiration_month": "12",
      "expiration_year": "22",
      "security_code": "123",
      "cardholder_name": "John Doe"
    }
  },
  "customer": {
    "reference": "user123",
    "contacts": [
      {
        "email": "user@gmail.com"
      }
    ]
  },
  "metadata": "good"
}'

Step 3. Wait for notification that the Bank is ready to perform the payment​

Bank 131 will send you the 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 
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",
    "acquiring_payments": [
      {
        "id": "pm_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"
      }
    ]
  }
}'
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) {
    $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 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_3230"
}'
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_3230"
}'

Step 5. Lead the user through 3D Secure​

If the user's card requires 3D Secure, Bank 131 will send you a action_required webhook with redirection details. Redirect the user to the address that will be specified in the customer_interaction.redirect.url field.

Webhook example 
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "action_required",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_131",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "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"
            }
          }
        }
      }
    ]
  }
}'

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::ACTION_REQUIRED) {
    $session = $hook->getSession();
    //do your logic here
}

Step 6. Wait for a 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 
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "ready_to_capture",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_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"
      }
    ]
  }
}'
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_CAPTURE) {
    $session = $hook->getSession();
    //do your logic here
}

Step 7. Proceed with debiting, or cancel​

Debit the amount put on hold (session/capture) or cancel the capture (session/cancel).

Debiting the payment 
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: signature' \
-d '{
  "session_id": "ps_3230"
}'
Canceling the payment 
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 8. Learn the payment result​

Wait for a payment_finished webhook or request the payment status using the session/status method.

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.

More about payment statuses

All done, the payment has been performed.

Payment with PCI DSS (without a payment form)​

Payment with PCI DSS