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

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

Схема работы

В проведении отдельного платежа с использованием «Выплаты на банковские счета в других странах» задействуются веб-сервис мерчанта и платёжная платформа ecommpay, а также технические средства провайдера, обеспечивающие взаимодействие с сервисами банков.

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

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

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

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

Проведение выплат с использованием метода «Выплаты на банковские счета в других странах» выполняется с уведомлением пользователей через веб-сервис мерчанта.

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

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

Для выплаты через Gate с использованием метода «Выплаты на банковские счета в других странах» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате выплаты. Полная схема проведения выплаты представлена далее.

Информация о формате запросов и параметрах инициализации выплат методом «Выплаты на банковские счета в других странах» через 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 — для Великобритании, TRANSIT NUMBER — для Канады, BRANCH CODE — для Бразилии, SWIFT — для остальных стран, для которых поддерживается этот метод;
     • routing_number — идентификатор банка в системе межбанковских переводов;
5. Также, в зависимости от специфики конкретного платежа и особенностей работы разных банков, для проведения платежа могут понадобиться другие параметры. В этом случае отправляется дополнительное оповещение на уточнение информации о платеже. К таким параметрам относятся:
   • payment — объект, содержащий сведения о платеже:
     • local_conversion_currency — код валюты страны получателя в формате ISO-4217 alpha-3 (может запрашиваться, если в параметре customer.country указан код страны CA или US; вместе с тем, в определённых случаях отсутствие этого параметра в исходном запросе может вести к отклонению платежа; с вопросами о работе с этим параметром можно обращаться в службу технической поддержки ecommpay);
   • 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 указан код валюты BRL, HKD или CAD; список доступных кодов банков следует уточнять у курирующего менеджера ecommpay).
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.