Одностадийный интернет-платеж (ECOM H2H)
| Название | Код | Описание |
|---|---|---|
Тип интеграции |
|
Платеж через API HighHelp на стороне мерчанта |
Валюта |
Поддерживаемые валюты: |
|
Депозиты |
✅ |
Доступные методы для оплаты: |
Выплаты |
✅ |
Доступные методы для выплаты: |
Оплата
Схема оплаты
Для проведения инетрнет-платежа в одну стадию клиент передает реквизиты карты в явном виде. Другие способы передачи реквезитов будут доступны позже.
Необходимость прохождения аутентификации 3-D Secure зависит от эмитента карты. Решение о проведении аутентификации принимается эмитентом. Со стороны мерчанта выбрать предпочтительный метод аутентификации невозможно.
3-D Secure может выполняться в одном из следующих сценариев:
-
аутентификация без участия клиента (frictionless flow): эмитенту достаточно данных, переданных мерчантом при создании платежа; поэтому важно передавать всю доступную информацию о клиенте (ФИО, информация о браузере и т.п.);
-
аутентификация с действиями клиента (challenge flow): клиент проходит дополнительную проверку (код подтверждения, биометрия и т.п.), способ аутентификации определяет эмитент.
Процесс оплаты
-
Создание заявки.
Мерчант создает заявку на оплату и передает все необходимые данные для проведения платежа. -
Получение данных для отображения в платежной инструкции.
Если эмитент требует 3-D Secure, мерчант получает оповещение со статусомprocessing:awaiting_3ds_resultилиprocessing:awaiting_redirect_result. В теле оповещения содержатся данные для перенаправления клиента. Подробнее см. раздел Перенаправление клиента. Если дополнительная аутентификация не требуется, происходит финализация платежа (пункт 6). -
Перенаправление клиента на страницу аутентификации.
Мерчант перенаправляет клиента на страницу эмитента для прохождения 3-D Secure. -
Подтверждение оплаты от эмитента.
В случае успешной аутентификации эмитент отправляет данные о результате. Эти данные необходимо передать в API HighHelp. -
Подтверждение оплаты от мерчанта.
В случае успешной аутентификации мерчант подтверждает платеж в API HighHelp. См. раздел Подтверждение 3DS аутентификации. -
Финализация платежа.
Средства списываются с карты клиента и зачисляются на счет мерчанта. Клиент перенаправляется на страницу мерчанта.
Создание заявки
POST https://api.hh-processing.com/api/v1/payment/ecom/payin
Параметры, которые необходимо отправить в теле запроса при создании платежа.
-
general— информация по заявке.-
project_id— идентификатор кассы (проекта), полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, уникальный в рамках кассы мерчанта. Можно использовать любые буквы, цифры и символы в кодировке UTF-8.
(string) (<= 255 символа) -
merchant_callback_url— динамический URL для получения оповещений информативного характера (изменения промежуточных статусов заявки и т.д.). Оповещения по финальным статусам приходят на URL, указанные вmerchant_success_callback_urlиmerchant_decline_callback_url.
(string<https-url>) (<= 2048 символа) -
merchant_success_callback_url— динамический URL для получения оповещения при успешном завершении операции.
(string<https-url>) (<= 2048 символа) -
merchant_decline_callback_url— динамический URL для получения оповещения, если операция не завершилась успешно.
(string<https-url>) (<= 2048 символа)
-
-
payment— информация по платежу.-
method— код метода оплаты. Список методов приведен в разделе Платежные методы.
(string) (<= 32 символа) -
amount— сумма платежа в дробных единицах валюты. Подробнее см. раздел Коды валют.
(integer) (1 <= X <= 10000000000000) -
currency— код валюты платежа в формате ISO-4217 alpha-3. Подробнее о кодах валют см. в разделе Коды валют.
(string) (regex: ^[A-Z]{3}$) -
description— описание платежа или комментарий. Отображается в личном кабинете мерчанта.
(string) (<= 255 символа) -
extra_param— дополнительный параметр для индивидуальной маршрутизации заявки. Настраивается совместно с администратором.
(string) (regex: ^[A-Za-z0-9_-]{1,16}$)
-
-
card— реквизиты карты клиента, с которой списываются средства.-
pan— номер карты клиента.
(string<pan>) (<= 32 символа) -
year— год окончания срока действия карты клиента.
(integer) (2020 <= X <= 2099) -
month— месяц окончания срока действия карты клиента.
(integer) (1 <= X <= 12) -
card_holder— имя держателя карты (как на карте).
(string) (<= 255 символа) (regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЁРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$) -
cvv— код проверки подлинности карты (CVV/CVC).
(string) (regex: ^\d{3,4}$)
-
-
customer— информация о клиенте.-
id— уникальный идентификатор клиента в проекте мерчанта.
(string) (<= 255 символа) -
ip_address— IP-адрес клиента.
(string<ip-address>) (<= 255 символа) -
country— код страны клиента в формате ISO 3166-1 alpha-2. Список поддерживаемых стран см. в разделе Коды стран.
(string) (regex: ^[A-Z]{2}$) -
first_name— имя клиента.
(string) (<= 255 символа) -
last_name— фамилия клиента.
(string) (<= 255 символа) -
language— код языка в формате ISO 639-1, на котором будет показана платежная страница. Если язык не указан, используется язык по умолчанию для страны. Список поддерживаемых языков см. в разделе Коды языков.
(string) (regex: ^[a-z]{2}$) -
email— адрес электронной почты клиента.
(string<email>) (<= 255 символа) -
browser— название и версия браузера клиента.
(string) (<= 512 символа) -
device_type— тип устройства клиента.
(string) (<= 512 символа) -
user_agent— идентификационная строка клиентского приложения.
(string) (<= 1024 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/ecom/payin \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
"general": {
"project_id": "8b03432e-385b-4670-8d06-064591096795",
"payment_id": "KZT-ECOM-123456",
"merchant_callback_url": "https://your-domain.com/internal",
"merchant_success_callback_url": "https://your-domain.com/sucess",
"merchant_decline_callback_url": "https://your-domain.com/decline"
},
"payment": {
"method": "card-ecom",
"amount": 150000,
"currency": "KZT",
"description": "Comment about the payment",
"extra_param": "example"
},
"card": {
"pan": "4242242442422424",
"year": 2029,
"month": 1,
"card_holder": "John Snow",
"cvv": "666"
},
"customer": {
"id": "random-customer-id",
"ip_address": "1.1.1.1",
"first_name": "John",
"last_name": "Snow",
"country": "RU",
"language": "ru",
"email": "[email protected]",
"browser": "Google Chrome v15.12",
"device_type": "Iphone 15 Pro",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "new",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456"
}
Перенаправление клиента
Если эмитент требует 3-D Secure, мерчант получает оповещение со статусом processing:awaiting_3ds_result или processing:awaiting_redirect_result. В теле оповещения содержатся данные для аутентификации. Пример такого оповещения приведен в разделе Информативные оповещения по оплате.
Оповещения доставляются с повторными попытками до успешной доставки или до истечения времени жизни заявки. Если оповещение не было получено и заявка остается в промежуточном статусе, можно запросить информацию о заявке через API. См. раздел Информация о заявке (оплата).
Аутентификация 3-D Secure
В оповещении со статусом processing:awaiting_3ds_result в поле asc_info передаются:
-
pa_req— зашифрованные данные с информацией о платеже для 3-D Secure. -
acs_url— URL страницы эмитента, на которую необходимо перенаправить клиента. -
md— данные о заявке мерчанта в платежной системе.
После получения данных мерчант формирует HTML-форму и перенаправляет клиента на страницу эмитента для прохождения аутентификации.
<!DOCTYPE html>
<html>
<head>
<title>3D Secure Authentication</title>
</head>
<body>
<form id="3dsform" action="{{acs_url}}" method="post" enctype="application/x-www-form-urlencoded">
<input type="hidden" name="PaReq" value="{{pa_req}}"/>
<input type="hidden" name="TermUrl" value="{{term_url}}"/>
<input type="hidden" name="MD" value="{{md}}"/>
</form>
<script type="text/javascript">
setTimeout(function () {
document.getElementById("3dsform").submit();
}, 1000);
</script>
</body>
</html>
-
{{acs_url}}— значение параметраacs_urlиз оповещения. -
{{pa_req}}— значение параметраpa_reqиз оповещения. -
{{term_url}}— ваш URL, на который эмитент отправляет результат аутентификации в форматеFormData. Пример:PaRes=ewogISsg2&MD=eyJwdXJ&Action=sendBy. После получения результата необходимо передать данные в API HighHelp. См. раздел Подтверждение 3DS аутентификации. -
MD— значение параметраmdиз оповещения.
Аутентификация путем перенаправления клиента
В оповещении со статусом processing:awaiting_redirect_result в поле redirect_info передаются:
-
method— HTTP-метод для запроса. -
url— URL, на который необходимо перенаправить клиента. -
body— данные для передачи на указанный URL (может быть пустым).
После получения оповещения мерчант перенаправляет клиента на указанный URL.
Информация о заявке
POST https://api.hh-processing.com/api/v1/payment/ecom/payin/info
Параметры, которые необходимо отправить в теле запроса для получения статуса ecom заявки на оплату.
-
general— информация по заявке.-
project_id— идентификатор кассы, полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа.
(string) (<= 255 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/ecom/payin/info \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
"general": {
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "awaiting_3ds_result",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456",
"payment_info": {
"amount": 150000,
"currency": "KZT",
"lifetime": 1800,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-ecom",
"type": "payin"
},
"card": {
"pan": "424224******2424",
"year": 2029,
"month": 1,
"card_holder": "John Snow"
},
"customer": {
"id": "random-customer-id"
},
// если статус заявки `processing:awaiting_3ds_result`
"asc_info": {
"acs_url": "https://acs-url.com/order/1234",
"pa_req": "123456789",
"md": "V2hhdCdzIHVwIGR1ZGU="
}
// если статус заявки `processing:awaiting_redirect_result`
"redirect_info": {
"method": "POST",
"url": "https://bank-domain.com/redirect/1234",
"body": {
"key1": "value1",
"key2": "value2"
}
}
}
Параметры ответа:
-
status— статус обработки оплаты. Список статусов приведен в разделе Статусы оплат.
(string) (<= 32 символа) -
sub_status— подстатус обработки платежа. Используется только для отдельных статусов. Список подстатусов приведен в разделе Статусы оплат.
(string) (<= 32 символа) -
status_description— дополнительная информация по статусу. Используется, если оплата не прошла или произошла ошибка.
(string) (<= 1024 символа) -
request_id— идентификатор платежа, который генерируется в системе HighHelp.
(string) (<= 32 символа) -
project_id— идентификатор кассы, полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, уникальный в рамках кассы мерчанта.
(string) (<= 255 символа) -
payment_info— информация об оплате.-
amount— сумма платежа в дробных единицах валюты. Подробнее см. раздел Коды валют.
(integer) (1 <= X <= 10000000000000) -
currency— код валюты в формате ISO-4217 alpha-3. Подробнее о кодах валют см. в разделе Коды валют.
(string) (regex: ^[A-Z]{3}$) -
lifetime— время жизни заявки в секундах.
(integer) (X <= 2^32) -
expiration_date— время, до которого заявка действительна, в формате Unix Timestamp (UTC).
(integer) (X <= 2^32) -
created_date— время создания заявки в формате Unix Timestamp (UTC).
(integer) (X <= 2^32) -
method— код метода оплаты. Список методов приведен в разделе "Платежные методы".
(string) (<= 32 символа) -
type— тип оплаты. Подробнее о типах см. в разделе Поддерживаемые типы платежей.
(string) (<= 32 символа)
-
-
card— информация о карте, с которой производится оплата.-
pan— номер карты отправителя (маскированный).
(string<pan>) (<= 32 символа) -
year— год окончания срока действия карты.
(integer) (2020 <= X <= 2099) -
month— месяц окончания срока действия карты.
(integer) (1 <= X <= 12) -
card_holder— имя держателя карты.
(string) (<= 255 символа) (regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЁРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$) -
cvv— код проверки подлинности карты отправителя.
(string) (<= 3 символа)
-
-
customer— информация об отправителе.-
id— уникальный идентификатор пользователя в проекте мерчанта.
(string) (<= 255 символа)
-
-
asc_info— информация для 3-D Secure.-
pa_req— зашифрованные данные о платеже для 3-D Secure.
(string) (<= 2048 символа) -
acs_url— URL-страницы эмитента для 3-D Secure.
(string<https-url>) (<= 4096 символа) -
md— данные мерчанта в платежной системе для 3-D Secure.
(string) (<= 4096 символа)
-
|
Поле |
Подтверждение 3DS-аутентификации
POST https://api.hh-processing.com/api/v1/payment/ecom/payin/confirm-3ds-result
Параметры, которые необходимо отправить в теле запроса для подтверждения списания средств у пользователя.
-
general— информация по заявке.-
project_id— идентификатор кассы, полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, для которого выполняется подтверждение.
(string) (<= 255 символа)
-
-
pares— информация о результате 3-D Secure.-
data— данные, полученные от эмитента после аутентификации.
(string) (<= 2^16 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/ecom/payin/confirm-3ds-result \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
"general": {
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456"
},
"pares": {
"data": "base64string"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "awaiting_3ds_result",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456"
}
Параметры ответа:
-
status— статус обработки оплаты. Список статусов приведен в разделе Статусы оплат.
(string) (<= 32 символа) -
sub_status— подстатус обработки платежа. Используется только для отдельных статусов. Список подстатусов приведен в разделе Статусы оплат.
(string) (<= 32 символа) -
status_description— дополнительная информация по статусу. Используется, если оплата не прошла или произошла ошибка.
(string) (<= 1024 символа) -
request_id— идентификатор платежа, который генерируется в системе HighHelp.
(string) (<= 32 символа) -
project_id— идентификатор кассы, полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, уникальный в рамках кассы мерчанта.
(string) (<= 255 символа)
Статусы оплат
Типы операций и статусов описаны в разделе Типы операций и статусы.
Коды статусов и возможные значения status и sub_status приведены в разделе Коды статусов.
| Статус | Подстатус | Описание | Состояние платежа |
|---|---|---|---|
|
Платеж не был выполнен из-за ошибки, возникшей при проверке запроса |
Промежуточное состояние |
|
|
|
Проверяется корректность запроса перед началом обработки |
Промежуточное состояние |
|
Подбор реквизитов, на которые клиенту необходимо перечислить сумму из запроса |
Промежуточное состояние |
|
|
Ожидается подтверждение оплаты от клиента, так как реквизиты уже предоставлены |
Промежуточное состояние |
|
|
Клиент подтвердил, что отправил сумму на выданные реквизиты |
Промежуточное состояние |
|
|
|
Клиент не выполнил оплату по заявке за время ее жизни ( |
Промежуточное состояние |
|
Клиент отправил сумму, отличающуюся от указанной в заявке |
Промежуточное состояние |
|
|
Время жизни заявки истекло, но клиент позднее подтвердил оплату и предоставил чек |
Промежуточное состояние |
|
|
Платеж отклонен |
Финальное состояние |
|
|
Платеж выполнен |
Финальное состояние |
Оповещения
|
Рекомендуется реализовать проверку входящих оповещений на дубликаты. Ключ идемпотентности можно формировать по шаблону |
|
Каждое оповещение подписывается цифровой подписью HighHelp. Текущий публичный ключ для проверки подписи можно получить в панели администратора. Ключ уникален для каждой кассы. Алгоритм проверки подписи идентичен алгоритму формирования подписи при вызове API. Примеры проверки подписи приведены в разделе Аутентификация и подпись. |
Предусмотрены три типа оповещений:
-
Информативные — оповещения по промежуточным статусам заявок. Оповещение отправляется при изменении статуса. URL задается в параметре
merchant_callback_urlпри создании заявки. -
Успешные — оповещения по заявкам, завершившимся в статусе
success. URL задается в параметреmerchant_success_callback_url. -
Неуспешные — оповещения по заявкам, завершившимся в статусе
declineили с ошибкой. URL задается в параметреmerchant_decline_callback_url.
Информативные оповещения
Пример оповещения со статусами processing:awaiting_3ds_result и processing:awaiting_redirect_result:
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "KZT-ECOM-123456"
},
"status": {
"status": "processing",
"sub_status": "awaiting_3ds_result",
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "KZT",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-ecom",
"type": "payin"
},
"card": {
"pan": "427212******1234",
"year": 2029,
"month": 1,
"card_holder": "John Snow"
},
// если статус заявки `processing:awaiting_3ds_result`
"asc_info": {
"pa_req": "123456789",
"acs_url": "https://acs-url.com/order/1234",
"md": "V2hhdCdzIHVwIGR1ZGU="
}
// если статус заявки `processing:awaiting_redirect_result`
"redirect_info": {
"method": "POST",
"url": "https://bank-domain.com/redirect/1234",
"body": {
"key1": "value1",
"key2": "value2"
}
}
}
|
Успешные оповещения
Оповещение отправляется при успешном финальном статусе success.
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "KZT-ECOM-123456"
},
"status": {
"status": "success",
"sub_status": null,
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "KZT",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-ecom",
"type": "payin"
},
"card": {
"pan": "427212***1234",
"year": 2029,
"month": 1,
"card_holder": "John Snow"
}
}
Неуспешные оповещения
Оповещение отправляется при неуспешном финальном статусе decline.
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "KZT-ECOM-123456"
},
"status": {
"status": "decline",
"sub_status": null,
"status_description": "Declined by anti-fraud"
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "KZT",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-ecom",
"type": "payin"
},
"card": {
"pan": "427212***1234",
"year": 2029,
"month": 1,
"card_holder": "John Snow"
}
}
Выплата
Создание заявки на выплату
POST https://api.hh-processing.com/api/v1/payment/ecom/payout
Параметры, которые необходимо отправить в теле запроса при создании выплаты на карту.
-
general— информация по заявке.-
project_id— идентификатор кассы, полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, уникальный в рамках кассы мерчанта. Можно использовать любые буквы, цифры и символы в кодировке UTF-8.
(string) (<= 255 символа) -
merchant_callback_url— динамический URL для получения оповещений информативного характера (изменения промежуточных статусов заявки и т.д.). Оповещения по финальным статусам заявок отправляются на URL, указанные вmerchant_success_callback_urlиmerchant_decline_callback_url.
(string<https-url>) (<= 2048 символа) -
merchant_success_callback_url— динамический URL для получения оповещения при успешном завершении операции.
(string<https-url>) (<= 2048 символа) -
merchant_decline_callback_url— динамический URL для получения оповещения, если операция не завершилась успешно.
(string<https-url>) (<= 2048 символа)
-
-
receiver— данные получателя выплаты.-
pan— номер карты получателя.
(string<pan>) (<= 32 символа) -
year— год окончания срока действия карты получателя. Обязательное поле для валютыUZS.
(integer) (2020 <= X <= 2099) -
month— месяц окончания срока действия карты получателя. Обязательное поле для валютыUZS.
(integer) (1 <= X <= 12)
-
-
payment— информация о выплате.-
method— код метода выплаты. Список методов приведен в разделе Платежные методы.
(string) (<= 32 символа) -
amount— сумма выплаты в дробных единицах валюты. Подробнее см. раздел Коды валют.
(integer) (1 <= X <= 10000000000000) -
currency— валюта выплаты в формате ISO-4217 alpha-3. Подробнее о кодах валют см. в разделе Коды валют.
(string) (regex: ^[A-Z]{3}$) -
description— описание выплаты или комментарий. Отображается в личном кабинете мерчанта.
(string) (<= 255 символа) -
extra_param— дополнительный параметр для индивидуальной маршрутизации заявки. Настраивается совместно с администратором.
(string) (regex: ^[A-Za-z0-9_-]{1,16}$)
-
-
customer— информация об отправителе.-
id— уникальный идентификатор пользователя в проекте мерчанта.
(string) (<= 255 символа) -
ip_address— IP-адрес пользователя.
(string<ip-address>) (<= 255 символа) -
first_name— имя клиента, получающего выплату.
(string) (<= 255 символа) -
last_name— фамилия клиента, получающего выплату.
(string) (<= 255 символа) -
country— код страны пользователя в формате ISO 3166-1 alpha-2.
(string) (regex: ^[A-Z]{2}$) -
email— адрес электронной почты пользователя.
(string<email>) (<= 255 символа) -
browser— название и версия браузера пользователя.
(string) (<= 512 символа) -
device_type— тип устройства пользователя.
(string) (<= 512 символа) -
user_agent— идентификационная строка клиентского приложения.
(string) (<= 1024 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/ecom/payout \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
"general": {
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456",
"merchant_callback_url": "https://your-domain.com/internal",
"merchant_success_callback_url": "https://your-domain.com/sucess",
"merchant_decline_callback_url": "https://your-domain.com/decline"
},
"receiver": {
"pan": "4242242442422424"
},
"payment": {
"method": "card-ecom",
"amount": 150000,
"currency": "KZT",
"description": "Comment about the payout",
"extra_param": "example"
},
"customer": {
"id": "random-customer-id",
"ip_address": "1.1.1.1",
"first_name": "John",
"last_name": "Snow",
"country": "RU",
"email": "[email protected]",
"browser": "Google Chrome v15.12",
"device_type": "Iphone 15 Pro",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "new",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456"
}
Параметры ответа:
-
status— статус обработки выплаты. Список статусов приведен в разделе Статусы выплат.
(string) (<= 32 символа) -
sub_status— подстатус обработки выплаты. Используется только для отдельных статусов. Список подстатусов приведен в разделе Статусы выплат.
(string) (<= 32 символа) -
status_description— дополнительная информация по статусу. Используется, если выплата не прошла или произошла ошибка.
(string) (<= 1024 символа) -
request_id— идентификатор платежа, который генерируется в системе HighHelp.
(string) (<= 32 символа) -
project_id— идентификатор кассы, полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, уникальный в рамках кассы мерчанта.
(string) (<= 255 символа)
|
Поля, помеченные , являются обязательными. |
Информация о заявке
POST https://api.hh-processing.com/api/v1/payment/ecom/payout/info
Параметры, которые необходимо отправить в теле запроса для получения статуса ecom заявки на выплату.
-
general— информация по заявке.-
project_id— идентификатор кассы, полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа.
(string) (<= 255 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/ecom/payout/info \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
"general": {
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "payout_process",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-ECOM-123456",
"payment_info": {
"amount": 10000,
"currency": "KZT",
"method": "card-ecom",
"type": "payout"
}
}
Параметры ответа:
-
status— статус обработки выплаты. Список статусов приведен в разделе Статусы выплат.
(string) (<= 32 символа) -
sub_status— подстатус обработки выплаты. Используется только для отдельных статусов. Список подстатусов приведен в разделе Статусы выплат.
(string) (<= 32 символа) -
status_description— дополнительная информация по статусу. Используется, если выплата не прошла или произошла ошибка.
(string) (<= 1024 символа) -
request_id— идентификатор платежа, который генерируется в системе HighHelp.
(string) (<= 32 символа) -
project_id— идентификатор кассы, полученный от HighHelp в процессе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, уникальный в рамках кассы мерчанта.
(string) (<= 255 символа) -
payment_info— информация о выплате.-
amount— сумма заявки в дробных единицах валюты. Подробнее см. раздел Коды валют.
(integer) (1 <= X <= 10000000000000) -
currency— код валюты, в которой выполняется выплата, в формате "ISO-4217 alpha-3". Подробнее о кодах валют см. в разделе Коды валют.
(string) (regex: ^[A-Z]{3}$) -
method— код метода выплаты. Список методов приведен в разделе Платежные методы.
(string) (<= 32 символа) -
type— тип оплаты, который выбран при создании платежа. Подробнее о типах см. в разделе Поддерживаемые типы платежей.
(string) (<= 32 символа)
-
Статусы выплат
| Статус | Подстатус | Описание | Состояние платежа |
|---|---|---|---|
|
Выплата не была выполнена из-за ошибки при проверке запроса. |
Промежуточное состояние. |
|
|
|
Проверка запроса перед обработкой. |
Промежуточное состояние. |
|
Подбор трейдера, который исполнит выплату. |
Промежуточное состояние. |
|
|
Выполняется процесс выплаты по указанным реквизитам. |
Промежуточное состояние. |
|
|
|
Указаны неверные реквизиты для выплаты. |
Промежуточное состояние. |
|
Не удалось выполнить выплату на указанные реквизиты. |
Промежуточное состояние. |
|
|
Выплата не была исполнена до истечения времени жизни заявки. |
Промежуточное состояние. |
|
|
Операция отклонена. |
Финальное состояние. |
|
|
Операция выполнена. |
Финальное состояние. |
Оповещения
|
Рекомендуется реализовать проверку входящих оповещений на дубликаты. Ключ идемпотентности можно формировать по шаблону |
|
Каждое оповещение подписывается цифровой подписью HighHelp. Текущий публичный ключ для проверки подписи можно получить в панели администратора. Ключ уникален для каждой кассы. Алгоритм проверки подписи идентичен алгоритму формирования подписи при вызове API. Примеры проверки подписи приведены в разделе Аутентификация и подпись. |
Предусмотрены три типа оповещений:
-
Информативные — оповещения по промежуточным статусам заявок. Оповещение отправляется при изменении статуса. URL задается в параметре
merchant_callback_urlпри создании заявки. -
Успешные — оповещения по заявкам, завершившимся в статусе
success. URL задается в параметреmerchant_success_callback_url. -
Неуспешные — оповещения по заявкам, завершившимся в статусе
declineили с ошибкой. URL задается в параметреmerchant_decline_callback_url.
Информативные оповещения
Пример оповещения со статусом processing:payout_process:
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "KZT-ECOM-123456"
},
"status": {
"status": "processing",
"sub_status": "payout_process",
"status_description": null
},
"payment_info": {
"amount": 7000,
"currency": "KZT",
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-ecom",
"type": "payout"
},
"additional_info": {}
}
Успешные оповещения
Оповещение отправляется при успешном финальном статусе success.
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "KZT-ECOM-123456"
},
"status": {
"status": "success",
"sub_status": null,
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "KZT",
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-ecom",
"type": "payout"
}
}
Неуспешные оповещения
Оповещение отправляется при неуспешном финальном статусе decline.
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "KZT-ECOM-123456"
},
"status": {
"status": "decline",
"sub_status": null,
"status_description": "Declined by anti-fraud"
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "KZT",
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-ecom",
"type": "payout"
}
}