Banks of Hong Kong

Введение

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

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

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

Схема работы

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

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

Для проведения платежей и выполнения операций с использованием метода Banks of Hong Kong могут применяться различные интерфейсы платёжной платформы. Так выплаты могут проводиться через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие ограничения.

При работе с методом Banks of Hong Kong, независимо от используемых интерфейсов, актуальны следующие ограничения.

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

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

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

Вместе с тем, к особенностям работы с методом Banks of Hong Kong можно отнести то, что для каждого платежа с использованием этого метода должен быть указан конкретный банк. При работе через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Способы работы с идентификаторами банков описаны в следующем подразделе, Поддержка со стороны банков.

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

В следующей таблице в ознакомительных целях приведены названия и идентификаторы некоторых банков, поддерживающих работу с методом Banks of Hong Kong. Более подробный список представлен по ссылке: Список поддерживаемых банков. Данную информацию следует уточнять у курирующего менеджера ecommpay.

С вопросами о работе с банками, поддерживающими метод Banks of Hong Kong, можно обращаться к курирующему менеджеру ecommpay.

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

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

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

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

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

1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/hk/payout. Эта точка относится к группе /v2/payment/banks/{payment_method}/payout.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма выплаты в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемой выплаты;,
   • account — сведения о счёте пользователя:
     • bank_id — идентификатор банка,
     • number — номер счёта,
     • customer_name — имя получателя.
3. Валютой платежа может быть только HKD или CNY.
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
    "general": {
      "project_id": 383000,
      "payment_id": "12278b5d662764c9506b4db9df8c5c35",
      "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w=="
    },
    "customer": {
      "id": "fr-2374245",
      "ip_address": "192.0.2.0"
    },
    "payment": {
      "amount": 10000,
      "currency": "HKD"
  },
    "account": {
      "bank_id": 22791,
      "number": "1234567890",
      "customer_name": "John Doe"
  }
}

{
    "general": {
      "project_id": 383000,
      "payment_id": "12278b5d662764c9506b4db9df8c5c35",
      "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w=="
    },
    "customer": {
      "id": "fr-2374245",
      "ip_address": "192.0.2.0"
    },
    "payment": {
      "amount": 10000,
      "currency": "HKD"
  },
    "account": {
      "bank_id": 22791,
      "number": "1234567890",
      "customer_name": "John Doe"
  }
}

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

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

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

{
        "project_id": 789,
        "payment": {
            "id": "ABC1234321",
            "type": "payout",
            "status": "success",
            "date": "2021-04-26T08:41:59+0000",
            "method": "hk",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "account": {
            "number": "1234567"
        },
        "customer": {
            "id": "customer3"
        },
        "operation": {
            "id": 4348000010681,
            "type": "payout",
            "status": "success",
            "date": "2021-04-26T08:41:59+0000",
            "created_date": "2021-04-26T08:41:54+0000",
            "request_id": "3d7ef0727decad0829d608cabd0f8a6d96fbd3a...006256",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 5181,
                "payment_id": "aff0b...cf9f2cd",
                "auth_code": "",
                "date": "2021-04-26T08:41:55+0000"
            }
        },
        "signature": "1L2fmnHY/51dZPI1j/IVa9LqzEPR67j9pPghn...c545R1xsGzw0zQ=="
    }
}

В следующем примере оповещение свидетельствует об отклонённой выплате.

{
        "project_id": 0123,
        "payment": {
            "id": "ABC1234567",
            "type": "payout",
            "status": "decline",
            "date": "2021-04-26T08:41:59+0000",
            "method": "hk",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "account": {
            "number": "123456789"
        },
        "customer": {
            "id": "customer1234"
        },
        "operation": {
            "id": 4348000010681,
            "type": "payout",
            "status": "decline",
            "date": "2021-04-26T08:41:59+0000",
            "created_date": "2021-04-26T08:41:54+0000",
            "request_id": "a19b65b2463fa7377f518d49674275cbaa4397a7...004349",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 5181,
                "payment_id": "aff0b...cf9f2cd",
                "auth_code": "",
                "date": "2021-04-26T08:41:55+0000"
            }
        },
        "signature": "eQxj9hXHVWFBDMcko2Tj0071CvnFPsp...A9CchCgVr/Hqbu6w=="
    }
}

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

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

• Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Выплаты — о том, как проводить выплаты через Gate.
• Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.