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

Обзор

Введение

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

В этой статье представлена информация о работе с методом «Выплаты на банковские счета в разных странах»: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.

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

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



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

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

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

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

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

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

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



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

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

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



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

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

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

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

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

  1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/bank-transfer/world/payout. Эта точка относится к группе /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. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

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

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

 {
  "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 также могут быть полезны следующие материалы:

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

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

  • инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
  • отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
  • данные в формате JSON, получаемые по программным запросам через интерфейс Data API.

С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.