Hong Kong Virtual Account

Обзор

Введение

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

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

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

Тип платёжного метода банковские платежи
Платёжные инструменты банковские счета
Регионы использования HK
Валюты платежей HKD, CNY
Конвертация валют
Разовые оплаты +
Повторяемые оплаты
Полные возвраты
Частичные возвраты
Выплаты
Опротестования
Особенности при оплате пользователь может указывать сумму, отличную от суммы в запросе; информация о реагировании на такие случаи представлена далее
Организация и стоимость подключения по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommshop

Схема работы

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



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

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

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

Суммы, HKD
минимум максимум
Оплаты 4 000 000,00

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

Проведение оплат с использованием метода Hong Kong Virtual Account осуществляется с отображением платёжной инструкции пользователю.

Пользовательский сценарий оплаты через Payment Page (в базовом варианте с выбором пользователем метода и банка и перенаправлением с итоговой страницы платёжной формы к веб-сервису) выглядит следующим образом.

Общие сценарии проведения оплат можно представить следующим образом.

Обработка некорректных платёжных данных

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

Предположим, что для инициирования платежа был использован следующий запрос через Gate с указанием суммы 300,00 HKD:

Рис.: Пример данных из запроса

{
    "general": {
      "project_id": 1234567,
      "payment_id": "abc12345",
      "signature": "123abc...pkdme12"
    },
    "customer": {
      "id": "123"
      "ip_address": "192.0.2.0"
    },
    "payment": {
      "amount": 30000,
      "currency": "HKD"
  }
}

Если пользователь указал при оплате сумму 250,00 HKD и платёж был успешно обработан на стороне провайдера и платёжной платформы, то от платформы к веб-сервису отправляется оповещение следующего вида с фактической суммой, указанной пользователем. При этом на стороне мерчанта необходимо иметь возможность обработать такое оповещение, несмотря на отличие фактической суммы платежа от исходной суммы в запросе.

Рис.: Пример данных из оповещения

{
        "project_id": 3514,
        "payment": {
            "id": "EP0c8a-960e",
            "type": "purchase",
            "status": "success",
            "date": "2021-02-10T10:10:14+0000",
            "method": "hk-va",
            "sum": {
                "amount": 25000,
                "currency": "HKD"
            },
            "description": ""
        },
        "operation": {
            "id": 360,
            "type": "sale",
            "status": "success",
            "date": "2021-02-10T10:10:14+0000",
            "created_date": "2021-02-10T10:09:34+0000",
            "request_id": "cca222750e99b05bc6656ec...000001",
            "sum_initial": {
                "amount": 25000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 25000,
                "currency": "HKD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 5171,
                "payment_id": "16129...9796",
                "auth_code": "",
                "date": "2021-02-10T10:09:57+0000"
            }
        },
        "signature": "9sHwkk4fbhwQg3PH/8ShWtbqgBZEcfaC+HnVrQe6DFFCQX14w=="
    }

Оплаты через Payment Page

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

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



Рис.: Проведение оплаты через Payment Page

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выбирает для оплаты метод Hong Kong Virtual Account.
  8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Hong Kong Virtual Account.
  9. В платёжной платформе обеспечиваются обработка полученного запроса.
  10. Данные для отображения платёжной инструкции пользователю передаются к Payment Page.
  11. Пользователю отображается платёжная инструкция.
  12. Пользователь выполняет необходимые действия для оплаты согласно инструкции.
  13. В сервисе провайдера выполняется обработка платежа.
  14. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты.
  15. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  16. От платёжной платформы к Payment Page направляется информация о результате оплаты.
  17. Информация о результате оплаты отображается пользователю на Payment Page.

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

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

При формировании запросов на открытие платёжной формы с применением метода Hong Kong Virtual Account необходимо учитывать следующее:

  1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
    • payment_amount — сумма платежа в дробных единицах валюты;
    • customer_id — идентификатор пользователя в рамках проекта.
  2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
  3. Валютой платежа может быть только HKD или CNY.
  4. Для предварительного выбора метода Hong Kong Virtual Account необходимо указывать код этого метода в параметре force_payment_methodhk-va.
  5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
  6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "HKD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "HKD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

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

{
        "project_id": 123,
        "payment": {
            "id": "12345678",
            "type": "purchase",
            "status": "success",
            "date": "2021-04-26T08:40:29+0000",
            "method": "hk-va",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 6301000010721,
            "type": "sale",
            "status": "success",
            "date": "2021-04-26T08:40:29+0000",
            "created_date": "2021-04-26T08:39:53+0000",
            "request_id": "faac1f505a3e188fb384d7eabc735335b32af288...006302",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 5171,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "tqmkAb32XGHYglWq3Nm7XD7Yq21fV21dcGBMPb7/ddzuts...qoumh8dQw=="
    }
}

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

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

{
        "project_id": 0123,
        "payment": {
            "id": "123456789",
            "type": "purchase",
            "status": "decline",
            "date": "2021-04-26T08:40:29+0000",
            "method": "hk-va",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1234"
        },
        "operation": {
            "id": 5205000010711,
            "type": "sale",
            "status": "decline",
            "date": "2021-04-26T08:40:29+0000",
            "created_date": "2021-04-26T08:39:53+0000",
            "request_id": "9b430e9f97d5fa903985e482242f6638...0005206",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 5171,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "+a9OY3rEEhMlPpR54LJoQa...2HfVTKJO5LeUmFUDtfA=="
    }
}

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

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

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

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

Для проведения оплаты через Gate с использованием метода Hong Kong Virtual Account со стороны веб-сервиса необходимо:

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
  2. Принять промежуточное оповещение от платёжной платформы и отобразить платёжную инструкцию пользователю.
  3. Принять итоговое оповещение от платёжной платформы.

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



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

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

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

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

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

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

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "HKD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  }
}

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "HKD"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  }
}

Формат промежуточных оповещений для отображения платёжной инструкции

Для отображения пользователям платёжной инструкции при проведении каждого платежа с использованием метода Hong Kong Virtual Account необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в массив display_data. Формат таких оповещений является типовым (подробнее), при этом в состав массива display_data включаются следующие параметры:

  • type — тип передаваемых данных (в значении всегда передаётся add_info);
  • title — название передаваемых данных, которые необходимо отобразить пользователю (в значении всегда передаётся virtual_account_number);
  • data — номер созданного виртуального банковского счёта.

Рис.: Пример массива display_data

"display_data": [
            {
                "type": "add_info",
                "title": "virtual_account_number",
                "data": "1213323442...523521424"
            }
]

Помимо текста инструкции рекомендуется отобразить пользователю информация о времени, отведённом на выполнение необходимых для проведения оплаты действий. Если пользователь не подтверждает платёж до истечения указанного срока, выдаётся сообщение об ошибке.

Далее приведён текст инструкции для отображения пользователю:

Текст инструкции на китайском языке (традиционное письмо) Текст инструкции на английском языке
付款詳情 Payment Details
銀行名稱: DBS Bank (Hong Kong) Limited Bank Name: DBS Bank (Hong Kong) Limited
帳戶持有人姓名:DOLLARSMART GLOBAL PTE. LTD. LTD. Account Holder name: DOLLARSMART GLOBAL PTE. LTD.
銀行帳號:{{va_number}} Bank Account number: {{va_number}}
轉帳金額: {{amount}} Transfer amount: {{amount}}
貨幣:HKD Currency: HKD
失效日期 Expiration date
如何支付 How to pay
1) 打開您的銀行應用程序,並從您的帳戶開始新的轉帳。 1) Open your banking app and start a new transfer from your account.
2) 選擇“DBS BANK(HONG KONG)LIMITED”作為收款銀行。 2) Select "DBS BANK (HONG KONG) LIMITED" as a payee bank.
3) 輸入帳戶持有人姓名:“DOLLARSMART GLOBAL PTE. LTD.” 3) Enter account holder’s name: "DOLLARSMART GLOBAL PTE. LTD."
4) 輸入銀行帳號。 4) Enter the bank account number.
5) 如有需要,請選擇HKD貨幣和付款日期。 5) Select HKD currency and payment date if necessary.
6) 輸入要支付的金額。 6) Enter the amount to be paid.
7)選擇“CONFIRM”以繼續轉帳。 7) Select "CONFIRM" to proceed with the transfer.
確認後,付款處理時間少於1分鐘。 Payment processing takes less than 1 minute after confirmation.

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

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

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

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

{
        "project_id": 456,
        "payment": {
            "id": "12345678",
            "type": "purchase",
            "status": "success",
            "date": "2021-04-26T08:40:29+0000",
            "method": "hk-va",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 6301000010721,
            "type": "sale",
            "status": "success",
            "date": "2021-04-26T08:40:29+0000",
            "created_date": "2021-04-26T08:39:53+0000",
            "request_id": "faac1f505a3e188fb384d7eabc735335b32af288...006302",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 5171,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "tqmkAb32XGHYglWq3Nm7XD7Yq21fV21dcGBMPb7/ddzuts...qoumh8dQw=="
    }
}

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

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

{
        "project_id": 0123,
        "payment": {
            "id": "123456789",
            "type": "purchase",
            "status": "decline",
            "date": "2021-04-26T08:40:29+0000",
            "method": "hk-va",
            "sum": {
                "amount": 10000,
                "currency": "HKD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer1234"
        },
        "operation": {
            "id": 5205000010711,
            "type": "sale",
            "status": "decline",
            "date": "2021-04-26T08:40:29+0000",
            "created_date": "2021-04-26T08:39:53+0000",
            "request_id": "9b430e9f97d5fa903985e482242f6638...0005206",
            "sum_initial": {
                "amount": 10000,
                "currency": "HKD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "HKD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 5171,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "+a9OY3rEEhMlPpR54LJoQa...2HfVTKJO5LeUmFUDtfA=="
    }
}

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

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

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

Для анализа информации о платежах и операциях, как в отдельности по методу Hong Kong Virtual Account, так и в совокупности с другими методами, можно использовать:

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

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