Banks of Taiwan

Обзор

Banks of Taiwan — метод интернет-банкинга для проведения платежей через банки Тайваня. Для работы с этим методом доступно проведение оплат через Payment Page и Gate, выплат — через Gate и Dashboard (Old Dashboard).

Характеристика

Тип платёжного метода Интернет-банкинг
Регионы использования TW
Валюты платежей TWD
Конвертация валют на стороне ECommPay
Оплаты +
Выплаты +
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности
  • При проведении оплат пользователям рекомендуется подтверждать совершение оплаты на стороне банка в течение установленного времени. Если пользователь не подтверждает совершение оплаты в течение этого времени, то обработка платежа на стороне провайдера может занимать существенно большее время (вплоть до нескольких рабочих дней).
  • В запросах на оплаты с указанием валюты TWD необходимо округлять суммы до целых чисел. Если в запросе указывается иная валюта, то сумма платежа конвертируется на стороне ECommPay в эквивалентную сумму в валюте TWD и также округляется до целых чисел. При этом округление выполняется в большую сторону (например, если в результате конвертации получается сумма 3 000,05 TWD, то такая сумма округляется до 3 001,00 TWD).
Организация и стоимость подключения по согласованию с курирующим менеджером ECommPay

Схема работы

В проведении отдельного платежа с использованием Banks of Taiwan задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ECommPay, а также технические средства провайдера.



Основные операции

Интерфейсы Суммы, TWD Время**
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) минимум максимум базовое предельное
Оплаты + + 3 000,00 200 000,00 * *
Выплаты + + 3 000,00 200 000,00 * *

* Информацию необходимо уточнять у курирующего менеджера ECommPay.

** Базовое и предельное время определяются следующим образом:

  • Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
  • Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ECommPay.

Сценарии использования

Проведение оплат с использованием метода Banks of Taiwan выполняется с отображением платёжной инструкции пользователям, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.

Рис.: Оплата через Payment Page



Рис.: Оплата через Gate



Рис.: Выплата через Gate



Поддержка со стороны банков

Проведение платежей с применением метода Banks of Taiwan осуществляется через банки, поддерживающие работу с этим методом. Банкам соответствуют свои идентификаторы, которые используются при инициировании выплат через Gate.

Далее в таблице в ознакомительных целях представлена информация об этих банках, которую следует уточнять у курирующего менеджера ECommPay или по запросу /v2/info/banks/{payment_method}/{operationType}/list, отправляемым методом POST через Gate API: /v2/info/banks/taiwan/payout/list.

Запрос должен содержать идентификаторы проекта и платежа, подпись, валюту и сумму платежа, как указано в примере. Важно передавать реальные данные о платеже, но в случае если платёж еще не сформирован, для идентификатора платежа в запросе можно указать случайное значение.

Рис.: Пример запроса списка банков

{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "TWD"
  }
}
Табл. 1. Список банков
Банк ID
Bank of Kaohsiung 3131
Bank of Panhsin 3301
Bank of Taiwan 3031
Cathay United Bank 3121
Chang Hwa Bank 3081
Citibank 3161
COTA Commercial Bank Co.,Ltd. 3311
CTBC Bank 3441
DBS Bank (Taiwan) , Ltd. 4131
Entie Commercial Bank 3431
Far Eastern Int`l Bank 3341
First Commercial Bank 3061
Fubon Bank 3111
HSBC Bank 3261
Hua Nan Bank 3071
Hwatai Bank 3281
Jih Sun International Bank,Ltd. 3421
KGI Bank 3381
King's Town Bank 4101
Land Bank of Taiwan 3041
Mega International Commercial Bank 3141
O-Bank Co., Ltd. 4081
Shin Kong Commercial Bank 4121
Standard Chartered Bank 4091
Sunny Bank Ltd. 3291
Taichung Commercial Bank 3231
Taipei Star Bank 4111
Taishin International Bank 3401
Taiwan Business Bank 3211
Taiwan Cooperative Bank 3051
The Export-Import Bank of the Republic of China 4071
The Shanghai Commercial and Savings Bank 3101
Union Bank of Taiwan 3321
Yuanta Commercial Bank Co., Ltd. 3351

Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.

Оплаты через Payment Page

Общая информация

Для оплаты через Payment Page с использованием метода Banks of Taiwan со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате оплаты. При этом метод Banks of Taiwan можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжного метода).



Рис.: Проведение оплаты через Payment Page

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. Осуществляется генерация Payment Page согласно настройкам проекта и параметрам вызова.
  6. Пользователю отображается сгенерированная платёжная форма.
  7. Пользователь выбирает платёжный метод Banks of Taiwan.
  8. Запрос на проведение оплаты с использованием сервиса провайдера поступает в платёжную платформу.
  9. Выполняются дальнейшая обработка запроса и его отправка в сервис провайдера.
  10. На стороне провайдера выполняется обработка запроса на оплату.
  11. От сервиса провайдера к платёжной платформе передаются данные для отображения платёжной инструкции пользователю.
  12. Данные для отображения платёжной инструкции пользователю передаются к Payment Page.
  13. Пользователю отображается платёжная инструкция.
  14. Пользователь выполняет необходимые действия для оплаты согласно инструкции и подтверждает совершение оплаты на стороне банка. По умолчанию пользователю отводится на это 30 минут, и это время можно сократить до 15 минут по согласованию с курирующим менеджером ECommPay. Если пользователь не подтверждает совершение оплаты в течение установленного времени, то обработка платежа на стороне провайдера может занимать существенно большее время (вплоть до нескольких рабочих дней).
  15. На стороне провайдера выполняется обработка платежа.
  16. От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
  17. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  18. От платёжной платформы к Payment Page направляется результат проведения оплаты.
  19. Результат оплаты отображается пользователю на Payment Page.

Информация о формате запросов и параметрах вызова Payment Page при работе с Banks of Taiwan, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API см. в разделе Описание Payment Page API.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода Banks of Taiwan необходимо учитывать следующее:

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции,
    • payment_id — идентификатор платежа, уникальный в рамках проекта,
    • payment_amount — сумма платежа в дробных единицах валюты,
    • payment_currency — код валюты платежа в формате ISO-4217 alpha-3,
    • customer_id — идентификатор пользователя уникальный в рамках проекта.
  2. Дополнительно рекомендуется указывать имя и фамилию пользователя в параметрах customer_first_name и customer_last_name. Если параметры отсутствуют в запросе, на Payment Page пользователю отображаются поля для ввода недостающих значений. Подробнее об уточнении параметров — в разделе Дополнение информации о платеже.
  3. Для предварительного выбора метода Banks of Taiwan необходимо указывать код платёжного метода в параметре force_payment_methodonline-taiwan-banks.
  4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
  5. После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.

Таким образом, корректный запрос на открытие платёжной формы с применением метода Banks of Taiwan должен содержать идентификаторы проекта и платежа, информацию о пользователе, а также код валюты, сумму платежа и подпись:

    { 
      payment_id: 'X03936', 
      payment_amount: 300000, 
      payment_currency: 'TWD',
      customer_first_name: 'Lin',
      customer_last_name: 'Chen',
      project_id: 12, 
      signature: "kUi2x9dKHAVNU0FYldJrxh4...qtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }

Формат оповещений

Для оповещений о результатах оплат с применением метода Banks of Taiwan используется стандартный формат, описание которого представлено в разделе Оповещения.

К особенностям метода Banks of Taiwan можно отнести то, что установленное время, отведённое пользователю для подтверждения оплаты, передаётся в параметре timeout объекта provider_extra_fields.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 1625успешно проведена оплата в размере 3 000,00 TWD.

Рис.: Пример данных в оповещении о проведении оплаты

{
   "provider_extra_fields":{
      "timeout":1800
   },
   "customer":{
      "id":"1"
   },
   "project_id":1625,
   "payment":{
      "id":"1234",
      "type":"purchase",
      "status":"success",
      "date":"2020-08-05T10:10:19+0000",
      "method":"Taiwan banks",
      "sum":{
         "amount":300000,
         "currency":"TWD"
      },
      "description":"test description"
   },
   "operation":{
      "id":80940000002001,
      "type":"sale",
      "status":"success",
      "date":"2020-08-05T10:10:19+0000",
      "created_date":"2020-08-05T08:47:04+0000",
      "request_id":"0adeebcf82d137232e95fbacb2b30243e0b...8ffd12d61-00080941",
      "sum_initial":{
         "amount":300000,
         "currency":"TWD"
      },
      "sum_converted":{
         "amount":300000,
         "currency":"TWD"
      },
      "code":"0",
      "message":"Success",
      "provider":{
         "id":3221,
         "payment_id":"29922",
         "auth_code":"",
         "date":"2020-08-05T08:59:33+0000"
      }
   },
   "signature":"dH68la7JM/o2pPA7NOm1xhhnBS7RcVLdlBC...iBq02I4OKpR6EbtQ=="
}

В следующем примере оплата была отклонена.

Рис.: Пример данных в оповещении об отказе в проведении оплаты

{
   "provider_extra_fields":{
      "timeout":1800
   },
   "customer":{
      "id":"2"
   },
   "project_id":1625,
   "payment":{
      "id":"123456",
      "type":"purchase",
      "status":"decline",
      "date":"2020-08-05T10:10:18+0000",
      "method":"Taiwan banks",
      "sum":{
         "amount":20000,
         "currency":"TWD"
      },
      "description":"test description"
   },
   "operation":{
      "id":80940000002002,
      "type":"sale",
      "status":"decline",
      "date":"2020-08-05T10:10:18+0000",
      "created_date":"2020-08-05T08:46:04+0000",
      "request_id":"0adeebcf82d137232e95fbacb2b30243e0b...8ffd12d61-00080942",
      "sum_initial":{
         "amount":20000,
         "currency":"TWD"
      },
      "sum_converted":{
         "amount":20000,
         "currency":"TWD"
      },
      "code":"20000",
      "message":"General decline",
      "provider":{
         "id":3221,
         "payment_id":"" 
        }
   },
   "signature":"dH68la7JM/o2pPA7NOm1xhhnBS7RcVLdlBC...iBq02I4OrpR6EbtQ=="
}

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

Оплаты через Gate

Общая информация

Для оплаты через Gate с использованием метода Banks of Taiwan со стороны веб-сервиса необходимо:

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay.
  2. Отобразить пользователю инструкцию для оплаты, предоставить ему возможность подтвердить платёж и, если пользователь подтвердит, отправить запрос на подтверждение платежа.
  3. Принять оповещение о результате оплаты.

Полная схема проведения оплаты представлена далее.



Рис.: Проведение оплаты через Gate

  1. Пользователь на стороне веб-сервиса инициирует оплату через сервис провайдера.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис провайдера.
  7. На стороне провайдера выполняется обработка запроса на оплату.
  8. От сервиса провайдера к платёжной платформе передаются данные для отображения инструкции пользователю.
  9. От платёжной платформы к веб-сервису направляется оповещение с данными для отображения платёжной инструкции пользователю.
  10. Пользователю отображается платёжная инструкция.
  11. Пользователь выполняет необходимые действия для оплаты согласно инструкции и подтверждает совершение оплаты на стороне банка. По умолчанию пользователю отводится на это 30 минут, и это время можно сократить до 15 минут по согласованию с курирующим менеджером ECommPay. Если пользователь не подтверждает совершение оплаты в течение установленного времени, то обработка платежа на стороне провайдера может занимать существенно большее время (вплоть до нескольких рабочих дней).
  12. На стороне сервиса провайдера выполняется обработка платежа.
  13. От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
  14. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  15. От веб-сервиса пользователю направляется результат оплаты.

Информация о формате запросов и параметрах инициации оплат методом Banks of Taiwan через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API см. в разделе Работа с API.

Формат запросов

При работе с запросами на оплаты с применением метода Banks of Taiwan необходимо учитывать следующее:

  1. Должен использоваться запрос /v2/payment/banks/taiwan/sale, отправляемый методом POST. Этот запрос относится к группе запросов /v2/payment/banks/{payment_method}/sale.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции,
      • payment_id — идентификатор платежа, уникальный в рамках проекта,
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в дробных единицах валюты,
      • currency — код валюты платежа в формате ISO-4217 alpha-3;
    • customer — объект, содержащий сведения о пользователе:
      • id— идентификатор, уникальный в рамках проекта,
      • ip_address — используемый IP-адрес,
      • first_name — имя,
      • last_name — фамилия.
  3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода Banks of Taiwan должен содержать идентификаторы проекта и платежа, подпись, информацию о пользователе, код валюты и сумму платежа:

Рис.: Пример запроса на оплату

{
    "general": {
      "project_id": 200,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWo...=="
    },
    "payment": {
      "amount": 300000,
      "currency": "TWD"
      },
    "customer": {
      "id": "customer123",
      "ip_address": "248.14.67.234",
      "first_name": "Lin",
      "last_name": "Chen"
    }
}

Форматы данных для отображения платёжной инструкции и запросов на подтверждение платежа

Для отображения платёжной инструкции необходимо принять и обработать оповещение от платёжной платформы, содержащее данные о платеже в массиве display_data, и отобразить пользователю платёжную инструкцию, а также предоставить пользователю возможность подтвердить платёж на стороне веб-сервиса. При подтверждении платежа пользователем со стороны веб-сервиса необходимо отправить POST-запрос на подтверждение платежа к конечной точке /v2/payment/customer/confirm.

Помимо текста инструкции рекомендуется отобразить пользователю счётчик времени, отведённого на подтверждение оплаты на стороне банка. Если пользователь подтвердит платёж в течение установленного времени, то платёж обрабатывается на стороне провайдера автоматически. Если пользователь не подтверждает платёж, или подтверждает платёж после истечения установленного времени, то обработка платежа на стороне провайдера может занимать существенно большее время (вплоть до нескольких рабочих дней).

Далее приведён текст инструкции для отображения пользователю:

Табл. 2. Инструкция
Текст инструкции на китайском языке (упрощённое письмо) Текст инструкции на английском языке
以下為我司提供的收款人賬戶信息, 請用網銀轉入“正確”的收款人賬戶 Below are the Payee Details. Please transfer the exact amount to the following account with your own online bank
1) 請用網銀轉入我司所提供的收款人信息 1) Please transfer the "exact" amount to the following account with your own online bank
2) 轉賬時, 請勿在銀行附言框內填入任何信息 2) Please Never enter any words under Remark field during transfer
3) 轉賬完成後, 請保留匯款圖片 3) Please keep the Transfer Screenshot after the transfer is complete
4) 完成轉賬後, 請按下確認鍵 4) Please click CONFIRMATION button once you complete the transfer

Массив display_data содержит объекты со следующими параметрами:

  • type — тип объекта (в значении всегда передаётся add_info);
  • title — название параметра, который необходимо отобразить пользователю;
  • data — значение параметра, указанного в параметре title.

Параметр title определяет тип содержимого параметра data и может принимать одно из следующих значений:

  • Payee_BankName — при передаче в параметре data трёхзначного кода тайваньского банка;
  • Payee_BankAccount — при передаче в параметре data номера банковского счёта;
  • RequestedAmt — при передаче в параметре data суммы платежа в минорных единицах валюты.

Далее приведён фрагмент оповещения, содержащего данные для отображения пользователю.

"display_data": [
            {
                "type": "add_info",
                "title": "Payee_BankName",
                "data": "808"
            },
            {
                "type": "add_info",
                "title": "Payee_BankAccount",
                "data": "1322968025289"
            },
            {
                "type": "add_info",
                "title": "RequestedAmt",
                "data": "300000"
            }
        ]

Запрос на подтверждение платежа отправляется методом POST к конечной точке /v2/payment/customer/confirm и должен содержать следующие объекты и параметры:

  • general — объект, содержащий основные идентификационные сведения платежа:
    • project_id — идентификатор проекта, к которому относится проводимый платёж;
    • payment_id — идентификатор проводимого платежа;
    • signature — подпись, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).

Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, а также подпись:

{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  }
}

Формат оповещений

Для оповещений о результатах оплат с применением метода Banks of Taiwan используется стандартный формат, описание которого представлено в разделе Оповещения.

К особенностям метода Banks of Taiwan можно отнести то, что установленное время, отведённое пользователю для подтверждения оплаты, передаётся в параметре timeout объекта provider_extra_fields.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 1625успешно проведена оплата в размере 3 000,00 TWD.

Рис.: Пример данных в оповещении о проведении оплаты

{
   "provider_extra_fields":{
      "timeout":1800
   },
   "customer":{
      "id":"1"
   },
   "project_id":1625,
   "payment":{
      "id":"1234",
      "type":"purchase",
      "status":"success",
      "date":"2020-08-05T10:10:19+0000",
      "method":"Taiwan banks",
      "sum":{
         "amount":300000,
         "currency":"TWD"
      },
      "description":"test description"
   },
   "operation":{
      "id":80940000002001,
      "type":"sale",
      "status":"success",
      "date":"2020-08-05T10:10:19+0000",
      "created_date":"2020-08-05T08:47:04+0000",
      "request_id":"0adeebcf82d137232e95fbacb2b30243e0b...8ffd12d61-00080941",
      "sum_initial":{
         "amount":300000,
         "currency":"TWD"
      },
      "sum_converted":{
         "amount":300000,
         "currency":"TWD"
      },
      "code":"0",
      "message":"Success",
      "provider":{
         "id":3221,
         "payment_id":"29922",
         "auth_code":"",
         "date":"2020-08-05T08:59:33+0000"
      }
   },
   "signature":"dH68la7JM/o2pPA7NOm1xhhnBS7RcVLdlBC...iBq02I4OKpR6EbtQ=="
}

В следующем примере оплата была отклонена.

Рис.: Пример данных в оповещении об отказе в проведении оплаты

{
   "provider_extra_fields":{
      "timeout":1800
   },
   "customer":{
      "id":"2"
   },
   "project_id":1625,
   "payment":{
      "id":"123456",
      "type":"purchase",
      "status":"decline",
      "date":"2020-08-05T10:10:18+0000",
      "method":"Taiwan banks",
      "sum":{
         "amount":20000,
         "currency":"TWD"
      },
      "description":"test description"
   },
   "operation":{
      "id":80940000002002,
      "type":"sale",
      "status":"decline",
      "date":"2020-08-05T10:10:18+0000",
      "created_date":"2020-08-05T08:46:04+0000",
      "request_id":"0adeebcf82d137232e95fbacb2b30243e0b...8ffd12d61-00080942",
      "sum_initial":{
         "amount":20000,
         "currency":"TWD"
      },
      "sum_converted":{
         "amount":20000,
         "currency":"TWD"
      },
      "code":"20000",
      "message":"General decline",
      "provider":{
         "id":3221,
         "payment_id":"" 
        }
   },
   "signature":"dH68la7JM/o2pPA7NOm1xhhnBS7RcVLdlBC...iBq02I4OrpR6EbtQ=="
}

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

Выплаты через Gate

Общая информация

Для выплаты через Gate с использованием метода Banks of Taiwan со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате выплаты. Полная схема проведения выплаты представлена далее.



Рис.: Проведение выплаты через Gate

  1. Пользователь на стороне веб-сервиса инициирует выплату через Banks of Taiwan.
  2. От веб-сервиса на заданный URL ECommPay передаётся запрос на проведение выплаты через Gate.
  3. Запрос на проведение выплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис Banks of Taiwan.
  7. На стороне Banks of Taiwan выполняется обработка платежа.
  8. От Banks of Taiwan к платёжной платформе направляется оповещение о результате.
  9. От платёжной платформы к веб-сервису направляется оповещение о результате.
  10. От веб-сервиса пользователю направляется результат выплаты.

Информация о формате запросов и параметрах инициации выплат методом Banks of Taiwan через Gate, а также о формате оповещений о результатах выплат приведена далее, общая информация о работе с API см. в разделе Работа с API.

Формат запросов

При работе с запросами на выплаты с применением метода Banks of Taiwan необходимо учитывать следующее:

  1. Должен использоваться запрос /v2/payment/banks/taiwan/payout, отправляемый методом POST. Этот запрос относится к группе запросов для проведения платежей в одном из поддерживаемых банков /v2/payment/banks/{payment_method}/payout.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор,
      • ip_address — IP-адрес;
    • account — объект, содержащий сведения о банковском счёте пользователя:
      • number — номер счёта,
      • bank_id — идентификатор банка;
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в дробных единицах валюты,
      • currency — валюта платежа в формате ISO-4217 alpha-3.
  3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на выплату с применением метода Banks of Taiwan должен содержать идентификаторы проекта, проекта и платежа, подпись, номер счёта (для зачисления средств) и IP-адрес пользователя, а также валюту и сумму платежа:

Рис.: Пример запроса на выплату

{
    "general": {
        "project_id": 200,
        "payment_id": payment_id,
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVLhNN5e7aRfB...=="
    },
    "payment": {
      "amount": 300000,
      "currency": "TWD"
      },
    "customer": {
      "id":"100",
      "ip_address": "248.1.1.1"
    },
    "account":{
      "bank_id": 3131,
      "number": "12345"
    }
}

Формат оповещений

Для оповещений о результатах выплат с применением метода Banks of Taiwan используется стандартный формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 1625успешно проведена выплата в размере 190,00 TWD.

Рис.: Пример данных из оповещения о проведении выплаты

{
   "project_id":1625,
   "payment":{
      "id":"TEST_payout123460",
      "type":"payout",
      "status":"success",
      "date":"2020-08-07T08:38:40+0000",
      "method":"Taiwan banks",
      "sum":{
         "amount":300000,
         "currency":"TWD"
      },
      "description":""
   },
   "account":{
      "number":"123"
   },
   "customer":{
      "id":"123456"
   },
   "operation":{
      "id":80814000002361,
      "type":"payout",
      "status":"success",
      "date":"2020-08-07T08:38:40+0000",
      "created_date":"2020-08-07T08:26:53+0000",
      "request_id":"f6a2942f9ec83f1ce440ae38478bab2...852c23eac3dd4e-00080815",
      "sum_initial":{
         "amount":300000,
         "currency":"TWD"
      },
      "sum_converted":{
         "amount":300000,
         "currency":"TWD"
      },
      "code":"0",
      "message":"Success",
      "provider":{
         "id":3221,
         "payment_id":"",
         "auth_code":""
      }
   },
   "signature":"JJZv9rzrzCHm9GGcyYutg7EHdv+vwcYRG1bljafkehG...yNjgWUssrDHwgt0NvA=="
}

В следующем примере выплата была отклонена.

Рис.: Пример данных из оповещения об отказе в проведении выплаты

{
   "project_id":1625,
   "payment":{
      "id":"TEST_payout123461",
      "type":"payout",
      "status":"decline",
      "date":"2020-08-07T08:38:41+0000",
      "method":"Taiwan banks",
      "sum":{
         "amount":19000,
         "currency":"TWD"
      },
      "description":""
   },
   "account":{
      "number":"123"
   },
   "customer":{
      "id":"123456"
   },
   "operation":{
      "id":80814000002362,
      "type":"payout",
      "status":"decline",
      "date":"2020-08-07T08:38:41+0000",
      "created_date":"2020-08-07T08:27:53+0000",
      "request_id":"f6a2942f9ec83f1ce440ae38478bab2...852c23eac3dd4e-00080816",
      "sum_initial":{
         "amount":19000,
         "currency":"TWD"
      },
      "sum_converted":{
         "amount":19000,
         "currency":"TWD"
      },
      "code":"20000",
      "message":"General decline",
      "provider":{
         "id":3221,
         "payment_id":"",
         "auth_code":""
      }
   },
   "signature":"JJZv9rzrzCHm9GGcyYutg7EHdv+vwcYRG1bljafkehG...yNjgWUssrDGwgt0NvA=="
}

Дополнительные материалы

Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:

Выплаты через Dashboard (Old Dashboard)

Для проведения выплат через Dashboard (Old Dashboard) со стороны мерчанта необходимо инициировать запросы на выплаты и принять уведомления об их успешной обработке. Инициировать такие выплаты можно двумя способами:
  • как единичную выплату — в этом случае для каждой выплаты необходимо указать доступные для данного метода валюту и сумму, выбрать метод и заполнить все поля, отображаемые в интерфейсе с учётом выбранного метода;
  • в рамках массового платежа — в этом случае все параметры выплат необходимо задать в файле формата CSV с учётом требований, представленных в разделе Выплаты через Gate (кроме пункта о подписи).

Информация о проведении выплат отображается в разделах Платежи и Мануальные платежи интерфейса Dashboard (Old Dashboard).

Более подробная информация о проведении выплат через Dashboard (Old Dashboard) представлена в разделе Проведение выплат.

Анализ результатов проведения платежей

Как и при работе с другими платёжными методами, которые предоставляет ECommPay, при использовании метода Banks of Taiwan доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей на вкладке Analytics.

Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:

  • Dashboard (Old Dashboard) позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
  • Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ECommPay.