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

Прием средств

На данной странице вы найдете методы и вебхуки, которые понадобятся платежному партнеру, отправляющему перевод. Общий порядок запросов следующий:

  • Платежный партнер инициирует платежную сессию и передает в Банк подробную информацию об Отправителе и Получателе методом 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-string12-значный ИНН отправителя
    date_of_birth+stringДата рождения отправителя в формате ГГГГ-ММ-ДД. Убедитесь, что возраст отправителя 18+
    contactsobjectКонтакты отправителя
      phoneobjectТелефон отправителя
        full_number+stringПолный номер телефона отправителя в формате +<код страны><номер>
        country_iso3+stringКод страны, к которой относится номер телефона отправителя, в формате ISO3
        operator_code+stringКод оператора телефонного номера отправителя
        short_number+stringНомер телефона отправителя без кода оператора
      email-stringEmail отправителя
    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-stringID точки приёма
      name-stringНазвание точки приема
      country-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Номер телефона получателя, без кода оператора
      email-stringEmail получателя
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": "Russia",
"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+stringID сессии. Запомните его, он будет нужен для подтверждения/отклонения транзакции или для получения статуса по транзакции
  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+stringID платежа
    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": "Russia",
"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": "Russia",
"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+stringID сессии из ответа на инициацию транзакции
confirm_information+objectОбъект confirm_information из вебхука ready_to confirm без изменений
  exchanges+objectОбъект с дополнительными данными
    id+stringID транзакции
    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+stringID сессии из ответа на инициацию транзакции

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

"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+stringID сессии из ответа на инициацию транзакции
Пример запроса
"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, это значит, что оплата прошла успешно. Подробное описание вебхука приведено здесь.