Banks of Thailand

Обзор

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

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

Тип платёжного метода Интернет-банкинг
Регионы использования Тайланд
Валюты платежей THB
Конвертация валют на стороне ECommPay; для подключения необходимо обратиться к курирующему менеджеру ECommPay
Оплаты +
Выплаты +
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности
  • Для работы с этим методом через Payment Page поддерживается каскадное проведение оплат. Информацию о поддержке этой возможности можно получить в разделе Каскадное проведение платежей и у курирующего менеджера ECommPay
  • Метод Banks of Thailand входит в группу методов интернет-банкинга в Юго-Восточной Азии, для которых можно задавать дополнительные параметры при вызове Payment Page
  • Доступны два способа выбора банка: на стороне Payment Page или на стороне провайдера. Подключаемый способ необходимо уточнять у курирующего менеджера ECommPay
  • В браузере Safari может не поддерживаться перенаправление на сервис банка. Подробности необходимо уточнять у курирующего менеджераECommPay
Организация и стоимость подключения По согласованию с курирующим менеджером ECommPay
Прим.:

Для работы с методом Banks of Thailand в настоящее время поддерживаются две технических реализации: новая, описанная в данном разделе, и старая, описанная в разделе Banks of Thailand (legacy).

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

Схема работы

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



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

Интерфейсы Суммы, THB Время **
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) Минимум Максимум Базовое Предельное
Оплаты + + * * * *
Выплаты + * * * *

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

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

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

Проведение оплат с использованием метода Banks of Thailand выполняется с перенаправлением пользователей на сайты банков, поддерживающих работу с этим методом, проведение выплат — с уведомлением пользователей средствами веб-сервиса.

Рис.: Оплата через Payment Page с выбором банка на стороне Payment Page



Рис.: Оплата через Payment Page с выбором банка на стороне провайдера



Рис.: Оплата через Gate с перенаправлением на сайт банка



Рис.: Оплата через Gate с выбором банка на стороне провайдера



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



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

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

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

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

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

{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 10000,
    "currency": "THB"
  }
}
Табл. 1. Список банков
Банк ID Оплаты Выплаты
AIG Retail Bank PCL 6551 +
ANZ Bank (Thai) PCL 6561 +
Bangkok Bank 124 + +
Bank For Agriculture And Agricultural Cooperatives 5851 +
Bank of America N.A. 6481 +
Bank Of Ayudhya 127 + +
Bank of China (Thai) Public Company 6531 +
Bank of Tokyo-Mitsubishi 6441 +
Bharat Overseas Bank Ltd 6491 +
BNP Paribas, Bangkok 6521 +
CIMB Thailand 483 +
Citibank 5921 +
Deutsche Bank AG 5871 +
Export-Import Bank of Thailand 6521 +
Finansa Credit Ltd 6601 +
Government Housing Bank 4701 +
Government Savings Bank 128 + +
Hongkong and Shanghai Corporation Ltd 6501 +
Industrial and Commercial Bank of China (Thai) 3911 +
Islamic Bank of Thailand 5841 +
JPMorgan Chase Bank, Bangkok Branch 6421 +
KasiKorn Bank 123 + +
Kiatnakin Bank (KNK) 710 + +
Krung Thai Bank 126 + +
Krungsri (Bank of Ayudhya Public Company Limited) 394 + +
KTB Net Bank 164 + +
Land and Houses Bank 5911 +
Mega International Commercial Bank 6471 +
Mizuho Corporate Bank 5891 +
Oversea-Chinese Banking Corporation Ltd. 6431 +
Promptpay Bank 6581 +
RHB Bank Berhad 6461 +
Siam Commercial Bank 125 + +
Small and Medium Enterprise 6571 +
Srisawad Finance Public Company Limited 6591 +
Standard Chartered Bank 4711 +
Sumitomo Mitsui Banking Corporation 5901 +
Sumitomo Mitsui Banking Corporation 5901 +
Thai Investment and Securities Company Bank 5931 +
Thai Military Bank 6451 +
Thai Payment Network Company Limited 6611 +
Thanachart Bank PCL 6541 +
Thanachat Bank 745 +
The Royal Bank of Scotland PCL, Bkk Br 6411 +
TMB Bank Public Company Limited 129 + +
United Overseas 484 +
UOBT 395 + +

Регионы проведения выплат

При проведении выплаты с использованием метода Banks of Thailand в зависимости от провайдера, обрабатывающего платёж, может учитываться регион банковского счёта пользователя (более подробную информацию следует уточнять у курирующего менеджера ECommPay). Для этого используется идентификатор региона, который передаётся в параметре region_id в запросе на выплату. Далее в таблице приведена информация о регионах и их идентификаторах.

Табл. 2. Список регионов
Наименование региона Идентификатор региона
Amnat Charoen 59
Ang Thong 60
Bueng Kan 61
Buri Ram 62
Chachoengsao 63
Chai Nat 64
Chaiyaphum 65
Chanthaburi 66
Chiang Mai 67
Chiang Rai 68
Chon Buri 69
Chumphon 70
Kalasin 71
Kamphaeng Phet 72
Kanchanaburi 73
Khon Kaen 74
Krabi 75
Krung Thep Maha Nakhon 76
Lampang 77
Lamphun 78
Loei 79
Lop Buri 80
Mae Hong Son 81
Maha Sarakham 82
Mukdahan 83
Nakhon Nayok 84
Nakhon Pathom 85
Nakhon Phanom 86
Nakhon Ratchasima 87
Nakhon Sawan 88
Nakhon Si Thammarat 89
Nan 90
Narathiwat 91
Nong Bua Lam Phu 92
Nong Khai 93
Nonthaburi 94
Pathum Thani 95
Pattani 96
Phangnga 97
Phatthalung 98
Phatthaya 99
Phayao 100
Phetchabun 101
Phetchaburi 102
Phichit 103
Phitsanulok 104
Phra Nakhon Si Ayutthaya 105
Phrae 106
Phuket 107
Prachin Buri 108
Prachuap Khiri Khan 109
Ranong 110
Ratchaburi 111
Rayong 112
Roi Et 113
Sa Kaeo 114
Sakon Nakhon 115
Samut Prakan 116
Samut Sakhon 117
Samut Songkhram 118
Saraburi 119
Satun 120
Si Sa Ket 121
Sing Buri 122
Songkhla 123
Sukhothai 124
Suphan Buri 125
Surat Thani 126
Surin 127
Tak 128
Trang 129
Trat 130
Ubon Ratchathani 131
Udon Thani 132
Uthai Thani 133
Uttaradit 134
Yala 135
Yasothon 136

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

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

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

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

Рис.: Схема проведения оплаты с выбором банка на Payment Page



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

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

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



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

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

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

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

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

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции,
    • payment_id — идентификатор платежа, уникальный в рамках проекта,
    • payment_amount — сумма платежа в минорных единицах валюты,
    • payment_currency — валюта платежа в формате ISO-4217 alpha-3.
  2. Обязательно указываются параметры с данными пользователя:
    • customer_id — идентификатор уникальный в рамках проекта,
    • customer_first_name — имя,
    • customer_last_name — фамилия,
    • customer_email — адрес электронной почты пользователя.
  3. По умолчанию Payment Page открывается на английском языке. Для изменения языка Payment Page и платёжной страницы сервиса Banks of Thailand необходимо передавать код языка в параметре language_code. Далее приведен список поддерживаемых языков с их кодами, но точный список языков рекомендуется уточнять у курирующего менеджера ECommPay.
    • en — английский,
    • id — индонезийский,
    • ms — малайский,
    • my — бирманский,
    • th — тайский,
    • vi — вьетнамский,
    • zh — китайский.
  4. Можно настраивать отображение страницы Payment Page с выбором метода оплаты.

    По умолчанию банки, поддерживающие проведение оплат методом Banks of Thailand, объединены в группу и отображаются одной кнопкой Banks of Thailand, поэтому выбор банка осуществляется в два этапа.

    Оплата через Payment Page с выбором банка на стороне сервиса провайдера

    При использовании платёжного метода Banks of Thailand с выбором банка на стороне сервиса провайдера сначала выбирается метод Banks of Thailand на Payment Page, а затем выполняется выбор конкретного банка на стороне сервиса провайдера. В данном случае можно настраивать отображение Payment Page с предварительно выбранным платёжным методом Banks of Thailand. Для этого необходимо передать код online-thailand-banks в параметре force_payment_method.

    Оплата через Payment Page с выбором банка на стороне Payment Page

    При использовании платёжного метода Banks of Thailand с выбором банка на стороне Payment Page сначала выбирается метод Banks of Thailand среди прочих, а затем на следующей странице с перечнем банков выбирается конкретный банк. Существует несколько вариантов отображения страницы Payment Page с выбором метода оплаты:

    • Отображение каждого банка группы отдельной кнопкой. Для этого необходимо передавать параметр split_banks со значением true в строке payment_methods_options.
      payment_methods_options: {"online_thailand_banks": {"split_banks": true}}
      
    • Отображение кнопок конкретных банков (одного или нескольких). В списке методов может присутствовать метод Banks of Thailand. Для этого необходимо передавать идентификаторы банков в параметре banks_id. Для отображения нескольких банков необходимо перечислять идентификаторы этих банков через запятую c пробелом.
      payment_methods_options: {"online_thailand_banks": {"split_banks": true, "banks_id": [125, 126]}}
    • Отображение только банков группы без других методов. Для этого используется предварительный выбор метода Banks of Thailand. Необходимо передавать код платежного метода online-thailand-banks в параметре force_payment_method. Пользователю открывается страница с выбором банков, минуя страницу с выбором метода оплаты.
    • Отображение сайта конкретного банка. Для этого используется предварительный выбор метода Banks of Thailand. Необходимо передавать код платежного метода online-thailand-banks в параметре force_payment_method и идентификатор банка banks_id в параметре payment_methods_options. Перенаправление пользователя на сайта банка осуществляется без подтверждения готовности оплатить, минуя страницы с выбором метода оплаты и с выбором банков.

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

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

      EPayWidget.run(
          { payment_id: 'X03936', 
            payment_amount: 200000, 
            payment_currency: 'THB', 
            project_id: 0,
            customer_id: '1',
            customer_first_name: 'John',
            customer_last_name: 'Johnson',
            customer_email: 'Johnson@mail.com',
            force_payment_method: 'online-thailand-banks',
            payment_methods_options: {"online_thailand_banks": {"banks_id": [125]}},
            signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
          }
      )
    Совет: Для включения и настройки функциональности свяжитесь со службой технической поддержки support@ecommpay.com.
  5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры открытия платежной формы Payment Page.
  6. После определения всех параметров необходимо составить подпись. Подробнее — в разделе Работа с подписью к данным.

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

EPayWidget.run(
    { payment_id: 'X03936', 
      payment_amount: 200000, 
      payment_currency: 'THB', 
      project_id: 0,
      customer_id: '1',
      customer_first_name: 'John',
      customer_last_name: 'Johnson',
      customer_email: 'Johnson@mail.com',
      signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }
)

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 от пользователя 1 была успешно проведена оплата в размере 100,00 THB.

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

 {
        "project_id": 200,
        "payment": {
            "id": "TEST_154382328570677",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-03T09:24:18+0000",
            "method": "Thailand banks",
            "sum": {
                "amount": 10000,
                "currency": "THB"
            },
            "description": "TEST_1543823285707"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 9327000002098,
            "type": "sale",
            "status": "success",
            "date": "2018-12-03T09:24:18+0000",
            "created_date": "2018-12-03T09:24:14+0000",
            "request_id": "18fb8bdc3f5",
            "sum_initial": {
                "amount": 10000,
                "currency": "THB"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "THB"
            },
            "provider": {
                "id": 1152,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "LU36QCTjH9FTX3euQRQjhgfghjLC5Zbz3xbV7XARw9trZ2gAKiA=="
    }
}

В следующем примере оплата была отклонена из-за нарушения ограничения на сумму.

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

{
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_1544769530751556",
            "type": "purchase",
            "status": "decline",
            "date": "2018-12-14T07:16:32+0000",
            "method": "Thailand banks",
            "sum": {
                "amount": 100,
                "currency": "THB"
            },
            "description": "ECT_TEST_1544769530751"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 7175000002255,
            "type": "sale",
            "status": "decline",
            "date": "2018-12-14T07:16:32+0000",
            "created_date": "2018-12-14T07:16:30+0000",
            "request_id": "a6baeae100a15878206fcb7883af26e71013e2de-e5d071f07676316e96ff0b294c3e0a952a8f96b9",
            "sum_initial": {
                "amount": 100,
                "currency": "THB"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "THB"
            },
            "provider": {
                "id": 1152,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "cQbMiD0pON9eJc5ZugNK0iT5SwH8wQubo0+7RCZWuxc0feItZRcABrPdFA4EKQiyWj7NWQRmVyHzNTmOX6Zg5w=="
    }

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

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

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

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

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

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

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

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



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

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

  10. Пользователь перенаправляется на сайт банка.
  11. Пользователь выполняет необходимые действия для оплаты на сайте банка.
  12. На стороне сервиса банка выполняется обработка платежа.
  13. Пользователю отображается результат оплаты на сайте банка.
  14. Пользователь перенаправляется к веб-сервису.
  15. От сервиса банка к платёжной платформе направляется уведомление о результате оплаты.
  16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  17. От веб-сервиса пользователю направляется результат оплаты.

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



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

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

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

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

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

  1. Должен использоваться запрос /v2/payment/banks/thailand/sale , отправляемый методом POST. Этот запрос относится к группе запросов /v2/payment/banks/{payment_method}/sale.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции,
      • payment_id — идентификатор платежа, уникальный в рамках проекта,
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • customer — объект, содержащий сведения о пользователе:
      • ip_address — используемый IP-адрес,
      • id — идентификатор,
      • first_name — имя,
      • last_name — фамилия,
      • email — адрес электронной почты;
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты,
      • currency — валюта платежа в формате ISO-4217 alpha-3;
    • account — объект, содержащий сведения о банковском счёте пользователя:
      • bank_id — идентификатор банка. Данный параметр не является обязательным при использовании способа выбора банка на стороне сервиса провайдера;
    • return_url — объект, содержащий URL для перенаправления пользователя после оплаты:
      • success — URL для перенаправления пользователя после проведенной оплаты,
      • decline — URL для перенаправления пользователя после отклоненной оплаты.
  3. По умолчанию платёжная страница сервиса Banks of Thailand открывается на английском языке. Для изменения языка платёжной страницы необходимо передать параметр customer.language со значением кода языка. Далее приведен список поддерживаемых языков с их кодами, но точный список языков рекомендуется уточнять у курирующего менеджера ECommPay.
    • en — английский,
    • id — индонезийский,
    • ms — малайский,
    • my — бирманский,
    • th — тайский,
    • vi — вьетнамский,
    • zh — китайский.
  4. В зависимости от провайдера, обрабатывающего платёж, для проведения оплаты могут потребоваться другие обязательные параметры, например, имя, фамилия и адрес электронной почты пользователя. В таком случае список параметров отправляется в оповещении на уточнение параметров. Подробнее см. в разделе Дополнение информации о платеже.
  5. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

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

{
    "general": {
        "project_id": 2990,
        "payment_id": payment_id,
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 20000000,
      "currency": "THB"
      },
    "customer": {
      "id":"2990",
      "ip_address": "248.121.176",
      "first_name": "Kon",
      "last_name": "Do",
      "email": "do@mail.com",
    },
    "account":{
      "bank_id": 124 
    },
    "return_url":{
      "decline" : "http://return.url",
      "success" : "http://return.url"
    }
}

Форматы данных для перенаправления пользователей

Для перенаправления пользователя от веб-сервиса на сайт банка необходимо принять оповещение от платёжной платформы, содержащее ссылку для перенаправления в параметре redirect_data.url и данные для отправки в теле запроса redirect_data.body, и использовать эти параметры при открытии HTML-страницы банка методом, указанным в redirect_data.method.

Рис.: Фрагмент оповещения, содержащего токен на оплату


"redirect_data": {
            "method": "POST",
            "body": {
                "token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJwYXiIwLjEifQ.xAQWCKO-
                          cZ7yRT_n0MjQ3MjY3NSwiaWgwMDk1LCJqdGkiOha2Rt4Cm5IRvoP1oP
                          N2mNOzVWp7LcHgDXa64ah4DtQsMRzrVFTwkiOha2Rt4Cm5IF0IjoxNTQ"
            },
            "encrypted": [],
            "url": "https://payment.allpay.site/api/transfer/v1/payIn/sendTokenForm"
    }

Рис.: Фрагмент оповещения, содержащий URL для перенаправления на страницу выбора банка


 "redirect_data": {
                    "body": {
                        "amount": "100.00",
                        "currency": "THB"
                    },
                    "method": "POST",
                    "url": "https://secure.example.asia/"
                }
            }

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 от пользователя 1 была успешно проведена оплата в размере 100,00 THB.

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

 {
        "project_id": 200,
        "payment": {
            "id": "TEST_154382328570677",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-03T09:24:18+0000",
            "method": "Thailand banks",
            "sum": {
                "amount": 10000,
                "currency": "THB"
            },
            "description": "TEST_1543823285707"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 9327000002098,
            "type": "sale",
            "status": "success",
            "date": "2018-12-03T09:24:18+0000",
            "created_date": "2018-12-03T09:24:14+0000",
            "request_id": "18fb8bdc3f5",
            "sum_initial": {
                "amount": 10000,
                "currency": "THB"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "THB"
            },
            "provider": {
                "id": 1152,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "LU36QCTjH9FTX3euQRQjhgfghjLC5Zbz3xbV7XARw9trZ2gAKiA=="
    }
}

В следующем примере оплата была отклонена из-за нарушения ограничения на сумму.

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

{
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_1544769530751556",
            "type": "purchase",
            "status": "decline",
            "date": "2018-12-14T07:16:32+0000",
            "method": "Thailand banks",
            "sum": {
                "amount": 100,
                "currency": "THB"
            },
            "description": "ECT_TEST_1544769530751"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 7175000002255,
            "type": "sale",
            "status": "decline",
            "date": "2018-12-14T07:16:32+0000",
            "created_date": "2018-12-14T07:16:30+0000",
            "request_id": "a6baeae100a15878206fcb7883af26e71013e2de-e5d071f07676316e96ff0b294c3e0a952a8f96b9",
            "sum_initial": {
                "amount": 100,
                "currency": "THB"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "THB"
            },
            "provider": {
                "id": 1152,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "cQbMiD0pON9eJc5ZugNK0iT5SwH8wQubo0+7RCZWuxc0feItZRcABrPdFA4EKQiyWj7NWQRmVyHzNTmOX6Zg5w=="
    }

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

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

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

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

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



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

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

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

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

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

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

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

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

{
    "general": {
        "project_id": 2990,
        "payment_id": payment_id,
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVLhNNSaRfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 10000,
      "currency": "THB"
      },
    "customer": {
      "id":"2990",
      "ip_address": "248.121.176"
    },
  "account":{
      "bank_id": 124,      
      "customer_name": "Putra account",
      "number": "314159265358979",
      "region_id": 20978,
      "branch":"Bank branch",
      "city": "Huanin"
    }
}

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

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

В данном случае оповещение свидетельствует о том, что в рамках проекта 200 для пользователя 1 была успешно проведена выплата в размере 2 000,00 THB на счёт № 6419422222.

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

 {
        "project_id": 200,
        "payment": {
            "id": "TESTPAYOUT7891022555",
            "type": "payout",
            "status": "success",
            "date": "2018-12-12T13:28:58+0000",
            "method": "Thailand banks",
            "sum": {
                "amount": 200000,
                "currency": "THB"
            },
            "description": "test payout"
        },
        "account": {
            "number": "6419422222",
            "bank_id":124,
            "region_id": 236
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 15112000002236,
            "type": "payout",
            "status": "success",
            "date": "2018-12-12T13:28:58+0000",
            "created_date": "2018-12-12T13:22:15+0000",
            "request_id": "b54610e94a76",
            "sum_initial": {
                "amount": 20000,
                "currency": "THB"
            },
            "sum_converted": {
                "amount": 200000,
                "currency": "THB"
            },
            "provider": {
                "id": 1152,
                "payment_id": "E80NPPQ6Z1YSYPZTPH0NBON42",
                "date": "2018-12-12T13:28:34+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "qV2FRs/wxoOaywQS0GYQDi+6spZFbiRXxt8zG10zy9TNiJLT0P/+EOrpMkoW80mynkaQfSAUJpfQ=="
    }

В этом примере выплата была отклонена из-за превышения максимального лимита суммы выплаты.

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

{
        "project_id": 200,
        "payment": {
            "id": "TESTPAYOUT789",
            "type": "payout",
            "status": "decline",
            "date": "2018-12-07T09:44:43+0000",
            "method": "Thailand banks",
            "sum": {
                "amount": 60000000,
                "currency": "THB"
            },
            "description": ""
        },
        "account": {
            "number": "6419422222",
            "bank_id":140,
            "region_id": 236
        },
        "customer": {
            "id": "1"
        },
        "errors": [
            {
                "code": "3104",
                "message": "Payment Constraint Invalid Payout Amount",
                "description": "Gate. Operation was declined. Maximum payout limit is exceeded"
            }
        ],
        "operation": {
            "id": 533000002202,
            "type": "payout",
            "status": "decline",
            "date": "2018-12-07T09:44:43+0000",
            "created_date": "2018-12-07T09:44:43+0000",
            "request_id": "205d3536a91f4737d679ae44f5c707eaace0b009-7b37cb0b1b4d62a602dd42fa7d248258224fe3f6",
            "sum_initial": {
                "amount": 60000000,
                "currency": "THB"
            },
            "sum_converted": {
                "amount": 60000000,
                "currency": "THB"
            },
            "provider": {
                "id": 1152,
                "payment_id": ""
            },
            "code": "3104",
            "message": "Payment Constraint Invalid Payout Amount"
        },
        "signature": "j4cxKDvx0EaDe4zKLbLcb8isoHFxBB/eV5hPzvsN+iFpGJELstSJw0bHot6v83rzDMlinxE915lAWGHKVjurpQ=="
    }

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

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

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

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

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

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

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

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