Расщепление платежей

Функциональность Расщепление e-commerce платежей дает возможность разделить сумму платежа, поступившего на транзитный счет в рамках интернет-эквайринга на несколько частей. Затем части платежа зачисляются на текущие счета или платежные карты бенефициаров. Ниже приведено описание функциональности и API запросов мерчанта.

Описание

Регистрация Мерчанта-партнера

1. Mерчант-агрегатор (далее МА) отправляет запрос на регистрацию мерчанта-партнера (далее МП) с указанием данных о клиенте, контракта и счета в Банк.
2. Банк осуществляет проверки.
3. Банк создает данные о Клиенте, счете и контракте МП с присвоением ему регистрационного номера.
4. Банк отправляет ответ на запрос регистрации МП МА с указанием регистрационных номеров МП.
5. Банк осуществляет проверку наличия клиента МП в разрезе МА, сформировавшего запрос. Если данные присутствуют, то Банк отправляет ответ на запрос регистрации МП МА с указанием кода ошибки -346100500 - PARTNER_ALREADY_REGISTERED.
6. Если не удается получить ответ на запрос создания клиента, контракта, постоянного платежного поручения (далее ППП) в течение указанного времени ожидания ответа, продолжается повторная отправка запроса. Если по истечении заданного количества попыток не был получен успешный ответ, то Банк удаляет созданные данные и отправляет ответ на запрос регистрации МП МА с указанием кода ошибки -246100500 - EXTERNAL_COMMUNICATION_ERROR.

Редактирование данных о МП

1. Mерчант-агрегатор (далее МА) отправляет запрос на регистрацию мерчанта-партнера (далее МП) с указанием идентификатора клиента и изменяемыми данными в Прокси Банк.
2. Банк осуществляет проверки.
3. Банк осуществляет обработку запроса.
4. Банк возвращает ответ на запрос редактирования клиента, контракта, ППП.
5. Банк обновляет соответствующие данные о МП, контракте, счете.
6. Банк отправляет ответ на запрос регистрации МП МА.

• Если в результате проверки данные о МП не найдутся, то Банк отправляет ответ на запрос регистрации МП МА с указанием кода ошибки -346100501 - PARTNER_DOESNT_EXIST.
• Если в результате проверки уникальности изменяемых данных - хотя бы одни из изменяемых данных совпадают существующими, то Банк отправляет ответ на запрос регистрации МП МА с указанием кода ошибки -446100501 - SAME_DATA.

Проведение оплаты

1. МП формирует заказ.
2. МА выполняет запрос регистрации заказа с предавторизацией registerPreAuth.do.
3. Банк регистрирует заказ и возвращает orderId.
4. МП перенаправляется на платежную страницу и отправляет заполненные данные.
5. Банк выполняет проверки и осуществляет оплату.
6. МП перенаправляется в магазин, на финишную страницу.
7. МА производит запрос deposit.do и getOrderStatusExtended.do.
8. Банк возвращает МА paymentAmount/feeAmount, authRefNum.

Передача инструкций по расщеплению

1. МА отправляет запрос передачи инструкций на расщепление splitInstruction.do в Банк с указанием идентификатора заказа, RRN операции (поле referenceNumber), а также данных по расщеплению.
2. Банк выполняет необходимые проверки (отсутствие дублей инструкций, корректность данных и т.д.). В данном случае под дублями подразумеваются только инструкции в статусе PENDING (создана) и SUCCESS (обработана).
3. Банк отправляет расширенный запрос получения статуса заказа getOrderStatusExtension.do - получает успешный ответ.
4. По RRN заказа Банк определяет направление инструкций по расщеплению, полученных от МА, - инструкции относятся к возврату платежа (полному или частичному).
5. Банк проверяет состояние заказа - состояние заказа "4 - По транзакции была проведена операция возврата".
6. Банк проверяет наличие инструкций по расщеплению по прямым операциям (тип операции - "purchase") по тем МП, которые были переданы в запросе передачи инструкций на расщепление от МА, - инструкции найдены.
7. Банк проверяет наличие инструкций по расщеплению с отрицательной суммой к расщеплению (sign="-") - инструкций с отрицательными суммами не найдено.
8. Банк проверяет соответствие суммы возврата (refundedAmount), указанной в ответе на расширенный запрос получения статуса заказа, общей сумме расщепления, указанной во всех инструкциях запроса передачи инструкций на расщепление от МА, - сумма соответствует.

9. Банк сохраняет инструкции на расщепление в БД, указывая следующие данные:

   Поле	Описание
   splitId	Идентификатор инструкции в системе МА. Указывается по данным запроса передачи инструкции на расщепление от МА
   regNumber	Регистрационный номер МП. Указывается по данным запроса передачи инструкции на расщепление от МА
   status	Статус инструкции на расщепление - PENDING (создана)
   amount	Сумма расщепления. Указывается по данным запроса передачи инструкции на расщепление от МА
   type	Тип расщепления - refund (возвраты)
   id	Уникальный идентификатор инструкции

10. Банк обновляет статус инструкции на расщепление на SUCCESS (обработана).

11. Банк возвращает успешный ответ на запрос регистрации инструкции на расщепление splitInstruction.do.

• Если в результате проверки сохраненных дублей инструкций на расщепление найдены дубли, то Банк возвращает ответ с указанием кода ошибки 400 Bad Request.
• Если Банк получает неуспешный ответ на расширенный запрос получения статуса заказа "заказ не найден", то Банк возвращает ответ с указанием кода ошибки 400 Bad Request.
• Если Банк получает неуспешный ответ на расширенный запрос получения статуса заказа - "RRN не найден",то Банк возвращает ответ с указанием кода ошибки 400 Bad Request.
• Если состояние заказа отличается от "4 - По транзакции была проведена операция возврата", то Банк возвращает ответ с указанием кода ошибки -346100503 ORDER_IN_WRONG_STATE.
• Если инструкции по расщеплению по прямым операциям (тип операции - "1") не найдены, то Банк возвращает ответ с указанием кода ошибки 400 Bad Request.
• Если найдены инструкции с отрицательными суммами, то Банк возвращает ответ с указанием кода ошибки TBD NEGATIVE_SUM.
• Если при возврате сумма возврата refundedAmount не соответсвует указанной во всех инструкциях запроса передачи инструкций на расщепление, то Банк возвращает ответ с указанием кода ошибки 400 Bad Request.
• Если по истечении заданного количества попыток или времени на создание инструкции по расщеплению не был получен успешный ответ, то Банк обновляет статус инструкции на расщепление на ERROR (ошибка) и возвращает ответ с указанием кода ошибки 400 Bad Request.

Альтернативный сценарий

Если Банк определяет направление инструкций как относящиеся к прямому платежу, то Банк проверяет состояние заказа - состояние заказа "2 - Проведена полная авторизация суммы заказа". Затем шаги 7-11 выглядят так:

7а. Банк проверяет соответствие указанной в ответе на расширенный запрос получения статуса заказа суммы списания (depositedAmount) за вычетом размера комиссии, полученного в ответе на авторизационный запрос общей сумме расщепления с учетом знака расщепления, указанной во всех инструкциях запроса передачи инструкций на расщепление от МА, - сумма соответствует.

8а. Банк сохраняет инструкции на расщепление в БД, указывая следующие данные:

9а. Банк обновляет статус инструкции на расщепление на SUCCESS (обработана).

10а. Банк возвращает успешный ответ на запрос регистрации инструкции на расщепление splitInstruction.do.

API запросы

Для авторизации обращения к системе Банка в любом запросе со стороны магазина должны быть приведены имя и пароль магазина, полученные при регистрации магазина в системе. Взаимодействия реализуются как HTTP обращения методом POST на определенные URL. Body запроса должен содержать json-объект. Результат обработки запроса возвращается в виде JSON объекта. Например: {"errorCode":"12","errorMessage":"Empty amount"}.

Все текстовые поля должны иметь кодировку Юникод (UTF-8). Если в ответе на запрос errorCode (Код ошибки) = 0, это означает, что запрос был обработан платежным шлюзом без системных ошибок. При этом errorCode не отображает статус заказа.

Регистрация мерчанта-партнера

Запрос merchantPartner.do позволяет мерчанту-агрегатору создавать и редактировать сведения о мерчанте-партнере.

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

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

Примеры

Пример запроса - регистрация МП

POST /split-abb/partner/merchantPartner.do
headers:
User-Agent: [Apache-HttpClient/4.5.13 (Java/11.0.13)]
Connection: [keep-alive]
Host: [localhost:8088]
Accept-Encoding: [gzip,deflate]
Content-Length: [411]
Content-Type: [application/json;charset=UTF-8]
body:
{
  "userName": "**username**",
  "password": "**password**",
  "merchants": [
    {
      "type": "add",
      "unp": "623458985",
      "shortName": "merchant.ru",
      "companyName": "Рога и копыта",
      "companyTradeName": "Рога и копыта TradeName",
      "order": {
        "targetNumber": "723456789",
        "bic": "PJCBBY2X",
        "currency": "BYN"
      }
    }
  ]
}

Пример запроса - изменение МП

POST /split-abb/partner/merchantPartner.do
headers:
User-Agent: [Apache-HttpClient/4.5.13 (Java/11.0.13)]
Connection: [keep-alive]
Host: [localhost:8088]
Accept-Encoding: [gzip,deflate]
Content-Length: [411]
Content-Type: [application/json;charset=UTF-8]
body:
{
  "userName": "**username**",
  "password": "**password**",
  "merchants": [
    {
      "type": "edit",
      "regNumber": "SPLIT000087",
      "companyName": "Рога, копыта и хвост"
    }
  ]
}

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

status: 200
headers:
Date: [Tue, 29 Mar 2022 09:08:06 GMT]
Content-Type: [application/json]
body:
{"status": "COMPLETE", "merchants":[{"regNumber":"SPLIT000087","unp":"623458985","status":"SUCCESS","error":null}]}

Пример неуспешного ответа - попытка повторной регистрации МП

status: 200
headers:
Date: [Tue, 29 Mar 2022 09:20:42 GMT]
Content-Type: [application/json]
body:
{"status": "COMPLETE_WITH_ERRORS", "merchants":[{"regNumber":null,"unp":"623458985","status":"FAIL","error":{"errorCode":-346100500,"errorDesc":"Partner already registered"}}]}

Пример неуспешного ответа - неуспешная авторизация

HTTP/1.1 401 Unauthorized
Date: Tue, 29 Mar 2022 09:19:46 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 21
Authentication failed

Пример неуспешного ответа - неуспешная валидация

HTTP/1.1 400 Bad Request
Date: Tue, 29 Mar 2022 09:22:52 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 80
Validation failed for param [$.merchants[0].unp] with message: must be not blank

Передача инструкции по расщеплению

Запрос splitInstruction.do позволяет мерчанту-агрегатору отправлять инструкции на расщепление платежей по мерчант-партнеру.

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

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

Примеры

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

POST /split-abb/split/splitInstruction.do
headers:
User-Agent: [Apache-HttpClient/4.5.13 (Java/11.0.13)]
Connection: [keep-alive]
Host: [localhost:8088]
Accept-Encoding: [gzip,deflate]
Content-Length: [411]
Content-Type: [application/json;charset=UTF-8]
body:
{
  "userName": "**username**",
  "password": "**password**",
  "orderId": "5e97e3fd-1d20-4b4b-a542-f5995f5e8208",
  "referenceNumber": "123456789012",  
  "instructions": [
    {
      "splitId": "a2345lk3d",
      "regNumber": "SPLIT000087",
      "amount": "100",
      "sign": "+"
    }
  ]
}

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

status: 200
headers:
Date: [Tue, 29 Mar 2022 09:08:06 GMT]
Content-Type: [application/json]
body:
{"status": "COMPLETE", "instructions":[{"splitId":"a2345lk3d","regNumber":"SPLIT000087","amount":"100","sign":"+","status":"SUCCESS","error":null}]}

Пример неуспешного ответа - неуспешная авторизация

HTTP/1.1 401 Unauthorized
Date: Tue, 29 Mar 2022 09:19:46 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 21
Authentication failed

Пример неуспешного ответа - неуспешная валидация

HTTP/1.1 400 Bad Request
Date: Tue, 29 Mar 2022 09:22:52 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 80
Validation failed for param [$.merchants[0].unp] with message: must be not blank