Выплаты на банковские счета в других странах
Обзор
«Выплаты на банковские счета в других странах» — платёжный метод позволяющий осуществлять выплаты пользователям с помощью банковских переводов. Выплаты осуществляются через Gate.
Характеристика
Тип платёжного метода | банковские платежи |
---|---|
Платёжные инструменты | банковские счета |
Регионы использования | AR, AU, BR, CA, CN, CO, CL, Европа (страны ЕЗПЕ), GB, HK, KR, IN, ID, LK, MX, MY, NP, PE, PH, SG, TH, TR, US, UY, VN |
Валюты платежей | AUD, ARS, BRL, CAD, CLP, CNY, COP, EUR, GBP, HKD, INR, IDR, KRW, LKR, MYR, MXN, NPR, PEN, PHP, SGD, THB, TRY, USD, UYU, VND |
Конвертация валют | – |
Оплаты | – |
Выплаты | + |
Оплаты по сохранённым данным | – |
Полные возвраты | – |
Частичные возвраты | – |
Опротестования | – |
Особенности | в каждой стране поддерживается использование только её национальной валюты |
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием «Выплаты на банковские счета в других странах» задействуются веб-сервис мерчанта и платёжная платформа ecommpay, а также технические средства провайдера, обеспечивающие взаимодействие с сервисами банков.
Основные операции
Интерфейсы | Суммы | Время* | ||||||
---|---|---|---|---|---|---|---|---|
Payment Page | CMS Plug-ins | Gate | Dashboard | Минимум | Максимум | Базовое | Предельное | |
Выплаты | – | – | + | – | – | – | – | 30 дней |
* Базовое и предельное время определяются следующим образом:
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.
Сценарии использования
Проведение выплат с использованием метода «Выплаты на банковские счета в других странах» выполняется с уведомлением пользователей через веб-сервис мерчанта.
Рис.: Выплата через Gate
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.
Выплаты через Gate
Общая информация
Для выплаты через Gate с использованием метода «Выплаты на банковские счета в других странах» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате выплаты. Полная схема проведения выплаты представлена далее.
Рис.: Проведение выплаты через Gate
- Пользователь запрашивает выплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение выплаты через Gate.
- Запрос на проведение выплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис провайдера.
- На стороне провайдера выполняется обработка платежа.
- От провайдера к платёжной платформе направляется оповещение о результате.
- От платёжной платформы к веб-сервису направляется оповещение о результате.
- От веб-сервиса пользователю направляется результат выплаты.
Информация о формате запросов и параметрах инициализации выплат методом «Выплаты на банковские счета в других странах» через Gate, а также о формате оповещений о результатах выплат приведена далее, общая информация о работе с API см. в разделе Работа с API.
Формат запросов
При работе с запросами на выплаты с применением метода «Выплаты на банковские счета в других странах» необходимо учитывать следующее:
- Должен использоваться запрос к конечной точке
/v2/payment/bank-transfer/world/payout
, отправляемый методом POST. Этот запрос относится к группе запросов на выплату с помощью банковского перевода: /v2/payment/bank-transfer/{payment_method}/payout. - В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- payment — объект, содержащий сведения о платеже:
- amount — сумма платежа в дробных единицах валюты,
- currency — валюта платежа в формате ISO-4217 alpha-3,
- customer — объект, содержащий сведения о получателе:
- id — идентификатор получателя в веб-сервисе,
- ip_address — IP-адрес.
- general — объект, содержащий основные идентификационные сведения запроса:
-
В запросах с указанием валют EUR и GBP при работе с некоторыми провайдерами может требоваться передавать код страны получателя в формате ISO 3166-1 alpha-2 в значении двух параметров:
payment.extra_param
иcustomer.country
. Это актуально для получателей из следующих стран: AR, AU, BR, CA, CN, CO, CL, GB, HK, KR, IN, ID, LK, MX, MY, NP, PE, PH, SG, TH, TR, US, UY, VN.Необходимость такого указания кода страны следует уточнять у курирующего менеджера ecommpay.
- Рекомендуется указывать ряд дополнительных параметров. Если такие параметры отсутствуют в запросе, к веб-сервису отправляется оповещение на уточнение. Формат оповещения соответствует спецификации JSON-Schema. Подробнее об уточнении параметров — в разделе Дополнение информации о платеже.
Рекомендуется использовать следующие объекты и параметры:
- customer — объект, содержащий сведения о получателе:
- address — адрес получателя;
- country — код страны в формате ISO 3166-1 alpha-2;
- person_type — тип счёта получателя (допустимые значения:
individual
для счетов физических лиц,company
для счетов юридических лиц); - first_name — имя получателя (допустимо указывать без фамилии) или название юридического лица;
- account — объект, содержащий сведения о счете получателя:
- number — номер счёта;
- routing_type — тип системы межбанковских переводов, допустимые значения:
ACH CODE
— для США,BANK CODE
— для Гонконга,BSB CODE
— для Австралии,IFSC
— для Индии,SORT CODE
— для Великобритании,TRANSIT NUMBER
— для Канады,BRANCH CODE
— для Бразилии,SWIFT
— для остальных стран, для которых поддерживается этот метод; - routing_number — идентификатор банка в системе межбанковских переводов;
- customer — объект, содержащий сведения о получателе:
- Также, в зависимости от специфики конкретного платежа и особенностей работы разных банков, для проведения платежа могут понадобиться другие параметры. В этом случае отправляется дополнительное оповещение на уточнение информации о платеже. К таким параметрам относятся:
- payment — объект, содержащий сведения о платеже:
- local_conversion_currency — код валюты страны получателя в формате ISO-4217 alpha-3 (может запрашиваться, если в параметре customer.country указан код страны
CA
илиUS
; вместе с тем, в определённых случаях отсутствие этого параметра в исходном запросе может вести к отклонению платежа; с вопросами о работе с этим параметром можно обращаться в службу технической поддержки ecommpay);
- local_conversion_currency — код валюты страны получателя в формате ISO-4217 alpha-3 (может запрашиваться, если в параметре customer.country указан код страны
- sender — данные отправителя:
- beneficiary_relationship — юридические отношения получателя и отправителя (например
employee
,buyer
и т.п.);
- beneficiary_relationship — юридические отношения получателя и отправителя (например
- customer — объект, содержащий сведения о получателе:
- city — город получателя;
- email — адрес электронной почты;
- phone — номер телефона, указывается с кодом страны, без знаков пунктуации и специальных символов (например,
79031234567
); - state — штат или регион;
- zip — почтовый индекс;
- identify — объект, содержащий сведения о документе, подтверждающем личность:
- doc_type — тип документа, подтверждающего личность, например
Passport
,Company Organization Code
,Company Social Credit Code
и т.п.; - doc_number — номер документа, подтверждающего личность;
- doc_type — тип документа, подтверждающего личность, например
- account — объект, содержащий сведения о счете получателя:
- type — тип банковского счёта получателя (например
Checking
для указания расчётного счёта,Saving
для сберегательного счёта, и т.п.); - bank_name — название банка получателя;
- bank_code — код банка получателя (состоит из трёх цифр, может запрашиваться если в параметре payment.currency указан код валюты
BRL
,HKD
илиCAD
; список доступных кодов банков следует уточнять у курирующего менеджера ecommpay).
- type — тип банковского счёта получателя (например
- payment — объект, содержащий сведения о платеже:
- Валютой платежа может быть только одна из поддерживаемых.
- Дополнительно могут использоваться все параметры, указанные в спецификации.
Таким образом, корректный запрос на выплату с применением метода «Выплаты на банковские счета в других странах» должен содержать идентификаторы проекта и платежа, подпись, валюту и сумму платежа, информацию о получателе и его счёте, а также дополнительные параметры (если потребуются):
Рис.: Пример запроса на выплату
{ "general": { "project_id": 3027, "payment_id": "payout1", "signature": "M1vT4q9c8hA8xCjEwGFSANI+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q==" }, "payment": { "amount": 1000, "currency": "EUR" "local_conversion_currency": "EUR", "extra_param": "US" }, "sender": { "beneficiary_relationship": "Employee" }, "customer": { "id": "customer1", "ip_address": "1.2.3.4", "address": "12 Spring Rd", "country": "US", "person_type": "individual", "first_name": "John", "city": "Los Angeles", "email": "customer@example.com", "phone": "145600198754", "state": "California", "zip": "12345", "identify": { "doc_type": "Passport", "doc_number": "1234" } }, "account": { "number": "1020304010", "routing_type": "SWIFT", "routing_number": "ADCBINBB" "type": "Saving", "bank_name": "Example Bank", "bank_code": "123" } }
Формат оповещений
Для оповещений о результатах выплат с применением метода «Выплаты на банковские счета в других странах» используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 1774
была успешно проведена выплата в размере 1,00 EUR
.
Рис.: Пример оповещения о проведении выплаты
{ "customer": { "id": "1" }, "account": { "number": "LV81HABA06" }, "project_id": 22351, "payment": { "id": "TEST_2_17022022", "type": "payout", "status": "success", "date": "2022-02-17T13:45:34+0000", "method": "world", "sum": { "amount": 100, "currency": "EUR" }, "description": "" }, "operation": { "id": 55969010087671, "type": "payout", "status": "success", "date": "2022-02-17T13:45:34+0000", "created_date": "2022-02-17T13:45:06+0000", "request_id": "0d9e9a0199baccc886a320da858e93919ce-00055970", "sum_initial": { "amount": 100, "currency": "EUR" }, "sum_converted": { "amount": 100, "currency": "EUR" }, "code": "0", "message": "Success", "provider": { "id": 2421, "payment_id": "PY23297248", "auth_code": "", "date": "2022-02-17T13:45:26+0000" } }, "signature": "dRj303+vVN+HghppyhEAK0c658yzVALLB4v192P6Bb8vhmA==" }
В следующем примере выплата была отклонена из-за недостатка средств на счёте мерчанта.
Рис.: Пример оповещения об отказе в проведении выплаты
{ "project_id": 1774, "payment": { "id": "1234567891", "type": "payout", "status": "decline", "date": "2020-04-06T11:34:51+0000", "method": "world", "sum": { "amount": 100, "currency": "EUR" }, "description": "Order 67" }, "account": { "number": "123" }, "customer": { "id": "31234" }, "operation": { "id": 538, "type": "payout", "status": "decline", "date": "2020-04-06T11:33:51+0000", "created_date": "2020-04-06T11:33:44+0000", "request_id": "ea8cf9c100f6ce886540493cfc99be653d03e76e0500b8-00000002", "sum_initial": { "amount": 100, "currency": "EUR" }, "sum_converted": { "amount": 100, "currency": "EUR" }, "code": "3028", "message": "Insufficient funds on merchant balance", "provider": { "id": 1971, "payment_id": "15861728285", "auth_code": "", "date": "2020-04-06T11:33:50+0000" } }, "signature": "Q8xo7IGQBS+HSqBLSwLMgV8FO0qrHsDnlbUqOdN8fa3frn9tgg==" }
Дополнительные материалы
Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:
Анализ результатов проведения платежей
Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода «Выплаты на банковские счета в других странах» доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.
Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей на вкладке Analytics.
Также можно выгружать нужную информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков:
- Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
- Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.
С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ecommpay.