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

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

Ниже приведено описание функциональности и API запросов мерчанта.

В описании используются следующие термины:

• Мерчант-агрегатор (МА) - Торгово-сервисное предприятие (магазин, мерчант), предоставляющее услугу размещения на собственном сайте (MarketPlace) информации о товарах и возможность осуществления продажи товара через сайт МА.
• Мерчант-партнер (МП) - Мерчант, размещающий на сайте МА информацию о своих товарах на основании договора, заключенного с МА.
• WAY4 - Система для ведения контрактов эквайринга МА и МП, позволяющая обрабатывать e-commerce онлайн-платежи, а также обрабатывающая инструкции по расщеплению e-commerce платежей и отражающая суммы расщепления на счетах контрактов МП.

Описание

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

1. Mерчант-агрегатор (далее МА) отправляет запрос на регистрацию мерчанта-партнера (далее МП) merchantPartner.do, type=add с указанием данных о клиенте, контракта и счета в Банк.
2. Банк проверяет, что МП отсутствует в справочнике МП.
3. Банк создает МП с указанием данных мерчанта.
4. Банк проверяет, что отсутствуют данные о клиенте МП в разрезе МА.
5. Банк создает данные о клиенте, контракте, и счете МП в разрезе МА.
6. Банк взаимодействует с WAY4 для создания клиента и обновляет данные по контракту и счету МП в разрезе МА.
7. Банк отправляет МА ответ на запрос регистрации МП с указанием регистрационных номеров МП.

Возможные ошибки

• Если при проверке наличия клиента МП в разрезе МА, сформировавшего запрос,(шаг 4) данные о клиенте найдены, то Банк отправляет МА ответ на запрос регистрации МП с указанием кода ошибки -346100500 - PARTNER_ALREADY_REGISTERED.
• Если не удается получить ответ от WAY4 на запрос создания клиента, контракта и счета (шаг 6) в течение указанного времени ожидания ответа, продолжается повторная отправка запроса. Если по истечении заданного количества попыток не был получен успешный ответ, то Банк удаляет созданные данные и отправляет ответ на запрос регистрации МП МА с указанием кода ошибки -246100500 - EXTERNAL_COMMUNICATION_ERROR.

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

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

Возможные ошибки

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

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

Ниже описан типовой сценарий проведения оплаты - двухстадийная оплата, т.к. после отправки запроса deposit.do банк получает от WAY4 сумму комиссии, которая учитывается при подаче инструкций на расщепление. Но если у вас есть возможность получать комиссию иным способом, вы можете использовать одностадийную оплату с использованием запросов register.do и paymentorder.do (см. Прямые платежи).

1. Клиент формирует заказ.
2. МА выполняет запрос регистрации заказа с предавторизацией registerPreAuth.do.
3. Банк регистрирует заказ
4. Банк возвращает orderId.
5. Клиент перенаправляется на платежную страницу.
6. Клиент отправляет заполненные данные.
7. Банк проверяет вовлеченность карты в 3DS.
8. Клиент перенаправляется на платежную страницу.
9. Клиент выполняет авторизацию на ACS.
10. Банк выполняет блокировку денежных средств.
11. Клиент перенаправляется на страницу магазина.
12. Браузер клиента запрашивает результат.
13. МА отправляет запрос статуса заказа getOrderStatusExtended.do.
14. Банк возвращает ответ на запрос статуса заказа.
15. МА перенаправляет Клиента на финишную страницу.
16. МА отправляет запрос завершения оплаты deposit.do.
17. Банк взаимодействует с WAY4 для обработки запроса и получения суммы комиссии.
18. Банк возвращает ответ на запрос завершения оплаты.
19. МА отправляет запрос статуса заказа getOrderStatusExtended.do.
20. Банк возвращает ответ на запрос статуса заказа. При этом в поле paymentAmountInfo.feeAmount возвращается размер комиссии, а в параметре authRefNum - уникальный номер операции. Эти параметры нужно будет указать при передаче инструкций на расщепление.

Отмена оплаты

1. МА отправляет запрос отмены оплаты reverse.do в Банк.
2. Банк выполняет отмену оплаты.
3. Банк возвращает ответ на запрос отмены оплаты.
4. МА отправляет запрос статуса заказа getOrderStatusExtended.do.
5. Банк возвращает ответ на запрос статуса заказа.

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

1. МА отправляет запрос возврата refund.do в Банк.
2. Банк выполняет возврат.
3. Банк возвращает ответ на запрос возврата.
4. МА отправляет запрос статуса заказа getOrderStatusExtended.do.
5. Банк возвращает ответ на запрос статуса заказа. В поле refunds.referenceNumber возвращается уникальный идентификационный номер операции, который необходимо указать при передаче инструкций на расщепление.

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

1. МА отправляет запрос передачи инструкций на расщепление splitInstruction.do в Банк с указанием идентификатора заказа, уникального идентификатора операции (поле referenceNumber), а также данных по расщеплению.
2. Банк выполняет необходимые проверки (отсутствие дублей инструкций, корректность данных и т.д.), а также определяет направление инструкций по расщеплению, полученных от МА - инструкции относятся платежу или к возврату платежа (полному или частичному).
3. Банк сохраняет инструкции на расщепление в БД.
4. Банк взаимодействует с WAY4 для обработки каждой инструкции по расщеплению, указанной в запросе.
5. Банк возвращает успешный ответ на запрос регистрации инструкции на расщепление splitInstruction.do.

Возможные ошибки

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

API запросы

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

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

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

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

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

Параметры блока merchants:

Параметры блока order:

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

Параметры блока merchants:

Параметры блока error:

Примеры

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

curl --request POST \
  --url https://abby.rbsuat.com/split-abb/partner/merchantPartner.do \
  --header 'content-type: application/json;charset=UTF-8' \
  --data userName=username \
  --data password=password \
  --data merchants={"type": "add", "unp": "623458985", "shortName": "merchant.ru", "companyName": "Company Name", "companyTradeName": "Company TradeName"}'
  --data order={"targetNumber": "723456789", "bic": "PJCBBY2X", "currency": "BYN"}'

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

curl --request POST \
  --url https://abby.rbsuat.com/split-abb/partner/merchantPartner.do \
  --header 'content-type: application/json;charset=UTF-8' \
  --data userName=username \
  --data password=password \
  --data merchants={"type": "edit", "regNumber": "SPLIT000087", "companyName": "Companyname"}'

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

{   "status": "COMPLETE", 
    "merchants":[{
        "regNumber":"SPLIT000087",
        "unp":"623458985",
        "status":"SUCCESS",
        "error":null
        }
    ]
}

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

{
    "status": "COMPLETE_WITH_ERRORS", 
    "merchants":[{
        "regNumber":null,
        "unp":"623458985",
        "status":"FAIL",
        "error":{"errorCode":-346100500,"errorDesc":"Partner already registered"}
            }
        ]
    }

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

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

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

Параметры блока instructions:

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

Параметры блока instructions:

Примеры

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

curl --request POST \
  --url https://abby.rbsuat.com/split-abb/split/splitInstruction.do \
  --header 'content-type: application/json;charset=UTF-8' \
  --data userName=username \
  --data password=password \
  --data orderId=5e97e3fd-1d20-4b4b-a542-f5995f5e8208 \
  --data referenceNumber=123456789012 \
  --data instructions={"splitId": "a2345lk3d", "regNumber": "SPLIT000087", "amount": "100", "sign": "+"}'

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

{
    "status": "COMPLETE", 
    "instructions":[{
        "splitId":"a2345lk3d",
        "regNumber":"SPLIT000087",
        "amount":"100",
        "sign":"+",
        "status":"SUCCESS",
        "error":"null"
        }
    ]
}

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

{ 
    "errorDesc":"Authentication failed"
}

Ограничения

• Набор параметров Клиента и счета, который может быть изменен МА при отправке запроса на регистрацию МП, ограничен. В случае необходимости изменения других параметров обратитесь в Банк.
• Валюта платежа - Белорусский рубль.
• Банк не осуществляет контроль соответствия суммы к расщеплению по каждой инструкции, контроль осуществляется только на соответствие общей сумме инструкций по заказу.