Methods · Documentation

When processing requests, the system checks for valid input parameters, the presence of the necessary headers, and rights to perform operations.

Performing operations

`session/create`

Payment session creation

Creates a payment session on Bank 131's side.

Payment operations can only be performed in a session. One or more operations of the same or different types can be performed within the session (e.g. several payouts, a payment and a refund, or a payment which is subsequently split).

Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details.

If you are ready to provide all the data needed to perform the operation in the request, you can use the method whereby the payout (session/start/payout) or the payment (session/start/payment) starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request.

The response contains the parameters of the created session.

Endpoint

api/v1/session/create

Request parameters

Name	Mandatory	Type	Description
payment_method	-	PaymentMethod	Payment details (card, customer account etc.)
amount_details	-	AmountDetails	The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify `10000`
fiscalization_details	-	FiscalizationDetails	Fiscalization details; only for payouts to the self-employed
participant_details	-	ParticipantDetails	Information about the participants (the payer and the recipient)
customer	-	Customer	The recipient's data in your system.
metadata	-	*	Additional information. Any data you need to perform the operation. Returned in responses and webhooks

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example

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: 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()  //OR ->createPayoutSession()
    ->setAmount(10000, 'rub')
    ->setMetadata('order123')
    ->build();

$response = $client->session()->create($request);

Successful response example

{
    "status": "ok",
    "session": {
        "id": "3230",
        "status": "created",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
    }
}

Unsuccessful response example

{
    "error": {
        "code": "invalid_request",
        "description": "customer.reference.not_blank"
    },
    "status": "error"
}

`session/init/payout`

Session creation with simultaneous payout initiation

This request can be used if you are ready to pass all the parameters needed for the payout at once, for example when transferring a payout to a Russian bank account. For payouts to bank cards, this is only possible if you have PCI DSS.

The response contains the parameters of the session created and an object with the information about the payout (Payment).

Endpoint

/api/v1/session/init/payout

Request parameters

Name	Mandatory	Type	Description
payment_method	-	PaymentMethod	Payment details (card, customer account etc.)
amount_details	-	AmountDetails	The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify `10000`
fiscalization_details	-	FiscalizationDetails	Fiscalization details
participant_details	-	ParticipantDetails	Information about the participants (the payer and the recipient)
customer	-	Customer	The recipient's data in your system.
metadata	-	*	Additional information. Any data you need to perform the operation. Returned in responses and webhooks

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
payment	-	PaymentMethod	Payout details (card, customer account etc.)
error	-	Error	The error

Request example

cURL

PHP

  https://demo.bank131.ru/api/v1/session/init/payout \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
    "payment_method": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "4242424242424242"
            }
        }
    },
    "participant_details": {
        "recipient": {
            "full_name": "Ivanov Ivan"
        }
    }
}'

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()
    ->initPayoutSession()
    ->setCard(new BankCard('4242424242424242'))
    ->setAmount(1000, 'rub')
    ->build();

$response = $client->session()->initPayout($request);

Successful response example

{
    "status": "ok",
    "session": {
        "id": "3230",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "payments": [
            {
                "id": "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": {
                        "last4": "4242",
                        "brand": "visa"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "metadata": "good"
            }
        ]
    }
}

`session/init/payout/fiscalization`

Session creation and payout start, with additional check that all the fiscalization data have been provided

Can be used for payouts to self-employed people if you are ready to provide all the information about the self-employed person and the details necessary to create the payout at once, for example when transferring a payout to a Russian bank account. For payouts to bank cards, this is only possible if you have PCI DSS.

The response contains the parameters of the session created and an object with the information about the payout (Payment) with the data necessary to send the receipt.

Endpoint

/api/v1/session/init/payout/fiscalization

Name	Mandatory	Type	Description
payment_method	-	PaymentMethod	Payment details (card, customer account etc.)
amount_details	-	AmountDetails	The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify `10000`
fiscalization_details	-	FiscalizationDetails	Fiscalization details
participant_details	-	ParticipantDetails	Information about the participants (the payer and the recipient)
customer	-	Customer	The recipient's data in your system.
metadata	-	*	Additional information. Any data you need to perform the operation. Returned in responses and webhooks

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
payment	-	PaymentMethod	Payout details (card, customer account etc.)
error	-	Error	The error

Request example

cURL

PHP

curl -X POST \
  https://demo.bank131.ru/api/v1/session/init/payout/fiscalization \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
    "fiscalization_details": {
        "professional_income_taxpayer": {
            "tax_reference": "590000000000",
            "payer_type": "legal",
            "payer_tax_number": "3300000000",
            "payer_name": "OOO Roga and Kopyta",
            "services": [
                {
                    "name": "Service description",
                    "amount_details": {
                        "amount": 10000,
                        "currency": "rub"
                    }
                }
            ]
        }
    },
    "payment_method": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "4242424242424242"
            }
        }
    },
    "amount_details": {
        "amount": 10000,
        "currency": "rub"
    },
    "metadata": "order123",
    "participant_details": {
        "recipient": {
            "full_name": "Ivanov Ivan"
        }
    }
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;
use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection;
use Bank131\SDK\DTO\FiscalizationService;
use Bank131\SDK\DTO\Participant;
use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer;


$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$services   = new FiscalizationServiceCollection();
$services[] = new FiscalizationService(
    'Delivery',
    new Amount(5000, 'rub'),
    1
);

$incomeInformation = new ProfessionalIncomeTaxpayer(
    $services,
    '590000000000'
);

$incomeInformation->setPayerName('OOO Roga and Kopyta');
$incomeInformation->setPayerType('legal');
$incomeInformation->setPayerTaxNumber('330000000000');

$recipient = new Participant();
$recipient->setFullName('Ivanov Ivan');

$request = RequestBuilderFactory::create()
    ->initPayoutSessionWithFiscalization()
    ->setIncomeInformation($incomeInformation)
    ->setCard(new BankCard('4242424242424242'))
    ->setAmount(5000, 'rub')
    ->setRecipient($recipient)
    ->setMetadata('good')
    ->build();

$response = $client->session()->create($request);

Successful 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",
        "payments": [
            {
                "id": "po_2909",
                "status": "in_progress",
                "created_at": "2018-05-27T02:03:00.000000Z",
                "payment_method": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "4242"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "fiscalization_details": {
                    "professional_income_taxpayer": {
                        "tax_reference": "590000000000",
                        "payer_type": "legal",
                        "payer_tax_number": "3300000000",
                        "payer_name": "OOO Roga and Kopyta",
                        "services": [
                            {
                                "name": "Service description",
                                "amount_details": {
                                    "amount": 10000,
                                    "currency": "rub"
                                }
                            }
                        ]
                    }
                },
                "metadata": "order123",
                "participant_details": {
                    "recipient": {
                        "full_name": "Ivanov Ivan"
                    }
                }
            }
        ]
    }
}

Unsuccessful response example

{
    "error": {
        "code": "invalid_request",
        "description": "participant_details.recipient.full_name.not_blank"
    },
    "status": "error"
}

`session/start/payout`

Payout start

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed.

If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request.

Endpoint

/api/v1/session/start/payout

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier
payment_method	-	PaymentMethod	Payout details (card, customer account etc.)
amount_details	-	AmountDetails	The amount
participant_details	-	ParticipantDetails	Information on payout participants
customer	-	Customer	The recipient's data in your system.
metadata	-	*	Additional information. Any data you need to perform the operation. Returned in responses and webhooks

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example

cURL

PHP

curl --location --request POST 'https://demo.bank131.ru/api/v1/session/start/payout' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: fd582e8a6619830e1e506ee68ece1ae0e2124f9047688617f7cf803ee492b9dd' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
    "session_id": "3230"
}'

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()
    ->startPayoutSession('session_id')
    ->build();

$response = $client->session()->create($request);

Successful response example

{
    "status": "ok",
    "session": {
        "id": "3230",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "payments": [
            {
                "id": "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": {
                        "last4": "4242",
                        "brand": "visa"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "metadata": "good"
            }
        ]
    }
}

`session/start/payout/fiscalization`

Payout start, with check that all fiscalization data have been provided

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed.

If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request.

Endpoint

/api/v1/session/start/payout/fiscalization

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier
payment_method	-	PaymentMethod	Payment details (card, customer account etc.)
amount_details	-	AmountDetails	The amount
fiscalization_details	-	FiscalizationDetails	Fiscalization details
participant_details	-	ParticipantDetails	Information on payout participants
customer	-	Customer	The recipient's data in your system.
metadata	-	*	Additional information. Any data you need to perform the operation. Returned in responses and webhooks

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example

cURL

PHP

curl --location --request POST 'https://demo.bank131.ru/api/v1/session/start/payout/fiscalization' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: 1cc6297fb447f038fd51f9e49d51fad3a0a37dfb801e6c830a2748e0b695a83b' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
    "session_id": "3230",
    "fiscalization_details": {
        "professional_income_taxpayer": {
            "tax_reference": "590000000000",
            "payer_type": "legal",
            "payer_tax_number": "330000000000",
            "payer_name": "OOO Roga and Kopyta",
            "services": [
                {
                    "name": "Goods delivery",
                    "amount_details": {
                        "amount": 5000,
                        "currency": "rub"
                    }
                }
            ]
        }
    }
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection;
use Bank131\SDK\DTO\FiscalizationService;
use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$services   = new FiscalizationServiceCollection();
$services[] = new FiscalizationService(
    'Delivery',
    new Amount(5000, 'rub'),
    1
);

$incomeInformation = new ProfessionalIncomeTaxpayer(
    $services,
    '590000000000'
);

$incomeInformation->setPayerName('OOO Roga and Kopyta');
$incomeInformation->setPayerType('legal');
$incomeInformation->setPayerTaxNumber('330000000000');

$request = RequestBuilderFactory::create()
    ->startPayoutSessionWithFiscalization('3230', $incomeInformation)
    ->build();

$response = $client->session()->create($request);

Successful response example

{
    "status": "ok",
    "session": {
        "id": "3230",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "payments": [
            {
                "id": "203",
                "status": "in_progress",
                "created_at": "2018-05-27T02:03:00.000000Z",
                "payment_method": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "4242"
                    }
                },
                "amount_details": {
                    "amount": 5000,
                    "currency": "rub"
                },
                "fiscalization_details": {
                    "professional_income_taxpayer": {
                        "services": [
                            {
                                "name": "Goods delivery",
                                "amount_details": {
                                    "amount": 5000,
                                    "currency": "rub"
                                },
                                "quantity": 1
                            }
                        ],
                        "tax_reference": "590613976192",
                        "payer_type": "legal",
                        "payer_tax_number": "3316004710",
                        "payer_name": "ООО Roga and Kopyta"
                    }
                }
            }
        ]
    }
}

`session/init/payment`

Session creation with simultaneous payout initiation

Can be used if you are ready to pass all the parameters needed for the payment at once, e.g. when paying with a bank card if you have PCI DSS.

The response contains the parameters of the session created and an object with information about the payment (AcquiringPayment).

Request parameters

Name	Mandatory	Type	Description
payment_details	+	PaymentDetails	Payment data
amount_details	+	AmountDetails	The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify `10000`
participant_details	-	ParticipantDetails	Participants information
customer	+	Customer	Client data in your system
payment_options	-	PaymentOptions	Additional payment parameters
metadata	-	*	Additional information. Any data you need to perform the operation. Returned in responses and webhooks

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example

cURL

PHP

curl --location --request POST 'https://demo.bank131.ru/api/v1/session/init/payment' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: key' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
    "payment_details": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "4242424242424242",
                "expiration_month": "05",
                "expiration_year": "22",
                "security_code": "123"
            }
        }
    },
    "amount_details": {
        "amount": 10000,
        "currency": "rub"
    },
    "customer": {
        "reference": "lucky"
    },
    "payment_options": {
        "return_url": "https://131.ru"
    }
}'

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

$paymentOptions = new PaymentOptions();
$paymentOptions->setReturnUrl('http://bank131.ru');

$request = RequestBuilderFactory::create()
    ->initPaymentSession()
    ->setCard(new BankCard('4242424242424242', '05', '22', '123'))
    ->setAmount(10000, 'rub')
    ->setCustomer(new Customer('lucky'))
    ->setPaymentOptions($paymentOptions)
    ->build();

$response = $client->session()->initPayout($request);

Successful 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",
        "acquiring_payments": [
            {
                "id": "pm_203",
                "status": "in_progress",
                "created_at": "2018-05-27T02:03:00.000000Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "4242"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "payment_options": {
                    "return_url": "https://131.ru"
                }
            }
        ]
    }
}

Unsuccessful response example

{
    "error": {
        "code": "invalid_request",
        "description": "customer.reference.not_blank"
    },
    "status": "error"
}

`session/init/payment/sync`

One-request payment

This method allows sending a payment request and get a response right away. Use it if you are ready to transmit all payment parameters in this request. e.g. when paying with a bank card if you have PCI DSS.

The response contains the parameters of the session created and the object AcquiringPayment with the payment result and information.

Request parameters

Only required request parameters are listed here. You can find additional parameters by following the links in object descriptions.

Name	Mandatory	Type	Description
payment_details	+	PaymentDetails	Payment data
type	+	string	Payment method type. Possible values: `card`
card	+	CardPaymentMethod	Object containing bank card details
type	+	string	Method of card information transmission. Value: `bank_card`
bank_card	+	BankCard	Object with open card information
number	+	string	Card number
expiration_month	+	string	Month of card expiration, `MM`. Example: `01`
expiration_year	+	string	Year of card expiration, `YY`. Example: `22`
security_code	+	string	CVC/CVV code
amount_details	+	AmountDetails	Object with payment amount
amount	+	int	The amount in ruble decimal format. The value must be greater than zero. If the payment amount is 100 rubles, you need to transmit `10,000`
currency	+	string	The ISO 4217 currency code. Case insensitive. Always: `rub`
participant_details	-	ParticipantDetails	Participants information
customer	+	Customer	Information about payment sender on your side
reference	+	string	Payment sender ID in your system
payment_options	+	PaymentOptions	Additional payment parameters
return_url	+	string	The URL to redirect the user to after the payment has been performed. The URL must be valid.
metadata	-	*	Additional information. Any data you need to perform the operation. Returned in responses and webhooks

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example

cURL

--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: project' \
--data-raw '{
    "payment_details": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "4242424242424242",
                "expiration_month": "01",
                "expiration_year": "22",
                "security_code": "123"
            }
        }
    },
    "amount_details": {
        "amount": 10000,
        "currency": "rub"
    },
    "customer": {
        "reference": "lucky"
    },
    "payment_options": {
        "return_url": "https://131.ru"
    }
}'

Successful response example

    "status": "ok",
    "session": {
        "id": "ps_3230",
        "status": "accepted",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "acquiring_payments": [
            {
                "id": "pm_203",
                "status": "succeeded",
                "created_at": "2018-05-27T02:03:00.000000Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "4242"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "payment_options": {
                    "return_url": "https://131.ru"
                }
            }
        ]
    }
}

Unsuccessful response example

{
    "error": {
        "code": "invalid_request",
        "description": "customer.reference.not_blank"
    },
    "status": "error"
}

`session/start/payment`

Payment start

This request can be used to start a payment within an existing session. In the parameters, you can pass the data necessary to perform the payment or change pieces of data that have already been passed.

Endpoint

/api/v1/session/start/payment

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier
payment_details	-	PaymentDetails	Payment data
amount_details	-	AmountDetails	The amount
participant_details	-	ParticipantDetails	Information about the participants (the payer and the recipient)
customer	-	Customer	Payment sender information in your system
metadata	-	*	Additional information. Any data you need to perform the operation. Returned in responses and webhooks

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example

cURL

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": "encrypted_card",
        "encrypted_card": {
            "number_hash": "asdfjasdoifapiodfhgphasdfpoighiodafhgdfgjsa;doifgoijhdsf;g",
            "expiration_date_hash":"dfkghd87fgya87sdgf76sadtf76gasdyfg67asdfasdf6s",
            "cardholder_name_hash":"jnsadbfnbasdfhjabsdfhbasdhbflahsbdflyabsdfuihasp[df",
            "security_code_hash":"adsfgsldkfjgposdfvpihsd;kfjvnkjsdfnvk;adf"
        }
    },
    "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 EncryptedCard(
            'number_hash',
            'expiration_date_hash',
            'cardholder_name_hash',
            'security_code_hash'
        )
    )
    ->setMetadata('good')
    ->build();

$response = $client->session()->startPayment($request);

Successful response example

{
    "status": "ok",
    "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": "in_progress",
                "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"
            }
        ]
    }
}

`session/confirm (confirm_request)`

Operation confirmation

This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, say you received a ready_to_confirm webhook.

You need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a confirm_request to Bank 131. If something is not right, cancel the operation by sending a cancel_request to Bank 131.

Endpoint

/api/v1/session/confirm

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session identifier

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example: confirm_request

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: 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');

Response example

{
    "status": "ok",
    "session": {
        "id": "3230",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "payments": [
            {
                "id": "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"
            }
        ]
    }
}

`session/capture (capture_request)`

Debiting amounts put on hold

This request can be used if you are sending payments with later capture. These payments are performed in two stages: first, the money is put on hold (for example, on the user's bank card), and then it is debited in response to your request.

The request can be sent when Bank 131 is ready to debit the money and has sent you a ready_to_capture webhook.

If you want to debit the amount put on hold, send a capture_request. You can debit the full amount on hold, or a portion of it.

To cancel the debit, send a cancel_request.

Endpoint

/api/v1/session/capture

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Bank 131 session identifier

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example: capture_request

cURL

PHP

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');

`session/cancel (cancel_request)`

Operation cancellation

This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, say you received a ready_to_confirm or a ready_to_capture webhook.

If you do not want to perform the operation, you can cancel it by sending a cancel_request.

If everything looks good, send a request to confirm the operation (confirm_request) or a request to debit the amount being put on hold (capture_request).

Endpoint

/api/v1/session/cancel

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session identifier

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example: cancel_request

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: 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');

Response example

{
    "status": "ok",
    "session": {
        "id": "3230",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "payments": [
            {
                "id": "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"
            }
        ]
    }
}

`session/refund`

Refund

You can use this request to return money to the user after a successful payment.

After completing the refund, Bank 131 will send you a payment_refunded webhook.

Endpoint

/api/v1/session/refund

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	The identifier of a successful payment session which needs to be refunded.
amount_details	-	AmountDetails	The amount of the refund. If not specified, the refund will be made for the full amount of the payment.
metadata	-	*	Additional information

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example

cURL

PHP

curl -X POST \
  https://demo.bank131.ru/api/v1/session/refund \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9871' \
  -d '{
    "session_id":"ps_3230"
}'

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()
    ->refundSession('ps_3230')
    ->build();

$response = $client->session()->refund($request);

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",
        "acquiring_payments": [
            {
                "id": "pm_2705",
                "status": "succeeded",
                "created_at": "2018-05-27T02:03:00.000000Z",
                "finished_at": "2018-05-27T02:03:00.000000Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "4242"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "refunds": [
                    {
                        "id": "rf_23",
                        "status": "in_progress",
                        "created_at": "2018-05-27T02:03:00.000000Z",
                        "amount_details": {
                            "amount": 10000,
                            "currency": "rub"
                        }
                    }
                ]
            }
        ]
    }
}

`token`

Generation of a token to work with widgets

The token is needed to access Bank 131's JavaScript library. You can generate it using this request and use it to work with widgets.

The token is only valid for a limited time. It can be used for a single operation. When sending a request, you should pass the parameters for working with widgets that you are going to use with that token.

Endpoint

/api/v1/token

Request parameters

Name	Mandatory	Type	Description
tokenize_widget	-	TokenizeWidgetMetadata	The data required by the tokenization widget
self_employed_widget	-	SelfEmployedWidgetMetadata	The data required by the self-employed registration widget
acquiring_widget	-	AcquiringWidgetMetadata	The data required by the payment form widget

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
public_token	-	string	The public token
error	-	Error	The error

An example of how to create a token to perform a payout which involves obtaining card details via the widget and linking a self-employed person

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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
    "tokenize_widget": {
      "access": true
    },
    "self_employed_widget":{
      "tax_reference": "111111111111"
    }
}'

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()
    ->setSelfEmployedWidget('111111111111')
    ->setAcquiringWidget(
        'test_ps_id',
        'http://success.url',
        'http://failed.url',
        false
    )
    ->build();

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

An example of a request to create a token to perform a payment through a payment form

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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
    "acquiring_widget": {
      "session_id": "ps_123456"
    }
}'

Successful response example

{
    "status": "ok",
    "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539"
}

Unsuccessful response example

{
    "status": "error",
    "error": {
        "description": "acquiring_widget.session_id.not_unique",
        "code": "invalid_request"
    }
}

Recurring payments

`recurrent/status`

Getting recurrent token status

This request helps find out whether a recurrent token is active (i.e. allows performing payments) and when it expires. Send the token in the request; the response will contain all the necessary information

Endpoint

/api/v1/recurrent/status

Request parameters

Name	Mandatory	Type	Description
recurrent	+	RecurrentDetails	Object with a token whose status needs to be checked

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
recurrent	+	RecurrentDetails	Object with a token

Request example

cURL

PHP

curl --location --request POST 'https://demo.bank131.ru/api/v1/recurrent/status' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
    "recurrent": {
        "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427"
    }
}'

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()
    ->recurrentStatusRequestBuilder()
    ->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39')
    ->build();

$response =  $client->recurrent()->getStatus($request);

Response example

{
    "recurrent": {
        "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39",
        "created_at": "2020-07-14T13:17:11+03:00",
        "finished_at": "2020-07-31T16:05:42+03:00",
        "is_active": true
    },
    "status": "ok"
}

`recurrent/disable`

Disable recurrent token

You can disable a recurrent token with this request. Send the token in the request, in the response you will get is_active: false. This means you cannot perform recurrent payments with this token.

Endpoint

/api/v1/recurrent/disable

Request parameters

Name	Mandatory	Type	Description
recurrent	+	RecurrentDetails	Object with a token

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
recurrent	+	RecurrentDetails	Object with a token

Request example

cURL

PHP

url --location --request POST 'https://demo.bank131.ru/api/v1/recurrent/disable' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
    "recurrent": {
        "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427"
    }

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()
    ->disableRecurrentRequestBuilder()
    ->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39')
    ->build();

$response =  $client->recurrent()->disable($request);

Response example

{
    "recurrent": {
        "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427",
        "created_at": "2020-07-14T13:17:11+03:00",
        "finished_at": "2020-07-31T16:05:42+03:00",
        "is_active": false
    },
    "status": "ok"
}

Information

`session/status`

Obtaining session information

You can send this request if you want to obtain full information about the payment session. For example, you can check whether the payout was completed, or check if you are able to debit the amount put on hold during a card payment.

The response contains the payment session with details about all the operations performed during it.

Endpoint

/api/v1/session/status

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
session	-	PaymentSession	The payment session
error	-	Error	The error

Request example: status_request

cURL

PHP

curl -X POST \
  https://demo.bank131.ru/api/v1/session/status \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
  -d '{
    "session_id": "3230"
}'

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

$response = $client->session()->status('session_id');

Successful response example

{
    "status": "ok",
    "session": {
        "id": "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": "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": {
                        "last4": "4242",
                        "brand": "visa"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "metadata": "good"
            }
        ]
    }
}

`wallet/balance`

You can use this request to identify your current Bank 131 deposit balance.

You need this to make sure there is enough money on the balance:

for mass payouts
for returns

If the amount is insufficient, you can top up your deposit.

Endpoint

/api/v1/wallet/balance

Request parameters

Name	Mandatory	Type	Description
request_datetime	+	string	The timestamp of the request

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Possible values: `error`, `ok`
wallets	-	WalletDetails	The list of guarantee payment accounts available at Bank 131.
error	-	Error	The error

Request example

cURL

PHP

curl -X POST \
  https://demo.bank131.ru/api/v1/wallet/balance \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9871' \
  -d '{
    "request_datetime":"2019-10-14T19:53:00+03:00"
}'

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

$walletBalanceResponse = $client->wallet()->balance();

$wallets = $walletBalanceResponse->getWallets();

Response example

{
    "status": "ok",
    "wallets": [
        {
            "id": "131",
            "amount_details": {
                "amount": 13100,
                "currency": "rub"
            }
        }
    ]
}

Self-employed people

`check` and `request/status`

Checking the status of a self-employed person

This request allows you to check whether an individual is self-employed or not, using their INN.

The requests consists of two parts:

First, you send a check request, passing the individual's INN in the tax_reference parameter, and receive a request_id identifier in response.
Then, you send a request/status request with this identifier. The response will tell you whether the INN is registered with the Federal Tax Agency as belonging to a self-employed person and whether it is linked to Bank 131.

The check request should not be sent more than once every 30 seconds.

The endpoint to send the check request to

/api/v1/npd/check

The check request parameters

Name	Mandatory	Type	Description
tax_reference	+	string	Individual's INN

Request example: check

curl -X POST \
  https://demo.bank131.ru/api/v1/npd/check \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "tax_reference": "123456789012"
}'

Example of response to: check

{
    "status": "ok",
    "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the request/status request to

api/v1/npd/request/status

The check request parameters

Name	Mandatory	Type	Description
request_id	+	string	The identifier received in response to the `check` request

Response parameters

Name	Mandatory	Type	Description
status	+	string	The status. Возможные варианты: `error`, `ok`, `pending`
is_professional_income_taxpayer	-	bool	Shows whether the individual is self-employed
is_linked	-	bool	Shows whether the self-employed person is linked to Bank 131
error	-	Error object	The error

Request example: request/status for check

curl -X POST \
  https://demo.bank131.ru/api/v1/npd/request/status \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

An example of a response to request/status for check: the individual is self-employed and is linked to Bank 131

{
    "status": "ok",
    "is_professional_income_taxpayer": true,
    "is_linked": true
}

An example of a response to request/status for check: the individual is self-employed but is not linked to Bank 131

{
    "status": "ok",
    "is_professional_income_taxpayer": true,
    "is_linked": false
}