Прием средств
На данной странице вы найдете методы и вебхуки, которые понадобятся платежному партнеру, отправляющему перевод. Общий порядок запросов следующий:
- Платежный партнер инициирует платежную сессию и передает в Банк подробную информацию об Отправителе и
Получателе методом
POST.../api/v1/bpa/session/init/payment
. - Банк создает транзакцию и возвращает результат создания.
- После получения ответа необходимо дождаться вебхука
ready_to_confirm
, в котором будет подробная информация о сумме к выплате, комиссии за транзакцию и курсе конвертации. - После получения вебхука
ready_to_confirm
необходимо подтвердить транзакцию методомsession/confirm
или отклонить ее методомsession/cancel
. - При необходимости можно проверить статус сессии при помощи метода
session/status
. - Для завершения транзакции дождитесь вебхука
payment_finished
.
Метод POST.../api/v1/bpa/session/init/payment
Метод предназначен для старта перевода.
Параметры запроса
Название | Обязательность | Тип данных | Описание |
---|---|---|---|
payment_details | + | object | Способ платежа |
type | + | string | Способ платежа. Возможное значение: moneysend |
moneysend | + | object | Детали платежа через Moneysend |
amount_details | + | object | Сумма и валюта платежа |
amount | + | int | Сумма платежа в минорных значениях (Чтобы передать 100 рублей, укажите 10000 ) |
currency | + | string | Валюта платежа |
participant_details | + | object | Информация об отправителе и получателе |
sender | + | object | Информация об отправителе |
citizenship_country_iso3 | + | string | Страна гражданства отправителя по стандарту ISO3166-1 alpha-3 |
first_name | + | string | Имя отправителя |
last_name | + | string | Фамилия отправителя |
middle_name | - | string | Отчество отправителя |
country_iso3 | + | string | Страна регистрации отправителя по стандарту ISO3166-1 alpha-3 |
state | - | string | Регион или район регистрации отправителя |
city | + | string | Населенный пункт регистрации отправителя |
postal_code | - | string | Почтовый индекс места регистрации отправителя |
street | - | string | Название улицы места регистрации отправителя |
building | + | string | Номер дома места регистрации отправителя |
flat | - | string | Квартира места регистрации отправителя |
tax_reference | - | string | 12-значный ИНН отправителя |
date_of_birth | + | string | Дата рождения отправителя в формате ГГГГ-ММ-ДД. Убедитесь, что возраст отправителя 18+ |
contacts | + | object | Контакты отправителя |
phone | + | object | Телефон отправителя |
full_number | + | string | Полный номер телефона отправителя в формате +<код страны><номер> |
country_iso3 | + | string | Код страны, к которой относится номер телефона отправителя, в формате ISO3 |
operator_code | + | string | Код оператора телефонного номера отправителя |
short_number | + | string | Номер телефона отправителя без кода оператора |
- | string | Email отправителя | |
identity_document | + | object | Данные документа, удостоверяющего личность отправителя |
id_type | + | string | Тип документа, удостоверяющего личность отправителя. Возможные значения: — Паспорт иностранного гражданина — Паспорт гражданина Российской Федерации |
id_number | + | string | Серия и номер документа, удостоверяющего личность отправителя (без пробелов) |
issue_date | + | string | Дата выдачи документа, удостоверяющего личность отправителя, в формате ГГГГ-ММ-ДД |
id_expiration_date | - | string | Дата окончания срока действия документа, удостоверяющего личность отправителя, в формате ГГГГ-ММ-ДД. Обязательно для заполнения при наличии в документе. Если его нет, просто не передавайте это поле |
division_code | - | string | Код подразделения, выдавшего документ, удостоверяющий личность отправителя. Обязательно для заполнения при наличии в документе |
issued_by | - | string | Название подразделения, выдавшего документ, удостоверяющий личность отправителя. Обязательно для заполнения при наличии в документе |
documents_foreigner | - | object | Параметры документа отправителя-нерезидента. Обязательно для заполнения, если отправитель является иностранным гражданином |
id_type | + | string | Тип документа, удостоверяющего личность отправителя-нерезидента. Возможные значения: — Вид на жительство — Разрешение на временное проживание — Миграционная карта — Виза |
issued_by | - | string | Название органа, выдавшего документ, удостоверяющий личность отправителя-нерезидента |
issue_date | + | string | Дата начала срока действия документа, удостоверяющего личность отправителя-нерезидента, в формате ГГГГ-ММ-ДД |
id_expiration_date | + | string | Дата окончания срока действия документа, удостоверяющего личность отправителя-нерезидента, в формате ГГГГ-ММ-ДД |
service_point | + | object | Точка приема денежных средств |
id | - | string | ID точки приёма |
name | - | string | Название точки приема |
country_iso3 | + | string | Страна точки приема. Формат ISO 3166-1 alpha-3 |
state | - | string | Регион/район нахождения точки приема |
city | + | string | Населенный пункт нахождения точки приема |
oktmo | + | string | Код ОКТМО расположения точки приема средств |
street | - | string | Улица нахождения точки приема |
house | - | string | Здание нахождения точки приема |
terminal_id | - | string | Номер терминала/кассы |
source_of_money | - | string | Источник поступления средств отправителя |
description | - | string | Дополнительная информация об отправителе |
recipient | + | object | Информация о получателе |
first_name | + | string | Имя получателя как в паспорте |
last_name | + | string | Фамилия получателя как в паспорте |
middle_name | - | string | Отчество получателя как в паспорте, если есть |
date_of_birth | - | string | Дата рождения получателя в формате ГГГГ-ММ-ДД. Убедитесь, что возраст получателя 18+ |
currency | + | string | Валюта выплаты. Возможные значения: TRY , USD |
contacts | + | object | Контакты получателя |
phone | + | object | Телефон получателя |
full_number | + | string | Полный номер телефона получателя в формате +<код страны><номер> |
country_iso3 | + | string | Код страны, к которой относится номер телефона получателя, в формате ISO3 |
operator_code | + | string | Код оператора телефонного номера получателя |
short_number | + | string | Номер телефона получателя, без кода оператора |
- | string | Email получателя | |
cash_details | + | object | Дополнительная информация о платеже наличными |
shift | + | string | Номер кассовой смены |
Пример запроса
{
"payment_details": {
"type": "moneysend",
"moneysend": {}
},
"amount_details": {
"amount": 1000,
"currency": "rub"
},
"participant_details": {
"sender": {
"citizenship_country_iso3": "AUS",
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"country_iso3": "RUS",
"state": "New York",
"city": "Kazan",
"postal_code": "420000",
"street": "Nekrasova",
"building": "1",
"flat": "131",
"tax_reference": "123456789012",
"date_of_birth": "2010-01-01",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
},
"identity_document": {
"id_type": "Паспорт гражданина Российской Федерации",
"id_number": "123456789",
"issue_date": "2020-01-01",
"id_expiration_date": "2030-01-01",
"division_code": "165-065",
"issued_by": "OVD Kazani"
},
"documents_foreigner": {
"id_type": "Виза",
"issued_by": "OVD Kazani",
"issue_date": "2020-01-01",
"id_expiration_date": "2030-01-01"
},
"service_point": {
"id": "1",
"name": "point_on_lenina",
"country_iso3": "RUS",
"state": "Moscow",
"city": "Moscow",
"oktmo": "36634436111",
"street": "Lenin avenue",
"house": "1",
"terminal_id": "123124"
},
"source_of_money": "salary",
"description": "salary transfers"
},
"recipient": {
"first_name": "Ivan",
"last_name": "Sidorov",
"middle_name": "Ivanovich",
"date_of_birth": "2010-01-01",
"currency": "TRY",
"contacts": {
"phone": {
"full_number": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"email": "test@test.com"
}
}
},
"cash_details": {
"shift": "11"
}
}
Параметры ответа
Название | Обязательность | Тип данных | Описание |
---|---|---|---|
status | + | string | Статус запроса |
session | + | object | Данные сессии |
id | + | string | ID сессии. Запомните его, он будет нужен для подтверждения/отклонения транзакции или для получения статуса по транзакции |
status | + | string | Текущий статус сессии. Возможные значения |
created_at | + | string | Дата и время создания сессии в формате RFC 3339. Пример: 2022-11-15T15:38:50.255803Z |
updated_at | + | string | Дата и время обновления сессии в формате RFC 3339. Пример: 2022-11-15T15:38:50.255803Z |
error | - | object | Причина ошибки. Возвращается только если была ошибка по сессии |
description | - | string | Описание ошибки |
code | - | string | Код ошибки |
acquiring_payments | + | array | Данные платежа |
id | + | string | ID платежа |
status | + | string | Текущий статус платежа. Возможные значения |
created_at | + | string | Дата и время создания платежа в формате RFC 3339. Пример: 2022-11-15T15:38:50.255803Z |
payment_details | + | object | Объект payment_details , переданный в запросе |
amount_details | + | object | Объект amount_details , переданный в запросе |
participant_details | + | object | Объект participant_details , переданный в запросе |
error | - | object | Причина ошибки. Возвращается только если была ошибка по сессии |
description | - | string | Описание ошибки |
code | - | string | Код ошибки |
Пример успешного ответа
{
"status": "ok",
"session": {
"id": "ps_592245",
"status": "in_progress",
"created_at": "2022-11-15T15:38:50.255803Z",
"updated_at": "2022-11-15T15:38:50.336303Z",
"acquiring_payments": [
{
"id": "pm_296251",
"status": "in_progress",
"created_at": "2022-11-15T15:38:50.357833Z",
"payment_details": {
"type": "moneysend",
"moneysend": {}
},
"amount_details": {
"amount": 978,
"currency": "rub"
},
"participant_details": {
"sender": {
"citizenship_country_iso3": "AUS",
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"country_iso3": "RUS",
"state": "New York",
"city": "Kazan",
"postal_code": "420000",
"street": "Nerkasova",
"building": "1",
"flat": "131",
"tax_reference": "123456789012",
"date_of_birth": "2010-01-01",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
},
"identity_document": {
"id_type": "Паспорт гражданина Российской Федерации",
"id_number": "123456789",
"issue_date": "2020-01-01",
"id_expiration_date": "2030-01-01",
"division_code": "165-065",
"issued_by": "OVD Kazani"
},
"documents_foreigner": {
"id_type": "Виза",
"issued_by": "OVD Kazani",
"issue_date": "2020-01-01",
"id_expiration_date": "2030-01-01"
},
"service_point": {
"id": "1",
"name": "point_on_lenina",
"country_iso3": "RUS",
"state": "Moscow",
"city": "Moscow",
"oktmo": "36634436111",
"street": "Lenin avenue",
"house": "1",
"terminal_id": "123124"
},
"source_of_money": "salary",
"description": "salary transfers"
},
"recipient": {
"first_name": "Ivan",
"last_name": "Sidorov",
"middle_name": "Ivanovich",
"date_of_birth": "2010-01-01",
"currency": "TRY",
"contacts": {
"phone": {
"full_number": "+79376151530",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"email": "test@test.com"
}
}
}
}
]
}
}
Пример неуспешного ответа
{
"error": {
"code": "invalid_request",
"description": "participant_details.recipient.full_name.not_blank"
},
"status": "error"
}
Вебхук ready_to_confirm
Банк 131 отправляет этот вебхук, когда готов провести транзакцию и ожидает
либо ее подтверждение методом session/confirm
, либо отмену методом
session/cancel
.
В вебхуке в объекте confirm_information
будет содержаться подробная
информация о сумме к выплате, комиссии за транзакцию и курсе конвертации.
"confirm_information"
● Source — сумма в валюте принятых средств
● Destination — сумма и валюта к выплате
● Fx_rate — курс конвертации
● Commission — комиссия с отправителя, взимается дополнительно к Source
Объект confirm_information
нужно будет передать в методе session/confirm
.
Также в вебхуке будет содержаться параметр tcn_code_encoded
, который
является контрольным номером перевода. Его необходимо сообщить
Получателю, так как без него будет невозможно получить перевод.
tcn_code_encoded
обернут в BASE64, его необходимо декодировать.
Пример вебхука
{
"type": "ready_to_confirm",
"session": {
"id": "ps_1",
"status": "in_progress",
"created_at": "2022-11-15T13:22:31.847352Z",
"updated_at": "2022-11-15T13:22:32.638464Z",
"acquiring_payments": [
{
"id": "pm_1",
"status": "pending",
"created_at": "2022-11-15T13:22:32.132993Z",
"payment_details": {
"type": "moneysend",
"moneysend": {}
},
"amount_details": {
"amount": 9782,
"currency": "RUB"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanov Ivanovich",
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"tax_reference": "123456789012",
"country_iso3": "RUS",
"city": "Kazan",
"postal_code": "420000",
"building": "1",
"date_of_birth": "2008-01-01",
"street": "Nerkasova",
"flat": "131",
"state": "New York",
"description": "salary transfers",
"identity_document": {
"id_type": "Паспорт гражданина Российской Федерации",
"id_number": "123456789",
"issue_date": "2020-01-01",
"division_code": "165-065",
"issued_by": "OVD Kazani",
"id_expiration_date": "2030-01-01"
},
"citizenship_country_iso3": "AUS",
"documents_foreigner": {
"id_type": "Виза",
"issue_date": "2020-01-01",
"issued_by": "OVD Kazani",
"id_expiration_date": "2030-01-01"
},
"service_point": {
"id": "1",
"name": "point_on_lenina",
"country_iso3": "RUS",
"state": "Moscow",
"city": "Moscow",
"oktmo": "36634436111",
"street": "lenin avenue",
"house": "1",
"terminal_id": "123124"
},
"source_of_money": "salary"
},
"recipient": {
"full_name": "Ivan Sidorov Ivanovich",
"first_name": "Ivan",
"last_name": "Sidorov",
"middle_name": "Ivanovich",
"date_of_birth": "2008-11-08",
"currency": "TRY",
"contacts": {
"phone": {
"full_number": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"email": "test@test.com"
}
}
}
}
],
"next_action": "confirm"
},
"confirm_information": {
"exchanges": [
{
"id": "pm_1",
"source": {
"amount": 1000,
"currency": "RUB"
},
"destination": {
"amount": 300,
"currency": "TRY"
},
"fx_rate": "0.3000",
"commission": {
"amount": 100,
"currency": "RUB"
}
}
]
},
"details": {
"tcn_code_encoded": "NTkyMTc0LTY5NDEyMjEx"
}
}
Метод POST.../api/v1/session/confirm
Метод предназначен для подтверждения платежа после получения вебхука ready_to_confirm
и получения подтверждения от Отправителя согласия с
суммой зачисления, курсом конвертации и комиссией.
В методе нужно передать объект confirm_information
в том же виде, в котором он передается в вебхуке ready_to_confirm
.
Параметры запроса
Название | Обязательность | Тип данных | Описание |
---|---|---|---|
session_id | + | string | ID сессии из ответа на инициацию транзакции |
confirm_information | + | object | Объект confirm_information из вебхука ready_to confirm без изменений |
exchanges | + | object | Объект с дополнительными данными |
id | + | string | ID транзакции |
source | + | object | Параметры приема средств |
amount | + | float | Сумма в минорных значениях (копейках) |
currency | + | string | Валюта |
destination | + | object | Параметры выдачи средств |
amount | + | float | Сумма в минорных значениях (копейках) |
currency | + | string | Валюта |
fx_rate | + | string | Курс конвертации |
commission | + | object | Параметры комиссии |
amount | + | float | Сумма в минорных значениях (копейках) |
currency | + | string | Валюта |
Пример запроса
{
"session_id": "ps_1",
"confirm_information": {
"exchanges": [
{
"id": "pm_1",
"source": {
"amount": 1000,
"currency": "RUB"
},
"destination": {
"amount": 300,
"currency": "TRY"
},
"fx_rate": "0.3000",
"commission": {
"amount": 100,
"currency": "RUB"
}
}
]
}
}
Параметры ответа
Содержимое ответа совпадает с содержанием ответа на запрос bpa/session/init/payment
.
Пример ответа
{
"status": "ok",
"session": {
"id": "ps_1634163",
"status": "in_progress",
"created_at": "2023-12-20T10:08:08.807876Z",
"updated_at": "2023-12-20T10:08:40.947967Z",
"acquiring_payments": [
{
"id": "pm_1062803",
"status": "in_progress",
"created_at": "2023-12-20T10:08:08.924899Z",
"customer": {
"reference": "customer_reference"
},
"payment_details": {
"type": "moneysend",
"moneysend": {}
},
"amount_details": {
"amount": 45000,
"currency": "RUB"
},
"participant_details": {
"sender": {
"full_name": "Gabriil Akulov",
"first_name": "Gabriil",
"last_name": "Akulov",
"middle_name": "",
"country_iso3": "RUS",
"city": "Кашира",
"postal_code": "761290",
"building": "39",
"date_of_birth": "1998-03-15",
"street": "наб. Будапештсткая",
"flat": "1",
"state": "Свердловская область",
"description": "описание описания",
"identity_document": {
"id_type": "Паспорт гражданина Российской Федерации",
"id_number": "7012 244588",
"issue_date": "2020-03-01",
"division_code": "",
"issued_by": "ОВД ПО Кировскому району"
},
"citizenship_country_iso3": "RUS",
"service_point": {
"id": "1",
"name": "точка на Ленина",
"country_iso3": "RUS",
"state": "Москва",
"city": "Москва",
"street": "Ленина",
"house": "1",
"oktmo": "36634436111",
"terminal_id": "345"
},
"source_of_money": "зарплата",
"contacts": {
"phone": {
"full_number": "+79376151530",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "6151530"
}
}
},
"recipient": {
"full_name": "samidov burac",
"first_name": "samidov",
"last_name": "burac",
"middle_name": "",
"date_of_birth": "2005-03-15",
"currency": "TRY",
"contacts": {
"phone": {
"full_number": "+43523452345",
"country_iso3": "TUR",
"operator_code": "352",
"short_number": "3452345"
}
}
}
}
}
],
"actions": {
"confirm": "2023-12-20T10:09:01.904212Z"
}
}
}
Метод POST../api/v1/session/cancel
Метод предназначен для отмены платежа.
Параметры запроса
Название | Обязательность | Тип данных | Описание |
---|---|---|---|
session_id | + | string | ID сессии из ответа на инициацию транзакции |
Пример запроса
"session_id": "ps_1"
Параметры ответа
Содержимое ответа совпадает с содержанием ответа на запрос bpa/session/init/payment
.
Пример ответа
{
"status": "ok",
"session": {
"id": "ps_1634164",
"status": "in_progress",
"created_at": "2023-12-20T10:09:30.979373Z",
"updated_at": "2023-12-20T10:09:47.084110Z",
"acquiring_payments": [
{
"id": "pm_1062804",
"status": "pending",
"created_at": "2023-12-20T10:09:31.100292Z",
"customer": {
"reference": "customer_reference"
},
"payment_details": {
"type": "moneysend",
"moneysend": {}
},
"amount_details": {
"amount": 45000,
"currency": "RUB"
},
"participant_details": {
"sender": {
"full_name": "Gabriil Akulov",
"first_name": "Gabriil",
"last_name": "Akulov",
"middle_name": "",
"country_iso3": "RUS",
"city": "Кашира",
"postal_code": "761290",
"building": "39",
"date_of_birth": "1998-03-15",
"street": "наб. Будапештсткая",
"flat": "1",
"state": "Свердловская область",
"description": "описание описания",
"identity_document": {
"id_type": "Паспорт гражданина Российской Федерации",
"id_number": "7012 244588",
"issue_date": "2020-03-01",
"division_code": "",
"issued_by": "ОВД ПО Кировскому району"
},
"citizenship_country_iso3": "RUS",
"service_point": {
"id": "1",
"name": "точка на Ленина",
"country_iso3": "RUS",
"state": "Москва",
"city": "Москва",
"street": "Ленина",
"house": "1",
"oktmo": "36634436111",
"terminal_id": "345"
},
"source_of_money": "зарплата",
"contacts": {
"phone": {
"full_number": "+79376151530",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "6151530"
}
}
},
"recipient": {
"full_name": "samidov burac",
"first_name": "samidov",
"last_name": "burac",
"middle_name": "",
"date_of_birth": "2005-03-15",
"currency": "TRY",
"contacts": {
"phone": {
"full_number": "+43523452345",
"country_iso3": "TUR",
"operator_code": "352",
"short_number": "3452345"
}
}
}
}
}
]
}
}
Метод POST../api/v1/session/status
При необходимости платежный партнер может использовать данный метод для получения информации по сессии. Подробнее о том, что такое платежная сессия.
Возможные статусы сессии
Параметры запроса
Название | Обязательность | Тип данных | Описание |
---|---|---|---|
session_id | + | string | ID сессии из ответа на инициацию транзакции |
Пример запроса
"session_id": "ps_1"
Пример ответа
{
"status": "ok",
"session": {
"id": "ps_1",
"status": "in_progress",
"created_at": "2022-11-15T15:38:50.255803Z",
"updated_at": "2022-11-15T15:38:50.336303Z",
"acquiring_payments": [
{
"id": "pm_1",
"status": "in_progress",
"created_at": "2022-11-15T15:38:50.357833Z",
"payment_details": {
"type": "moneysend",
"moneysend": {}
},
"amount_details": {
"amount": 1000,
"currency": "rub"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanov Ivanovich",
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"tax_reference": "123456789012",
"country_iso3": "RUS",
"city": "Kazan",
"postal_code": "420000",
"building": "1",
"date_of_birth": "2008-01-01",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
},
"street": "Nerkasova",
"flat": "131",
"state": "New York",
"description": "salary transfers",
"identity_document": {
"id_type": "Паспорт гражданина Российской Федерации",
"id_number": "123456789",
"issue_date": "2020-01-01",
"division_code": "165-065",
"issued_by": "OVD Kazani",
"id_expiration_date": "2030-01-01"
},
"citizenship_country_iso3": "AUS",
"documents_foreigner": {
"id_type": "Виза",
"issue_date": "2020-01-01",
"issued_by": "OVD Kazani",
"id_expiration_date": "2030-01-01"
},
"service_point": {
"id": "1",
"name": "point_on_lenina",
"country_iso3": "RUS",
"state": "Moscow",
"city": "Moscow",
"oktmo": "36634436111",
"street": "Lenin avenue",
"house": "1",
"terminal_id": "123124"
},
"source_of_money": "salary"
},
"recipient": {
"full_name": "Ivan Sidorov Ivanovich",
"first_name": "Ivan",
"last_name": "Sidorov",
"middle_name": "Ivanovich",
"date_of_birth": "2008-11-08",
"currency": "TRY",
"contacts": {
"phone": {
"full_number": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"email": "test@test.com"
}
}
}
}
]
}
}
Вебхук payment_finished
Банк отправляет этот вебхук, когда завершает транзакцию.
В теле вебхука приходят все параметры транзакции, в том числе ее статус (в поле
status
). Если статус сессии succeeded
, это значит, что оплата
прошла успешно.
Подробное описание вебхука приведено здесь.