«Выплаты на банковские счета в других странах»

Обзор

«Выплаты на банковские счета в других странах» — платёжный метод позволяющий осуществлять выплаты пользователям с помощью банковских переводов. Выплаты осуществляются через 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

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

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

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

При работе с запросами на выплаты с применением метода «Выплаты на банковские счета в других странах» необходимо учитывать следующее:

  1. Должен использоваться запрос к конечной точке /v2/payment/bank-transfer/world/payout, отправляемый методом POST. Этот запрос относится к группе запросов на выплату с помощью банковского перевода: /v2/payment/bank-transfer/{payment_method}/payout.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты,
      • currency — валюта платежа в формате ISO-4217 alpha-3,
    • customer — объект, содержащий сведения о получателе:
      • id — идентификатор получателя в веб-сервисе,
      • ip_address — IP-адрес.
  3. В запросах с указанием валют 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.

  4. Рекомендуется указывать ряд дополнительных параметров. Если такие параметры отсутствуют в запросе, к веб-сервису отправляется оповещение на уточнение. Формат оповещения соответствует спецификации 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 — для Великобритании, SWIFT — для остальных стран, для которых поддерживается этот метод;
      • routing_number — идентификатор банка в системе межбанковских переводов;
  5. Также, в зависимости от специфики конкретного платежа и особенностей работы разных банков, для проведения платежа могут понадобиться другие параметры. В этом случае отправляется дополнительное оповещение на уточнение информации о платеже. К таким параметрам относятся:
    • payment — объект, содержащий сведения о платеже:
      • local_conversion_currency — код валюты страны получателя в формате ISO-4217 alpha-3;
    • sender — данные отправителя:
      • beneficiary_relationship — юридические отношения получателя и отправителя (например employee, buyer и т.п.);
    • customer — объект, содержащий сведения о получателе:
      • city — город получателя;
      • email — адрес электронной почты;
      • phone — номер телефона, указывается с кодом страны, без знаков пунктуации и специальных символов (например, 79031234567);
      • state — штат или регион;
      • zip — почтовый индекс;
      • identify — объект, содержащий сведения о документе, подтверждающем личность:
        • doc_type — тип документа, подтверждающего личность, например Passport, Company Organization Code, Company Social Credit Code и т.п.;
        • doc_number — номер документа, подтверждающего личность;
    • account — объект, содержащий сведения о счете получателя:
      • type — тип банковского счёта получателя (например Checking для указания расчётного счёта, Saving для сберегательного счёта, и т.п.);
      • bank_name — название банка получателя;
      • bank_code — код банка получателя (состоит из трёх цифр, может запрашиваться если в параметре payment.currency указан код валюты HKD или CAD).
  6. Валютой платежа может быть только одна из поддерживаемых.
  7. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на выплату с применением метода «Выплаты на банковские счета в других странах» должен содержать идентификаторы проекта и платежа, подпись, валюту и сумму платежа, информацию о получателе и его счёте, а также дополнительные параметры (если потребуются):

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

 {
  "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.