Перейти к основному содержимому

Методы

При обработке запросов проверяется корректность входных параметров, наличие необходимых заголовков, права на выполнение действий.

Проведение операций​

session/create​

Cоздание платежной сессии​

Этот запрос создает платежную сессию на стороне Банка 131.

Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций одного или разных типов (например, несколько выплат, платеж и возврат, оплата с последующим разделением платежей).

Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты или оплаты. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату.

Если вы готовы передать в запросе все данные, которые нужны для проведения операции, можете использовать метод, при котором сразу после создания сессии стартует выплата (session/start/payout) или оплата (session/start/payment). В этом случае запускать операцию отдельным запросом не нужно.

В ответе возвращаются параметры созданной сессии.

Адрес для отправки запроса​

api/v1/session/create

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
amount_details-AmountDetailsСумма. Передается в минорных единицах. Если отправляете 100 рублей, евро или долларов США, нужно передать 10000
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
participant_details-ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
customerОбязательно для платежейCustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

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

Пример успешного ответа​

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

Пример неуспешного ответа​

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

session/init/payout​

Cоздание сессии с одновременным стартом выплаты​

Можно использовать этот запрос, если вы сразу готовы передать все параметры для создания выплаты. Например, при отправке выплаты на российский банковский счет. При выплате на банковскую карту — только если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии и объект с информацией о выплате (Payment).

Адрес для отправки запроса​

/api/v1/session/init/payout

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_method+PaymentMethodПлатежные данные (карта, банковский счет и др.)
amount_details+AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
fiscalization_details-FiscalizationDetailsДанные для фискализации
participant_details-ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
customer+CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
payment-PaymentMethodПлатёжные данные (карта, банковский счёт и др.)
error-ErrorОшибка

Пример запроса​

  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"
            }
        }
    },
    "amount_details": {
        "amount": 1000,
        "currency": "rub"
    },
    "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);

Пример успешного ответа​

{
    "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​

Создание сессии и старт выплаты с дополнительной проверкой заполненности данных для фискализации​

Можно использовать при выплатах самозанятым, если вы сразу готовы передать всю информацию о самозанятом и платежные данные для создания выплаты. Например, при отправке выплаты на российский банковский счет. При выплате на банковскую карту — только если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии, объект с информацией о выплате (Payment) с данными для отправки чека.

Адрес для отправки запроса​

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

НазваниеОбязательностьТипОписание
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
fiscalization_details-FiscalizationDetailsДанные для фискализации
participant_details-ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
payment-PaymentMethodПлатёжные данные (карта, банковский счёт и др.)
error-ErrorОшибка

Пример запроса​

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;
use Bank131\SDK\DTO\Amount;


$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(
    'Доставка товара',
    new Amount(5000, 'rub'),
    1
);

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

$incomeInformation->setPayerName('ООО Рога и Копыта');
$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()->initPayoutWithFiscalization($request);

Пример успешного ответа​

{
    "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"
                    }
                }
            }
        ]
    }
}

Пример неуспешного ответа​

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

session/start/payout​

Старт выплаты​

Этот запрос можно использовать, чтобы начать выплату в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения выплаты или заменить уже переданные.

Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.

Адрес для отправки запроса​

/api/v1/session/start/payout

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_method-PaymentMethodПлатежные данные (карта, банковский счёт и др.)
amount_details-AmountDetailsСумма
participant_details-ParticipantDetailsИнформация об участниках выплаты
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

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()->startPayout($request);

Пример успешного ответа​

{
    "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​

Старт выплаты с проверкой на заполненность данных для фискализации​

Этот запрос можно использовать, чтобы начать выплату в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения выплаты или заменить уже переданные.

Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.

Адрес для отправки запроса​

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

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
amount_details-AmountDetailsСумма
fiscalization_details-FiscalizationDetailsДанные для фискализации
participant_details-ParticipantDetailsИнформация об участниках выплаты
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

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": "ООО Рога и Копыта",
            "services": [
                {
                    "name": "Доставка товара",
                    "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(
    'Доставка товара',
    new Amount(5000, 'rub'),
    1
);

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

$incomeInformation->setPayerName('ООО Рога и Копыта');
$incomeInformation->setPayerType('legal');
$incomeInformation->setPayerTaxNumber('330000000000');

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

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

Пример успешного ответа​

{
    "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": "Доставка товара",
                                "amount_details": {
                                    "amount": 5000,
                                    "currency": "rub"
                                },
                                "quantity": 1
                            }
                        ],
                        "tax_reference": "590613976192",
                        "payer_type": "legal",
                        "payer_tax_number": "3316004710",
                        "payer_name": "ООО Рога и Копыта"
                    }
                }
            }
        ]
    }
}

fiscalization​

Фискализация без выплаты​

Этот запрос можно использовать, чтобы зарегистрировать выплату самозанятому в налоговой и получить ссылку на чек. Саму выплату проводить не нужно (можно провести до или после, любым удобным способом).

Чтобы отправить запрос на фискализацию, нужно сначала создать платежную сессию и получить идентификатор сессии (session_id).

Адрес для отправки запроса​

/api/v1/fiscalization

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
fiscalization_details+FiscalizationDetailsДанные для фискализации
payment_method-PaymentMethodПлатежные данные (карта, банковский счёт и др.)
amount_details-AmountDetailsСумма
participant_details-ParticipantDetailsИнформация об участниках выплаты
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

curl --location --request POST 'https://demo.bank131.ru/api/v1/fiscalization' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: project' \
--data-raw '{
    "session_id": "ps_2704",
    "fiscalization_details": {
        "professional_income_taxpayer": {
            "tax_reference": "123456789012",
            "payer_type": "legal",
            "payer_tax_number": "3316004777",
            "payer_name": "ООО Рога и Копыта",
            "services": [
                {
                    "name": "Доставка товара",
                    "amount_details": {
                        "amount": 5000,
                        "currency": "rub"
                    }
                },
                                {
                    "name": "Доставка сырья",
                    "amount_details": {
                        "amount": 5000,
                        "currency": "rub"
                    }
                }
            ]
        }
    }
}'

Пример успешного ответа​

{
    "status": "ok",
    "session": {
        "id": "ps_2704",
        "status": "in_progress",
        "created_at": "2021-05-27T08:13:33.736384Z",
        "updated_at": "2021-05-27T08:13:33.871729Z",
        "payments": [
            {
                "id": "po_2705",
                "status": "in_progress",
                "created_at": "2021-05-27T08:13:33.860754Z",
                "amount_details": {
                    "amount": 15000,
                    "currency": "rub"
                },
                "amounts": {
                    "gross": {
                        "amount": 15000,
                        "currency": "rub"
                    }
                },
                "fiscalization_details": {
                    "professional_income_taxpayer": {
                        "services": [
                            {
                                "name": "Доставка товара",
                                "amount_details": {
                                    "amount": 5000,
                                    "currency": "rub"
                                },
                                "quantity": 2
                            },
                            {
                                "name": "Доставка сырья",
                                "amount_details": {
                                    "amount": 5000,
                                    "currency": "rub"
                                },
                                "quantity": 1
                            }
                        ],
                        "tax_reference": "123456789012",
                        "payer_type": "legal",
                        "payer_tax_number": "3316004777",
                        "payer_name": "ООО Рога и Копыта"
                    }
                }
            }
        ]
    }
}

session/init/payment​

Создание сессии с одновременным стартом платежа​

Можно использовать, если вы сразу готовы передать все параметры, необходимые для оплаты. Например, при оплате банковской картой, если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии и объект с информацией о платеже (AcquiringPayment).

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsПлатежные данные
amount_details+AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
participant_details-ParticipantDetailsИнформация об участниках
customer+CustomerДанные клиента вашей системе
payment_options-PaymentOptionsДополнительные параметры платежа
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

curl --location --request POST 'https://demo.bank131.ru/api/v1/session/init/payment' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--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);

Пример успешного ответа​

{
    "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"
                }
            }
        ]
    }
}

Пример неуспешного ответа​

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

session/init/payment/sync​

Платеж одним запросом​

Этот метод позволяет отправить запрос на оплату и сразу получить ответ. Можно использовать, если вы готовы в этом запросе передать все параметры для оплаты. Например, при оплате банковской картой, если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии и объект AcquiringPayment с результатом платежа и всей информацией о нем.

Параметры запроса​

Здесь перечислены только обязательные параметры запроса. Дополнительные параметры есть по ссылкам в описании объектов.

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsПлатежные данные
type+stringТип способа оплаты. Возможные варианты: card
card+CardPaymentMethodОбъект с данными банковской карты
type+stringСпособ передачи данных карты. Значение: bank_card
bank_card+BankCardОбъект с данными карты в открытом виде
number+stringНомер карты
expiration_month+stringМесяц, до которого действует карта, в формате ММ. Например 01
expiration_year+stringМесяц, до которого действует карта, в формате ГГ. Например 22
security_code+stringСекретный код CVC или CVV
amount_details+AmountDetailsОбъект с данными для суммы платежа
amount+intСумма в копейках. Значение должно быть больше нуля. Если сумма оплаты 100 рублей, нужно передать 10000
currency+stringКод валюты согласно ISO 4217. Регистр не важен. Всегда: rub
participant_details-ParticipantDetailsИнформация об участниках
customer+CustomerДанные отправителя платежа на вашей стороне
reference+stringИдентификатор отправителя платежа в вашей системе
payment_options+PaymentOptionsДополнительные параметры платежа
return_url+stringURL, на который нужно перенаправить пользователя после проведения платежа. URL должен быть валидным
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

curl --location --request POST 'https://proxy.bank131.ru/api/v1/session/init/payment/sync' \
--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"
    }
}'

Пример успешного ответа​

{
    "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"
                }
            }
        ]
    }
}

Пример неуспешного ответа​

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

session/start/payment​

Старт платежа​

Этот запрос можно использовать, чтобы начать платеж в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения оплаты или заменить уже переданные.

Адрес для отправки запроса​

/api/v1/session/start/payment

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_details-PaymentDetailsПлатежные данные
amount_details-AmountDetailsСумма
participant_details-ParticipantDetailsИнформация об участниках (отправителе и получателе платежа)
customer-CustomerДанные отправителя платежа в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

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": "e05794ee22f47ee5f674e63303ea227e6113f42359f332945304f1e958542fff",
            "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\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);

Пример успешного ответа​

{
    "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 (confrm_request)​

Подтверждение операции​

Этот запрос можно отправлять, когда Банк 131 готов провести операцию — выплату или платеж. Например, вы получили вебхук ready_to_confirm.

Вам нужно проверить параметры операции и принять решение. Если всё в порядке, подтвердите операцию: отправьте Банку confirm_request. Если что-то не так, отмените операцию: отправьте запрос cancel_request.

Адрес для отправки запроса​

/api/v1/session/confirm

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии
confirm_information- (обязательно при операциях с номинальным счетом и при requier_confirm_information = true)ConfirmInformationИнформация для подтверждения операции

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса 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');

Пример ответа​

{
    "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)​

Списание захолдированной суммы​

Этот запрос можно использовать, если вы отправляете холдированные платежи. Такой платеж проходит в две стадии: сначала деньги замораживаются (например, на банковской карте пользователя), а потом списываются по вашей команде.

Запрос можно отправлять, когда Банк 131 готов списать деньги и прислал вам вебхук ready_to_capture.

Если вы хотите списать замороженную сумму, отправьте запрос capture_request. Можно списать замороженную сумму или меньше.

Чтобы отменить списание, отправьте cancel_request.

Адрес для отправки запроса​

/api/v1/session/capture

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии Банка 131
amount_details-AmountDetailsСумма к списанию. Может быть меньше захолдированной, но обязательно больше 0. Если параметр отсутствует, то захолдированная сумма будет списана полностью.

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса 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');

session/cancel (cancel_request)​

Отмена операции​

Этот запрос можно отправлять, когда Банк 131 готов провести операцию — выплату или платеж. Например, вы получили вебхук ready_to_confirm или ready_to_capture.

Если не хотите проводить эту операцию, можете ее отменить: отправьте запрос cancel_request.

Если всё в порядке, отправьте запрос на подтверждение операции (confirm_request) или на списание замороженной суммы (capture_request).

Адрес для отправки запроса​

/api/v1/session/cancel

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса 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');

Пример ответа​

{
    "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​

Возврат​

С помощью этого запроса можно вернуть деньги пользователю после успешного платежа.

После проведения возврата Банк 131 отправит вам вебхук payment_refunded.

Адрес для отправки запроса​

/api/v1/session/refund

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор успешной платежной сессии, по которой необходимо провести возврат.
amount_details-AmountDetailsСумма возврата. Если не указывать, то возврат будет на полную сумму платежа.
metadata-*Дополнительная информация

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

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

Пример ответа​

{
    "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​

Генерация публичного токена для работы с виджетами​

Токен нужен для доступа к JavaScript-библиотеке Банка 131. Вы можете сгенерировать его этим запросом и использовать для работы с виджетами.

Токен действителен 24 часа. Его можно использовать для одной операции. При отправке запроса следует передать параметры для работы с виджетами, которые вы собираетесь использовать с этим токеном.

Адрес для отправки запроса​

/api/v1/token

Параметры запроса​

НазваниеОбязательностьТипОписание
tokenize_widget-TokenizeWidgetMetadataДанные для работы виджета токенизации
self_employed_widget-SelfEmployedWidgetMetadataДанные для работы виджета регистрации самозанятого
acquiring_widget-AcquiringWidgetMetadataДанные для работы виджета платежной формы

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
public_token-stringПубличный токен
error-ErrorОшибка

Пример запроса на создание токена для проведения выплаты с получением данных карты через виджет и с привязкой самозанятого​

curl -X POST \
  https://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();

Пример запроса на создание токена для проведения платежа с оплатой через платежную форму​

curl -X POST \
  https://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"
    }
}'

Пример успешного ответа​

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

Пример неуспешного ответа​

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

token/info​

Получение информации по токену​

Операции с банковскими картами часто проводятся с токенизированными данными. При выплатах и платежах через виджеты создается публичный токен, при рекуррентных платежах — рекурентный токен.

По любому платежному токену можно получить информацию:

  • о банковской карте, для которой создан этот токен — это будет маскированный номер карты и платежная система,
  • или о самом токене — тип токена, время создания, срок действия, активен ли этот токен на момент запроса.

Этот метод можно использовать, чтобы, например, узнать маскированный номер карты и показать пользователю, с какой карты спишутся деньги по подписке. Или если понадобится проверить срок действия токена.

Адрес для отправки запроса​

/api/v1/token/info

Параметры запроса​

НазваниеОбязательностьТипОписание
type+stringТип запроса. Варианты: card, public_token, recurrent_token
card- (обязателен для type = card)CardPaymentMethodОбъект с данными банковской карты
public_token- (обязателен для type = public_token)PublicTokenОбъект с данными токена
recurrent_token- (обязателен для type = recurrent_token)RecurrentTokenОбъект с данными рекуррентного токена

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
info-CardTokenInfo, PublicTokenInfo или RecurrentTokenInfoИнформация о токене, зависит от типа запроса (type)
error-ErrorОшибка

Запрос информации о карте по токену​

Пример запроса

Вы отправляете токенизированные данные банковской карты и получаете маску карты и платежную систему.

curl --location --request POST 'https://demo.bank131.ru/api/v1/token/info' \
--header 'X-PARTNER-PROJECT: partner-project' \
--header 'X-PARTNER-SIGN: key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "card",
    "card": {
        "type": "encrypted_card",
        "encrypted_card": {
            "number_hash": "card_number_hash (token)"
        }
    }
}'

Пример ответа

{
    "status": "ok",
    "info": {
        "number_hash": "card_number_hash",
        "brand": "visa",
        "last4": "4242",
        "type": "card"
    }
}

Запрос информации о публичном токене​

Пример запроса

Вы отправляете публичный токен и получаете информацию о нем.

curl --location --request POST 'https://demo.bank131.ru/api/v1/token/info' \
--header 'X-PARTNER-PROJECT: partner-project' \
--header 'X-PARTNER-SIGN: key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "public_token",
    "public_token": {
        "token": "your_token"
    }
}'

Пример ответа

{
    "status": "ok",
    "info": {
        "token": "your_token",
        "created_at": "2021-03-17T14:10:56+03:00",
        "finished_at": "2021-03-18T14:10:56+03:00",
        "is_active": true,
        "type": "public_token"
    }
}

Запрос информации о рекуррентном токене​

Пример запроса

Вы отправляете рекуррентный токен и получаете информацию о нем.

curl --location --request POST 'https://demo.bank131.ru/api/v1/token/info' \
--header 'X-PARTNER-PROJECT: partner-project' \
--header 'X-PARTNER-SIGN: key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "recurrent_token",
    "recurrent_token": {
        "token": "your_token"
    }
}'

Пример ответа

{
    "status": "ok",
    "info": {
        "token": "your_token",
        "created_at": "2021-03-17T14:19:05+03:00",
        "finished_at": "2021-04-17T14:19:05+03:00",
        "is_active": true,
        "type": "recurrent_token"
    }
}

recurrent/disable​

Отключение рекуррентного токена​

С помощью этого запроса можно отключить рекуррентный токен. Отправьте в запросе токен, в ответ придет is_active: false. Это значит, что с этим токеном больше нельзя проводить рекуррентные платежи.

После отключения токена в параметре даты окончания действия токена finished_at может появиться дата, относящаяся к 2000 году — она ни на что не влияет, можно не обращать на неё внимание.

Адрес для отправки запроса​

/api/v1/recurrent/disable

Параметры запроса​

НазваниеОбязательностьТипОписание
recurrent+RecurrentTokenОбъект с токеном, который нужно отключить

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
recurrent+RecurrentTokenInfoОбъект с токеном

Пример запроса​

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

Пример ответа​

{
    "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"
}

Информация​

session/status​

Получение информации по сессии​

Вы можете отправить этот запрос, если хотите получить полную информацию о платежной сессии. Например, проверить, прошла выплата или нет. Или узнать, можно ли списывать сумму, захолдированную при оплате картой.

В ответ на запрос приходит платежная сессия с данными обо всех операциях, которые проводились в ее рамках.

Адрес для отправки запроса​

/api/v1/session/status

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса status_request​

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

Пример успешного ответа​

{
    "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​

С помощью этого запроса можно узнать ваш текущий баланс на депозите в Банке 131.

Это нужно, чтобы убедиться, что на депозите достаточно денег:

  • для проведения массовых выплат;
  • для проведения возвратов.

Если денег недостаточно, вы можете пополнить депозит.

Данный метод не передает информацию о балансе номинального счета. Эта информация доступна в вашем аккаунте ДБО.

Адрес для отправки запроса​

/api/v1/wallet/balance

Параметры запроса​

НазваниеОбязательностьТипОписание
request_datetime+stringТекущее время запроса в формате ISO 8601

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
wallets-WalletDetailsСписок доступных счетов обеспечения в Банке 131
error-ErrorОшибка

Пример запроса​

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

Пример ответа​

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

fps/banks​

С помощью этого запроса вы можете получить список наименований и идентификаторов банков-участников Системы быстрых платежей.

Адрес для отправки запроса​

/api/v1/fps/banks

Пример запроса​

curl --location --request GET 'https://demo.bank131.ru/api/v1/fps/banks' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: test-partner' \
--data-raw '{}'

Пример ответа​

{
    "banks": [
        {
            "id": "100000000243",
            "eng_name": "National Standard Bank",
            "ru_name": "Национальный стандарт"
        },
        {
            "id": "100000000056",
            "eng_name": "Khlynov",
            "ru_name": "Хлынов"
        },
        ...
    ]
}

fps/customer_verification​

С помощью этого запроса можно проверить зарегистрирован ли получатель в Системе Быстрых Платежей. Если пользователь найден в СБП, то сессия примет успешный статус, иначе сессия отменится. Эта операция не тарифицируется и подтверждается автоматически (вебхук ready_to_confirm не отправляется).

Адрес для отправки запроса​

/api/v1/fps/customer_verification

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_method-PaymentMethodПлатежные данные (карта, банковский счёт и др.)
participant_details-ParticipantDetailsИнформация об участниках выплаты

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​


curl -X POST \
  https://demo.bank131.ru/api/v1/fps/customer_verification \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
  "payment_method": {
        "type": "bank_account",
        "bank_account": {
            "system_type": "faster_payment_system_verification",
            "faster_payment_system_verification": {
                "phone": "79261234567",
                "bank_id": "100000000069"
            }
        }
    },
    "participant_details": {
        "recipient": {
            "first_name": "Иван",
            "last_name": "Иванов",
            "middle_name": "Иванович"
        }
    }
}

Пример ответа​

{
    "status": "ok",
    "session": {
        "id": "ps_109941",
        "status": "in_progress",
        "created_at": "2022-03-01T11:57:31.652396Z",
        "updated_at": "2022-03-01T11:57:31.861329Z",
        "payments": [
            {
                "id": "po_31668",
                "status": "in_progress",
                "created_at": "2022-03-01T11:57:31.895773Z",
                "payment_method": {
                    "type": "bank_account",
                    "bank_account": {
                        "system_type": "faster_payment_system_verification",
                        "faster_payment_system_verification": {
                            "phone": "79261234567",
                            "bank_id": "100000000069"
                        }
                    }
                },
                "amount_details": {
                    "amount": 100,
                    "currency": "rub"
                },
                "participant_details": {
                    "recipient": {
                        "first_name": "Иван",
                        "last_name": "Иванов",
                        "middle_name": "Иванович"
                    }
                }
            }
        ]
    }
}

Самозанятые​

 

check и request/status​

Проверка статуса самозанятого​

Этот запрос позволяет проверить по ИНН, является физлицо самозанятым или нет.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос check, передаете в параметре tax_reference ИНН физлица и получаете в ответ идентификатор request_id.
  2. Затем отправляете запрос request/status с этим идентификатором. В ответе придет информация, зарегистрирован ли этот ИНН в налоговой как самозанятый и привязан ли он к Банку 131.

Запрос check не следует отправлять чаще, чем раз в 30 секунд.

Адрес для отправки запроса check​

/api/v1/npd/check

Параметры запроса check​

НазваниеОбязательностьТипОписание
tax_reference+stringИНН физлица

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
request_id+stringИдентификатор запроса

Пример запроса 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"
}'

Пример ответа на check​

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

Адрес для отправки запроса request/status​

api/v1/npd/request/status \

Параметры запроса request/status​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос check

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
is_professional_income_taxpayer-boolЯвляется ли физлицо самозанятым
is_linked-boolПривязан ли самозанятый к Банку 131
error-object ErrorОшибка

Пример запроса request/status для 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"
}'

Пример ответа на request/status для check: физлицо является самозанятым и привязано к Банку 131​

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

Пример ответа на request/status для check: физлицо является самозанятым и не привязано к Банку 131​

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

npd/taxpayer/check_personal_info и npd/request/status​

Проверка соответствия данных самозанятого​

Запрос позволяет проверить соответвие данных (ИНН, ФИО, номер телефона) самозанятого с теми, которые имеются в ФНС.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/taxpayer/check_personal_info, передаете в параметрах ИНН, ФИО и номер телефона самозанятого, и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет информация о возможных расхождениях с данными, которые есть у ФНС.

Адрес для отправки запроса npd/taxpayer/check_personal_info​

/api/v1/npd/taxpayer/check_personal_info

Параметры запроса npd/taxpayer/check_personal_info​

НазваниеОбязательностьТипОписание
first_name+stringИмя самозанятого
second_name+stringФамилия самозанятого
patronymic+stringОтчество самозанятого
tax_reference+stringИНН самозанятого
phone+stringНомер телефона самозанятого. Формат: "7ХХХХХХХХХХ".

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
request_id-stringИдентификатор, который пришел в ответ на запрос npd/taxpayer/check_personal_info

Пример запроса​

curl -X POST \
  https://demo.bank131.ru/api/v1/npd/taxpayer/check_personal_info \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "first_name": "Test",
    "first_name": "Test",
    "patronymic": "Test",
    "tax_reference": "123456789012",
    "phone": "71234567890"
}'

Пример ответа​

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

Адрес для отправки запроса npd/request/status​

api/v1/npd/request/status

Параметры запроса npd/request/status​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/taxpayer/check_personal_info

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
success-booleanРасхождение в параметрах. true - расхождение не обнаружено; false - обнаружено расхождение.
violations-array\<string>Массив с названиями параметров, в значениях которых обнаружены расхождения. Возможные значения: "first_name", "second_name", "patronymic", "tax_reference", "phone"
error-object ErrorОшибка

Пример запросаnpd/request/status​

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"
}

Пример ответа​

{
    "status": "ok",
    "success": false,
    "violations": ["first_name", "second_name", "phone"]
}

npd/notifications/count и npd/request/status​

Метод для получения количества непрочитанных оповещений из ФНС для самозанятых.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/notifications/count, передаете в параметрах ИНН и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет информация о количестве непрочитанных оповещений.

Адрес для отправки запроса npd/notifications/count​

/api/v1/npd/notificaitons/count

Параметры запроса npd/notifications/count​

НазваниеОбязательностьТипОписание
tax_reference_list+arrayСписок ИНН (не более 1000 штук в одном запросе)

Параметры ответа​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/count

Пример запроса npd/notifications/count​

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

Пример ответа​

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

Адрес для отправки запроса npd/request/status​

api/v1/npd/request/status

Параметры запроса npd/request/status​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/count

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
info-array<NotificationCountInformation>

Пример запроса npd/request/status​

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"
}

Пример ответа​

{
    "status": "ok",
    "info": [
        {
            "tax_reference": "",
            "count": 0
        }
    ]
}

npd/notifications/read и npd/request/status​

Метод для получения подробной информации о непрочитанных оповещениях для самозанятых из ФНС.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/notifications/read, передаете в параметрах ИНН и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет информация о непрочитанных оповещениях для самозанятых из ФНС.

Адрес для отправки запроса npd/notifications/read​

api/v1/npd/notifications/read

Параметры запроса npd/notifications/read​

НазваниеОбязательностьТипОписание
tax_reference_list+arrayСписок ИНН
get_read+booleanВыводить в ответе уже прочитанныхе оповещения. Возможные варианты: true — выводить; false — не выводить.
get_archived+booleanВыводить в ответе архивные оповещения. Возможные варианты: true — выводить; false — не выводить.

Параметры ответа​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/read

Пример запроса npd/notifications/read​

curl -X POST \
  https://demo.bank131.ru/api/v1/npd/notifications/read \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "tax_reference_list": ["123456789012"],
    "get_read": false,
    "get_archived":  false
}

Пример ответа​

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

Адрес для отправки запроса npd/request/status​

api/v1/npd/request/status

Параметры запроса npd/request/status​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/read

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
info-array<NotificationInformation>Список параметров для ИНН

Пример запроса npd/request/status​

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"
}

Пример ответа​

{
    "status": "ok",
    "info": [
        {
            "tax_reference": "123456789012",
            "notifications": [
                {
                    "id": "132313",
                    "title": "131.ru запрашивает разрешение на осуществление определенных действий от Вашего имени",
                    "message": "131.ru запросил у Вас разрешение на осуществление определенных действий от Вашего имени. Вы можете ознакомиться с перечнем запрошенных разрешений и дать свое согласие (уполномочить 131.ru), нажав кнопку \"Разрешить\", или отказать ему, нажав кнопку \"Отказать\".",
                    "status": "NEW",
                    "created_at": "2023-03-22T13:29:55+00:00"

                }
            ]
        }
    ]
}

npd/notifications/mark_as_delivered и npd/request/status​

Метод для отправки в ФНС уведомления о доставке оповещений самозанятому. Метод необходимо вызывать после метода notifications/read.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/notifications/mark_as_delivered, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет статус доставки.

Адрес для отправки запроса npd/notifications/mark_as_delivered​

/api/v1/npd/notifications/mark_as_delivered

Параметры запроса npd/notifications/mark_as_delivered​

НазваниеОбязательностьТипОписание
notification_list+array<Notification_list>Данные об оповещениях

Параметры ответа​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/mark_as_delivered

Пример запроса npd/notifications/mark_as_delivered​

curl -X POST \
  https://demo.bank131.ru/api/v1/npd/notifications/mark_as_delivered \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "notification_list": [
        {
            "message_id_list": ["123", "234"],
            "tax_reference": "123456789012"
        }
    ]
}

Пример ответа​

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

Адрес для отправки запроса npd/request/status​

api/v1/npd/request/status

Параметры запроса npd/request/status​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/mark_as_delivered

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending

Пример запроса npd/request/status​

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"
}

Пример ответа​

{
    "status": "ok"
}

npd/notifications/update и npd/request/status​

Метод для отправки в ФНС уведомления о том, что оповещение было прочитано самозанятым. Метод необходимо вызывать после метода notifications/mark_as_delivered.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/notifications/update, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет статус отправки.

Адрес для отправки запроса npd/notifications/update​

/api/v1/npd/notifications/update

Параметры запроса npd/notifications/update​

НазваниеОбязательностьТипОписание
notification_list+array<Notification_list>Данные об оповещениях

Параметры ответа​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/update

Пример запроса npd/notifications/update​

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

Пример ответа​

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

Адрес для отправки запроса npd/request/status​

api/v1/npd/request/status

Параметры запроса npd/request/status​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/update

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending

Пример запроса npd/request/status​

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"
}

Пример ответа​

{
    "status": "ok"
}

npd/taxpayer/account_status и npd/request/status​

Метод для получения общей информации о наличии налоговой задолженности и остатке налогового бонуса у самозанятых.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/taxpayer/account_status, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет общая информация о наличии налоговой задолженности и остатке налогового бонуса у самозанятого.

Адрес для отправки запроса npd/taxpayer/account_status​

/api/v1/npd/taxpayer/account_status

Параметры запроса npd/taxpayer/account_status​

НазваниеОбязательностьТипОписание
tax_reference+stringИНН самозанятого. Не более 1 ИНН в запросе.

Параметры ответа​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/taxpayer/account_status

Пример запроса npd/taxpayer/account_status​

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

Пример ответа​

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

Адрес для отправки запроса npd/request/status​

api/v1/npd/request/status

Параметры запроса npd/request/status​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/taxpayer/account_status

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
bonus_amount-stringСумма бонусного счета
unpaid_amount-stringОбщая сумма неоплаченных платежей
debt_amount-stringСумма задолжности (включена в общая сумму неоплаченных платежей)

Пример запроса npd/request/status​

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"
}

Пример ответа​

{
    "status": "ok",
    "bonus_amount": "9972.3624",
    "unpaid_amount": "0",
    "debt_amount": "0"
}

npd/accruals и npd/request/status​

Метод для получения подробной информации о наличии налоговой задолженности и остатке налогового бонуса у самозанятых.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/accruals, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет подробная информация о наличии налоговой задолженности и остатке налогового бонуса у самозанятого.

Адрес для отправки запроса npd/accruals​

/api/v1/npd/accruals

Параметры запроса npd/accruals​

НазваниеОбязательностьТипОписание
tax_reference_list+arrayСписок ИНН самозанятых. Не более 100 ИНН в обном запросе.

Параметры ответа​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/accruals

Пример запроса npd/accruals​

curl -X POST \
  https://demo.bank131.ru/api/v1/npd/accruals \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "tax_reference_list":["111111111111"]
}

Пример ответа​

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

Адрес для отправки запроса npd/request/status​

api/v1/npd/request/status

Параметры запроса npd/request/status​

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/accruals

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
accruals-jagged array
tax_charge_list-arrayИнформация о налоговой задолженности
amount-stringСумма начисления
due_date-stringСрок оплаты
tax_period_id-stringИдентификатор налогового периода. Формат: ГГГГММ
oktmo-stringОКТМО региона ведения деятельности
kbk-stringКод бюджетной классификации
paid_amount-stringСумма поступивших оплат в АИС Налог 3 по данному начислению
create_time-stringДата и время создания налогового начисления
id-stringВнутренний идентификатор налогового начисления в ПП НПД
krsb_list-array of reference-objects.mdИнформация о задолженности по карточке
debt-stringСумма о задолженности по карточке
penalty-stringСумма пени по карточке
overpayment-stringСумма переплаты по карточке
oktmo-stringОКТМО региона ведения деятельности, связанного с КРСБ
kbk-stringКод бюджетной классификации, связанный с КРСБ
tax_organ_code-stringКод налогового органа, связанного с КРСБ
update_time-stringДата/Время обновления информации по карточке в ПП НПД
id-stringВнутренний идентификатор карточки в ПП НПД
inn-stringИНН

Пример запроса npd/request/status​

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"
}

Пример ответа​

{
    "status": "ok",
    "accruals": [
        {
            "tax_charge_list": [
                {
                    "amount": "",
                    "due_date": "",
                    "tax_period_id": "",
                    "oktmo": "",
                    "kbk": "",


                    "paid_amount": "",
                    "create_time": "",
                    "id": ""
                }
            ],
            "krsb_list": [
                {
                    "debt": "",
                    "penalty": "",
                    "overpayment": "",
                    "oktmo": "",
                    "kbk": "",
                    "tax_organ_code": "",
                    "update_time": "",
                    "id": ""
                }
            ],
            "inn": "111111111111"
        }
    ]
}

Номинальный счет​

Cоздание платежной сессии​

session/multi/create/nominal​

Этот запрос создает платежную сессию на стороне Банка 131.

Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций.

Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты или платежа. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату.

Если вы готовы передать в запросе все данные, которые нужны для проведения операции, можете использовать метод, при котором сразу после создания сессии стартует выплата (/api/v1/session/multi/init/payment/nominal). В этом случае запускать операцию отдельным запросом не нужно.

В ответе возвращаются параметры созданной сессии.

Адрес для отправки запроса​

/api/v1/session/multi/create/nominal

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsДанные о переводе
payment_method+PaymentMethodПлатежные данные (карта, банковский счет и др.)
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
participant_details- (обязателен при выплатах на карту)ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d {
    "payment_details": {
        "type": "internal_transfer",
        "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
                "description": "Назначение платежа"
            }
        }
    },
    "payment_method": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "****************"
            }
        }
    },
    "participant_details": {
        "sender": {
            "full_name": "Данные отправителя",
            "beneficiary_id": "1234567890"
        },
        "recipient": {
            "full_name": "Иванов Иван Иванович"
        }
    },
    "amount_details": {
        "amount": 293400,
        "currency": "RUB"
    },
    "customer": {
        "reference": "123456789012"
    }
}

Пример успешного ответа​

{
    "status": "ok",
    "session": {
        "id": "ps_72974",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.274416Z",
        "updated_at": "2021-08-06T11:34:51.466550Z",
        "payments": [
            {
                "id": "po_25657",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545329Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_method": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "0002"
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ],
        "acquiring_payments": [
            {
                "id": "pm_15174",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545232Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "internal_transfer",
                    "internal_transfer": {
                        "type": "transfer_from_nominal_account",
                        "transfer_from_nominal_account": {
                            "description": "test payout",
                            "card_mask": "400000******0002"
                        }
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ]
    }
}

Пример неуспешного ответа​

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

session/multi/start/payment/nominal​

Старт выплаты​

Этот запрос можно использовать, чтобы начать выплату в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения операции или заменить уже переданные.

Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.

Адрес для отправки запроса​

/api/v1/session/multi/start/payment/nominal

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_details-PaymentDetailsДанные о переводе
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
participant_details- (обязателен при выплатах на карту)ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
customer-CustomerДанные получателя в вашей системе
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
    "session_id": "ps_12345",
    "payment_details": {
        "type": "internal_transfer",
        "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
                "description": "test payout"
            }
        }
    },
    "payment_method": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "4242424242424242"
            }
        }
    },
    "participant_details": {
        "recipient": {
            "full_name": "Ivan Ivanovich Test",
            "beneficiary_id": "123412341234"
        },
        "sender": {
            "full_name": "Ivan Ivanovich Test",
            "beneficiary_id": "123412341234"
        }
    },
    "amount_details": {
        "amount": 1011,
        "currency": "RUB"
    },
    "customer": {
        "reference": "test"
    }
}

Пример успешного ответа​

{
    "status": "ok",
    "session": {
        "id": "ps_72974",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.274416Z",
        "updated_at": "2021-08-06T11:34:51.466550Z",
        "payments": [
            {
                "id": "po_25657",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545329Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_method": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "0002"
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ],
        "acquiring_payments": [
            {
                "id": "pm_15174",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545232Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "internal_transfer",
                    "internal_transfer": {
                        "type": "transfer_from_nominal_account",
                        "transfer_from_nominal_account": {
                            "description": "test payout",
                            "card_mask": "400000******0002"
                        }
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ]
    }
}

Пример неуспешного ответа​

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

session/multi/init/payment/nominal​

Cоздание сессии с одновременным стартом выплаты на банковскую карту​

Можно использовать этот запрос, если вы сразу готовы передать все параметры для создания выплаты. При выплате на банковскую карту — только если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии и объект с информацией о выплате (acquiring_payments).

Адрес для отправки запроса​

/api/v1/session/multi/init/payment/nominal

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsДанные о переводе
payment_method+PaymentMethodПлатежные данные (карта)
participant_details+ (обязателен при выплатах на карту)ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
customer+CustomerДанные получателя в вашей системе
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

curl -X POST \
  https://demo.bank131.ru/api/v1/session/multi/init/payment/nominal \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
    "payment_details": {
        "type": "internal_transfer",
        "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
                "description": "test payout"
            }
        }
    },
    "payment_method": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "4242424242424242"
            }
        }
    },
    "participant_details": {
        "recipient": {
            "full_name": "Ivan Ivanovich Test",
            "beneficiary_id": "123412341234"
        },
        "sender": {
            "full_name": "Ivan Ivanovich Test",
            "beneficiary_id": "123412341234"
        }
    },
    "amount_details": {
        "amount": 1011,
        "currency": "RUB"
    },
    "customer": {
        "reference": "test"
    }
}

Пример успешного ответа​

{
    "status": "ok",
    "session": {
        "id": "ps_72974",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.274416Z",
        "updated_at": "2021-08-06T11:34:51.466550Z",
        "payments": [
            {
                "id": "po_25657",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545329Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_method": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "0002"
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ],
        "acquiring_payments": [
            {
                "id": "pm_15174",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545232Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "internal_transfer",
                    "internal_transfer": {
                        "type": "transfer_from_nominal_account",
                        "transfer_from_nominal_account": {
                            "description": "test payout",
                            "card_mask": "400000******0002"
                        }
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test",                  
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ]
    }
}

Пример неуспешного ответа​

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

api/v1/session/init/payout/nominal​

Cоздание сессии с одновременным стартом выплаты на банковский счет​

Этот запрос можно использовать для отправки выплаты с номинального счета на банковский счет.

Адрес для отправки запроса​

api/v1/session/init/payout/nominal

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_method+PaymentMethodПлатежные данные
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
participant_details+ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса для выплаты на счет физического лица​

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "ru": {
    "bik": "044525974",
    "account": "40817810400003869535",
    "full_name": "Иванов Иван Иванович",
    "description": "Перевод средств по договору № 5015553111 Иванов Иван Иванович НДС не облагается"
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    },
    "recipient":{
         "beneficiary_id": "1234567890"
         }
  }
}'

Пример запроса для выплаты на счет юридического лица​

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "ru": {
    "bik": "044525974",
    "account": "40702810500000000001",
    "full_name": "ООО Наименование организации",
    "inn": "1111111111",
    "kpp": "156605101",
    "description": "Перечисление денежных средств по договору за декабрь 2022 г. НДС не облагается."
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    },
    "recipient":{
         "beneficiary_id": "1234567890"
         }
  }
}'

Пример успешного ответа​

"status": "ok",
"session": {
    "id": "ps_287403",
    "status": "in_progress",
    "created_at": "2023-05-10T16:58:43.586072Z",
    "updated_at": "2023-05-10T16:58:43.705620Z",
    "payments": [
        {
            "id": "po_72265",
            "status": "in_progress",
            "created_at": "2023-05-10T16:58:43.781934Z",
            "payment_method": {
                "type": "bank_account",
                "bank_account": {
                    "system_type": "ru",
                    "ru": {
                        "bik": "049205131",
                        "account": "40702810900000000001",
                        "full_name": "Наименование организации",
                        "description": "Перечисление денежных средств по договору № 1 НС от 01.09.2021 комиссия площадки за декабрь 2022 г. НДС не облагается.",
                        "is_fast": false,
                        "kpp": "156605001",
                        "inn": "3111104710"
                    }
                }
            },
            "amount_details": {
                "amount": 200,
                "currency": "rub"
            },
            "amounts": {
                "gross": {
                    "amount": 200,
                    "currency": "rub"
                }
            },
            "paymentMetadata": {},
            "participant_details": {
                "sender": {
                    "account": "40702810300200000013"
                },
                "recipient": {
                    "beneficiary_id": "1234567890"
                }
            }
        }
    ]
}

Пример неуспешного ответа​

{
    "status": "error",
    "error": {
        "description": "Invalid input request parameters: payment_method.bank_account.ru.inn (bank_account_ru.inn.invalid_length)",
        "code": "invalid_request"
    }
}

Расчетный счет​

session/multi/create/rko​

Этот запрос создает платежную сессию на стороне Банка 131 для выплаты с расчетного счета.

Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций.

Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату.

Если вы готовы передать в запросе все данные, которые нужны для проведения операции, можете использовать метод, при котором сразу после создания сессии стартует выплата (/api/v1/session/multi/init/payment/rko). В этом случае запускать операцию отдельным запросом не нужно.

В ответе возвращаются параметры созданной сессии.

Адрес для отправки запроса​

/api/v1/session/multi/create/rko

| payment_details | + | PaymentDetails | Данные о переводе | | payment_method | + | PaymentMethod | Платежные данные (карта, банковский счет и др.) | | amount_details | - | AmountDetails | Сумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000 | | fiscalization_details | - | FiscalizationDetails | Данные для фискализации, только для выплат самозанятым | | participant_details | - (обязателен при выплатах на карту) | ParticipantDetails | Информация об участниках операции (отправителе и получателе) | | customer | - | Customer | Данные получателя в вашей системе | | metadata | - | * | Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках |

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

curl -X POST \
  https://demo.bank131.ru//api/v1/session/multi/create/rko \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d {
    "payment_details": {
        "type": "internal_transfer",
        "internal_transfer": {
            "type": "transfer_from_bank_account",
            "transfer_from_bank_account": {
                "description": "Назначение платежа"
            }
        }
    },
    "payment_method": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "****************"
            }
        }
    },
    "participant_details": {
        "sender": {
            "full_name": "Данные отправителя",
        },
        "recipient": {
            "full_name": "Иванов Иван Иванович"
        }
    },
    "amount_details": {
        "amount": 293400,
        "currency": "RUB"
    },
    "customer": {
        "reference": "123456789012"
    }
}

Пример успешного ответа​

{
    "status": "ok",
    "session": {
        "id": "ps_72974",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.274416Z",
        "updated_at": "2021-08-06T11:34:51.466550Z",
        "payments": [
            {
                "id": "po_25657",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545329Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_method": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "0002"
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ],
        "acquiring_payments": [
            {
                "id": "pm_15174",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545232Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "internal_transfer",
                    "internal_transfer": {
                        "type": "transfer_from_bank_account",
                        "transfer_from_bank_account": {
                            "description": "test payout",
                            "card_mask": "400000******0002"
                        }
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ]
    }
}

Пример неуспешного ответа​

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

session/multi/start/payment/rko​

Этот запрос можно использовать, чтобы начать выплату с расчетного счета на банковскую карту в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения операции или заменить уже переданные.

Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.

Адрес для отправки запроса​

/api/v1/session/multi/start/payment/rko

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_details-PaymentDetailsДанные о переводе
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
customer-CustomerДанные получателя в вашей системе
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
participant_details- (обязателен при выплатах на карту)ParticipantDetailsИнформация об участниках операции (отправителе и получателе)

Пример запроса​

curl -X POST \
  https://demo.bank131.ru/api/v1/session/multi/start/payment/rko \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -d '{
    "session_id": "ps_12345",
    "payment_details": {
        "type": "internal_transfer",
        "internal_transfer": {
            "type": "transfer_from_bank_account",
            "transfer_from_bank_account": {
                "description": "test payout"
            }
        }
    },
    "payment_method": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "4242424242424242"
            }
        }
    },
    "participant_details": {
        "recipient": {
            "full_name": "Ivan Ivanovich Test"
        },
        "sender": {
            "full_name": "Ivan Ivanovich Test"
        }
    },
    "amount_details": {
        "amount": 1011,
        "currency": "RUB"
    },
    "customer": {
        "reference": "test"
    }
}

Пример успешного ответа​

{
    "status": "ok",
    "session": {
        "id": "ps_72974",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.274416Z",
        "updated_at": "2021-08-06T11:34:51.466550Z",
        "payments": [
            {
                "id": "po_25657",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545329Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_method": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "0002"
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ],
        "acquiring_payments": [
            {
                "id": "pm_15174",
                "status": "in_progress",
                "created_at": "2021-08-06T11:34:51.545232Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "internal_transfer",
                    "internal_transfer": {
                        "type": "transfer_from_bank_account",
                        "transfer_from_bank_account": {
                            "description": "test payout",
                            "card_mask": "400000******0002"
                        }
                    }
                },
                "amount_details": {
                    "amount": 1011,
                    "currency": "RUB"
                },
                "amounts": {
                    "gross": {
                        "amount": 1011,
                        "currency": "RUB"
                    }
                },
                "metadata": {
                    "key": "value"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Ivan Ivanovich Test"
                    },
                    "recipient": {
                        "full_name": "Ivan Ivanovich Test",
                        "reference": "1234"
                    }
                }
            }
        ]
    }
}

Пример неуспешного ответа​

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

session/init/payout/rko​

Метод инициализации сессии и старта выплаты с расчетного счета.

Адрес для отправки запроса​

/api/v1/session/init/payout/rko

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_method+PaymentMethodПлатежные данные (банковский счет)
amount_details+AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
participant_details+ParticipantDetailsИнформация об отправителе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса​

curl --location 'https://proxy-stage.bank131.ru/api/v1/session/init/payout/rko' \
--header 'X-PARTNER-PROJECT: project-test' \
--header 'X-PARTNER-SIGN: sign' \
--header 'Content-Type: application/json' \
--data '{
    "payment_method": {
        "type": "bank_account",
        "bank_account": {
            "system_type":