Выплата с номинального счета на банковский счет

Этот сценарий описывает отправку выплаты на банковский счет c номинального счета. Выплата будет произведена в два списания, одно на сумму платежа, другое на комиссию (если комиссия применяется). Эти списания будут отражены в банковской выписке в онлайн-банке. API позволяет отправлять выплаты самозанятым, ИП, физическим и юридическим лицам на счета в российских банках. Все параметры передаются в открытом виде.

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

На какие счета можно отправить

Вы можете отправить выплаты только на счета, которые начинаются с этих цифр:

40817810
42301810
42302810
42303810
42304810
42305810
42306810
42307810
40802810
40702810 (для счетов юридических лиц)
40701810
40502810

Если счет начинается с других цифр, выплата не пройдет.

Шаг 1. Начните выплату

Отправьте запрос на создание платежной сессии c одновременным стартом выплаты session/init/payout/nominal.

Параметры

Для резидентов
Для нерезидентов

Название	Обязательность	Тип	Описание
payment_method	+	object	Платежные данные
type	+	string	Значение: `bank_account`
bank_account	+	object	Банковский счет
system_type	+	string	Система банковских переводов. Всегда: `ru`
ru	+	object	Объект банковского счета
bik	+	string	БИК банка получателя
account	+	string	Банковский счет получателя
full_name	+	string	ФИО физического лица. В случае выплаты на счет ИП, передается в следующем формате: `ИП <ФИО>`
inn	- (обязательно для выплат на счета юридических лиц или ИП)	string	ИНН
kpp	- (обязательно для выплат на счета юридических лиц)	string	КПП
description	+	string	Назначение выплаты. Как сформировать
participant_details	+	object	Информация об участниках выплаты
sender	+	object	Данные отправителя
account	+	string	Номер банковского номинального счета, с которого будет осуществляться выплата
beneficiary_id	+	string	ИНН бенефициара или выгодоприобретателя
recipient	+	object	Данные получателя
beneficiary_id	+	string	ИНН бенефициара или выгодоприобретателя. Не заполняется при выплатах по СБП
amount_details	+	object	Сумма
amount	+	int	Сумма в копейках. Значение должно быть больше нуля. Чтобы передать 100 рублей, укажите `10000`
currency	+	string	Код валюты согласно ISO 4217. Регистр не важен. Всегда: `rub`

Название	Обязательность	Тип	Описание
payment_method	+	object	Платежные данные
type	+	string	Значение: `bank_account`
bank_account	+	object	Банковский счет
system_type	+	string	Система банковских переводов. Всегда: `ru`
ru	+	object	Объект банковского счета
bik	+	string	БИК банка получателя
inn	- (обязательно для выплат на счета юридических лиц или ИП)	string	ИНН получателя
kpp	- (обязательно для выплат на счета юридических лиц)	string	KПП получателя
account	+	string	Банковский счет получателя
full_name	+	string	ФИО физического лица. В случае выплаты на счет ИП, передается в следующем формате: `ИП <ФИО>`. При выплате юридическому лицу — наименование юрлица, если предусмотрено договором. Важно: если наименование или ФИО указано некорректно, банк-получатель может отказать в зачислении и деньги вернутся на счет отправителя
description	+	string	Назначение выплаты с кодом валютной операции (согласуется с менеджером в Банке 131). Как сформировать
amount_details	+	object	Сумма
amount	+	int	Сумма в копейках. Значение должно быть больше нуля. Чтобы передать 100 рублей, укажите `10000`
currency	+	string	Код валюты согласно ISO 4217. Регистр не важен. Всегда: `rub`
participant_details	+	object	Информация об участниках выплаты
sender	+	object	Данные отправителя
full_name	- (обязательно, если отправитель — физическое лицо)	string	Имя
company_name	- (обязательно, если отправитель — юридическое лицо)	string	Название компании
address_line	+	string	Адрес. Важно: страну и город необходимо указать в следующих полях, в данном поле их дублировать не нужно
country_iso3	+	string	Страна (ISO-3166-1 alpha-3)
city	+	string	Город
recipient	+	object	Данные получателя
full_name	+	string	Имя получателя

Как заполнять данные бенефициара

Для выплат с номинального счета необходимо указывать данные бенефициара. В качестве данных бенефициара мы ожидаем получить ИНН бенефициара. Данные бенефициара указываются в объекте participant_details, в списке данных отправителя sender или данных получателя recipient. Если ваш бенефициар является отправителем, укажите его ИНН в блоке sender, если он является получателем, то укажите в блоке recipient. До старта выплат вам необходимо передать список данных ваших бенефициаров Вашему менеджеру.

Как формировать назначение выплаты

В назначении выплаты (поле bank_account.ru.description) по российским законам необходимо указывать:

вид операции (например, оплата услуг),
основание платежа (например, договор №),
наименование работ, услуг, товаров,
облагается НДС или нет.

Если ваша организация зарегистрирована не в России, необходимо добавить код вида валютной операции в следующем формате: {VO<код вида валютной операции>} без отступов и пробелов. Код необходимо согласовать заранее с менеджером в Банке 131.

Назначение выплаты не должно содержать следующие символы: ?, !. Максимальная длина: 210 символов.

Примеры назначения выплаты

Для резидентов
Для нерезидентов

Перевод средств по договору № 5015553456 Иванов Иван Иванович НДС не облагается

{VO99090} Перевод средств по договору № 5015553456 Иванов Иван Иванович НДС не облагается

Примеры запросов для выплат

Физическим лицам
Юридическим лицам

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-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: signature' \
-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"
    }
  }
}'

Шаг 2. Дождитесь уведомления о готовности сделать выплату

Банк 131 отправит вам вебхук ready_to_confirm. В теле вебхука придут все данные для выплаты. Вам необходимо сохранить объект confirm_information — он понадобится для подтверждения выплаты.

В ответ следует отдавать HTTP-код 200.

Пример вебхука

curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "ready_to_confirm",
  "session": {
    "id": "ps_260159",
    "status": "in_progress",
    "created_at": "2023-01-17T13:41:59.352487Z",
    "updated_at": "2023-01-17T13:42:01.657512Z",
    "payments": [
      {
        "id": "po_67428",
        "status": "pending",
        "created_at": "2023-01-17T13:41:59.594022Z",
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bik": "049205131",
              "account": "40702810300000000006",
              "full_name": "Наименование организации-получателя",
              "description": "Перечисление денежных средств по договору № 1 НС от 01.09.2021 комиссия площадки за декабрь 2022 г. НДС не облагается.",
              "is_fast": false
            }
          }
        },
        "amount_details": {
          "amount": 2700,
          "currency": "RUB"
        },
        "amounts": {
          "net": {
            "amount": 2700,
            "currency": "RUB"
          }
        }
      }
    ]
  }
}'  

Шаг 3. Подтвердите или отмените выплату

Проверьте данные для выплаты и подтвердите, что готовы её провести (с помощью запроса session/confirm) или отмените (отправьте запрос session/cancel). При подтверждении выплаты объект confirm_information` является обязательным. Данный запрос является платежным поручением на перевод денежных средств.

Пример запроса session/confirm

curl -X POST \
https://demo.bank131.ru/api/v1/session/confirm \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_1048967",
  "confirm_information": {
    "account_details": {
      "sender": {
        "account_number": "40702810300200000013",
        "name": "Наименование партнера Банка 131",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822029205131",
        "inn": "3316004790",
        "kpp": "156605101"
      },
      "recipient": {
        "account_number": "40702810300000000006",
        "name": "Наименование организации-получателя",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822029205131"
      }
    }
  }
}'   

Пример запроса session/confirm

curl -X POST \
https://demo.bank131.ru/api/v1/session/cancel \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_1048967",
  "confirm_information": {
    "account_details": {
      "sender": {
        "account_number": "40702810300200000013",
        "name": "Наименование партнера Банка 131",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822029205131",
        "inn": "3316004790",
        "kpp": "156605101"
      },
      "recipient": {
        "account_number": "40702810300000000006",
        "name": "Наименование организации-получателя",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822029205131"
      }
    }
  }
}'

Шаг 4. Дождитесь уведомления о результате выплаты

Банк 131 отправит вам вебхук payment_finished. В теле вебхука придут все данные, с которыми проводилась выплата. Результат выплаты приходит в поле payment.status.

Если статус succeeded, значит, выплата прошла успешно. Если статус failed — выплата не прошла из-за ошибки.

Подробнее о статусах выплаты

Возврат выплаты

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

Если у вас подключены вебхуки, в случае возврата вы получите вебхук payment_refunded. Если вебхуки у вас отключены, вы можете узнать про возвраты следующими способами:

С помощью запроса session/status.
С помощью реестра выплат.

Тестирование работы выплат

Вы можете протестировать работоспособность выплат с номинального счета. Для этого в вебхуке ready_to_confirm используйте объект confirm_information. В нем передаются тестовые данные, которые нужно отправить с запросом session/confirm. Они заполняются на сервере и используются только для тестирования.

Для проведения тестирования:

Отправьте запрос на создание платежной сессии.
Проверьте статус платежной сессии.
Дождитесь вебхука.
Отправьте запрос с тестовыми данными.
Проверьте статус платежной сессии.

Объект `confirm_information`

Объект с тестовыми данным для формирования запроса ready_to_confirm.

Название	Тип	Описание
confirm_information	object	Объект для тестирования выплаты
account_details	object	Объект с информацией о счетах отправителя и получателя
sender	object	Объект с тестовой информацией о счете отправителя
account_number	string	Номер счета отправителя
name	string	Имя отправителя
bank_name	string	Название банка отправителя
bik	string	БИК банка отправителя
correspondent_account_number	string	Корреспондентский счет отправителя
inn	string	ИНН банка отправителя
kpp	string	КПП банка отправителя
recipient	object	Объект с тестовой информацией о счете получателя
account_number	string	Номер счета получателя
name	string	Имя получателя
bank_name	string	Название банка получателя
bik	string	БИК банка получателя
correspondent_account_number	string	Корреспондентский счет получателя
inn	string	ИНН банка получателя
kpp	string	КПП банка получателя

Шаг 1. Создайте платежную сессию c одновременным стартом выплаты

Отправьте запрос session/init/payout/rko с необходимыми данными для инициализации платежной сессии.

Пример создания сессии

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout/rko \
--header 'X-PARTNER-PROJECT: your_project_name' \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "system_type": "ru",
      "ru": {
        "bik": "044525974",
        "account": "40702810500000000001",
        "full_name": "ООО Ромашки",
        "inn": "3316004790",
        "kpp": "156605101",
        "description": "Выплата"
      }
    }
  },
  "amount_details": {
    "amount": 350,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810900000000011"
    }
  }
}'

Шаг 2. Проверьте статус платежной сессии

Проверьте статус созданной платежной сессии в запросе session/status. Если все готово к дальнейшему прохождению транзакции, то вы получите параметр "session.next_action": "confirm" в ответе.

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

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

Шаг 3. Дождитесь вебхука с объектом `confirm_information`

Дождитесь вебхука ready_to_confirm с объектом confirm_information. Этот объект будет необходим для проведения дальнейшего тестирования.

Пример вебхука

{
  "type": "ready_to_confirm",
  "session": {
    "id": "ps_2643",
    "status": "in_progress",
    "created_at": "2024-02-20T08:42:35.905869Z",
    "updated_at": "2024-02-20T08:42:36.382627Z",
    "payments": [
      {
        "id": "po_513",
        "status": "pending",
        "created_at": "2024-02-20T08:42:35.965210Z",
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bik": "044525974",
              "account": "40702810500000000001",
              "full_name": "ООО Ромашки",
              "description": "Выплата",
              "is_fast": false,
              "kpp": "156605101",
              "inn": "3316004790"
            }
          }
        },
        "amount_details": {
          "amount": 350,
          "currency": "RUB"
        },
        "amounts": {
          "net": {
            "amount": 350,
            "currency": "RUB"
          },
          "gross": {
            "amount": 350,
            "currency": "RUB"
          }
        },
        "paymentMetadata": {},
        "participant_details": {
          "sender": {
            "account": "40702810900000000011"
          }
        },
        "payment_options": {
          "recurrent": false,
          "is_subsequent": false
        }
      }
    ],
    "next_action": "confirm",
    "session_metadata": {}
  },
  "confirm_information": {
    "account_details": {
      "sender": {
        "account_number": "account_number",
        "name": "name",
        "bank_name": "bank_name",
        "bik": "bik",
        "correspondent_account_number": "correspondent_account_number",
        "inn": "inn",
        "kpp": "kpp"
      },
      "recipient": {
        "account_number": "40702810500000000001",
        "name": "ООО Ромашки",
        "bank_name": "bank_name",
        "bik": "bik",
        "correspondent_account_number": "correspondent_account_number",
        "inn": "3316004790",
        "kpp": "156605101"
      }
    }
  }
}

Шаг 4. Отправьте объект `confirm_information` для проверки выплат

Скопируйте из полученного ответа объект confirm_information и отправьте его в запросе session/confirm.

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

curl -X POST \
https://demo.bank131.ru/api/v1/session/confirm \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_2643",
  "confirm_information": {
    "account_details": {
      "sender": {
        "account_number": "account_number",
        "name": "name",
        "bank_name": "bank_name",
        "bik": "bik",
        "correspondent_account_number": "correspondent_account_number",
        "inn": "inn",
        "kpp": "kpp"
      },
      "recipient": {
        "account_number": "40702810500000000001",
        "name": "ООО Ромашки",
        "bank_name": "bank_name",
        "bik": "bik",
        "correspondent_account_number": "correspondent_account_number",
        "inn": "3316004790",
        "kpp": "156605101"
      }
    }
  }
}'

Шаг 5. Проверьте статус тестовой платежной сессии

Проверьте статус тестовой платежной сессии в запросе session/status. Если платежная сессия была успешно проведена, то вы получите объект session.action с данными о всех операциях (в рамках одной тестовой сессии) в ответе.

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

curl --location 'https://demo.bank131.ru/api/v1/session/status' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--header 'X-PARTNER-SIGN: signature' \
--header 'Content-Type: application/json' \
--data '{
    "session_id": "ps_2643"
}'

На какие счета можно отправить​

Шаг 1. Начните выплату​

Параметры​

Как заполнять данные бенефициара​

Как формировать назначение выплаты​

Шаг 2. Дождитесь уведомления о готовности сделать выплату​

Шаг 3. Подтвердите или отмените выплату​

Шаг 4. Дождитесь уведомления о результате выплаты​

Возврат выплаты​

Тестирование работы выплат​

Объект confirm_information​

Шаг 1. Создайте платежную сессию c одновременным стартом выплаты​

Шаг 2. Проверьте статус платежной сессии​

Шаг 3. Дождитесь вебхука с объектом confirm_information​

Шаг 4. Отправьте объект confirm_information для проверки выплат​

Шаг 5. Проверьте статус тестовой платежной сессии​

На какие счета можно отправить

Шаг 1. Начните выплату

Параметры

Как заполнять данные бенефициара

Как формировать назначение выплаты

Шаг 2. Дождитесь уведомления о готовности сделать выплату

Шаг 3. Подтвердите или отмените выплату

Шаг 4. Дождитесь уведомления о результате выплаты

Возврат выплаты

Тестирование работы выплат

Объект `confirm_information`

Шаг 1. Создайте платежную сессию c одновременным стартом выплаты

Шаг 2. Проверьте статус платежной сессии

Шаг 3. Дождитесь вебхука с объектом `confirm_information`

Шаг 4. Отправьте объект `confirm_information` для проверки выплат

Шаг 5. Проверьте статус тестовой платежной сессии