Интернет-платежи через виджет (ECOM, H2C)
В этом разделе описан сценарий приема интернет-платежей через виджет HighHelp (тип интеграции H2C) с использованием метода /api/v1/widget/payin.
Параметры продукта
| Параметр | Код | Описание |
|---|---|---|
Тип интеграции |
|
Платеж выполняется на платежной странице HighHelp (виджет). |
Валюта |
Поддерживаемые валюты: |
|
Депозиты |
✅ |
Доступный метод оплаты: |
Выплаты |
❌ |
Выплаты через виджет не поддерживаются. |
Создание заявки
POST https://api.hh-processing.com/api/v1/widget/payin
В теле запроса передаются следующие параметры.
-
general— информация по заявке.-
project_id— идентификатор кассы, полученный при интеграции с HighHelp.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, уникальный в рамках кассы мерчанта. Разрешены символы UTF-8.
(string) (<= 255 символа) -
merchant_callback_url— URL для информативных оповещений по промежуточным статусам.
(string<https-url>) (<= 2048 символа) -
merchant_success_callback_url— URL для оповещений об успешных платежах.
(string<https-url>) (<= 2048 символа) -
merchant_decline_callback_url— URL для оповещений о неуспешных платежах.
(string<https-url>) (<= 2048 символа) -
redirect_url— URL, на который пользователь будет перенаправлен с платежной страницы после завершения платежа. Если параметр не передан, используется URL, заданный в настройках кассы.
(string<https-url>) (<= 2048 символа)
-
-
payment— информация о платеже.-
amount— сумма платежа в дробных единицах валюты. Например,10000для суммы 100.00. Подробнее см. Коды валют.
(integer) (1 <= X <= 10000000000000) -
currency— код валюты в формате ISO 4217 alpha-3.
(string) (regex: ^[A-Z]{3}$) -
lifetime— время жизни заявки в секундах. По умолчанию 600 секунд.
(integer) (300 <= X <= 600) -
description— описание платежа или комментарий для отображения в кабинете мерчанта.
(string) (<= 255 символа) -
extra_param— дополнительный параметр для индивидуальной маршрутизации заявки. Значение согласуется с администратором.
(string) (regex: ^[A-Za-z0-9_-]{1,16}$) -
widget_method— метод виджета, предвыбранный в виджете. Список методов см. в разделе Методы виджета.
(string) (<= 32 символа)
-
-
customer— информация о плательщике.-
id— уникальный идентификатор пользователя в системе мерчанта.
(string) (<= 255 символа) -
ip_address— IP-адрес пользователя.
(string<ip-address>) (<= 255 символа) -
country— код страны пользователя в формате ISO 3166-1 alpha-2. Список стран см. в разделе Коды стран.
(string) (regex: ^[A-Z]{2}$) -
language— код языка интерфейса виджета в формате ISO 639-1. Если язык не указан, используется язык по умолчанию для страны. Список языков см. в разделе Коды языков.
(string) (regex: ^[a-z]{2}$) -
email— адрес электронной почты пользователя.
(string<email>) (<= 255 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/widget/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": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-CARD-123456",
"merchant_callback_url": "https://your-callback-domain.com/internal",
"merchant_success_callback_url": "https://your-callback-domain.com/success",
"merchant_decline_callback_url": "https://your-callback-domain.com/decline",
"redirect_url": "https://your-web-site-url.com/order/page"
},
"payment": {
"amount": 1500000,
"currency": "KZT",
"lifetime": 600,
"description": "Comment about the payment",
"extra_param": "example",
"widget_method": "payin-ecom-card"
},
"customer": {
"id": "random-customer-id",
"ip_address": "1.1.1.1",
"country": "KZ",
"language": "kk",
"email": "[email protected]"
}
}'
Пример ответа:
{
"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-CARD-123456",
"integration": {
"form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
"redirect_url": "https://your-web-site-url.com/order/page"
}
}
Поля ответа:
-
status— статус обработки оплаты. Список статусов см. в разделах Статусы оплат (payin) и Коды статусов.
(string) (<= 32 символа) -
sub_status— подстатус обработки платежа.
(string) (<= 32 символа) -
status_description— текстовое описание статуса, включая причину отказа или ошибки.
(string) (<= 1024 символа) -
request_id— идентификатор заявки во внутренней системе HighHelp.
(string) (<= 32 символа) -
project_id— идентификатор кассы.
(string) (<= 32 символа) -
payment_id— идентификатор платежа в системе мерчанта.
(string) (<= 255 символа) -
integration— блок с параметрами для интеграции.-
form_url— URL платежной страницы, на которую необходимо перенаправить пользователя.
(string<https-url>) (<= 255 символа) -
redirect_url— URL для редиректа пользователя после завершения платежа.
(string<https-url>) (<= 2048 символа)
-
|
Поля, помеченные , являются обязательными. |
Получение информации о заявке
POST https://api.hh-processing.com/api/v1/widget/payin/info
Запрос:
-
general— информация по заявке.-
project_id— идентификатор кассы.
(string) (<= 32 символа) -
payment_id— идентификатор платежа.
(string) (<= 255 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/widget/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-CARD-123456"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "awaiting_confirm",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "KZT-CARD-123456",
"payment_info": {
"amount": 10000,
"old_amount": 10000,
"initial_amount": 12000,
"currency": "KZT",
"lifetime": 600,
"expiration_date": 1721647251,
"method": "card-ecom",
"widget_method": "payin-ecom-card",
"type": "payin"
},
"integration": {
"form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
"redirect_url": "https://your-web-site-url.com/order/page"
}
}
Поля ответа:
-
status— текущий статус обработки оплаты.
(string) (<= 32 символа) -
sub_status— текущий подстатус обработки оплаты.
(string) (<= 32 символа) -
status_description— текстовое описание статуса.
(string) (<= 1024 символа) -
request_id— идентификатор заявки во внутренней системе HighHelp.
(string) (<= 32 символа) -
project_id— идентификатор кассы.
(string) (<= 32 символа) -
payment_id— идентификатор платежа в системе мерчанта.
(string) (<= 255 символа) -
payment_info— информация о платеже.-
amount— актуальная сумма заявки в дробных единицах.
(integer) (1 <= X <= 10000000000000) -
old_amount— сумма до изменения по результатам обработки или апелляции. Если сумма не менялась, значения полейamountиold_amountсовпадают.
(integer) (1 <= X <= 10000000000000) -
initial_amount— сумма, указанная при создании заявки.
(integer) (1 <= X <= 10000000000000) -
currency— код валюты в формате ISO 4217 alpha-3.
(string) (regex: ^[A-Z]{3}$) -
lifetime— время жизни заявки в секундах.
(integer) (300 <= X <= 600) -
expiration_date— момент, до которого заявка действительна, в формате Unix Timestamp (UTC).
(integer) (X <= 2^32) -
method— метод оплаты, выбранный при обработке платежа. Список методов см. в разделе Методы оплаты (H2H).
(string) (<= 32 символа) -
widget_method— метод платежной страницы, выбранный во время оплаты.
(string) (<= 32 символа) -
type— тип платежа. Значения описаны в разделе Типы платежей.
(string) (<= 32 символа)
-
-
integration— дополнительные данные интеграции.-
form_url— URL платежной страницы, по которому доступна заявка.
(string<https-url>) (<= 255 символа) -
redirect_url— URL для редиректа с платежной страницы после завершения платежа.
(string<https-url>) (<= 2048 символа)
-
Статусы оплат
|
Статусы и переходы для ecom-заявок совпадают с жизненным циклом оплат по H2H. См. раздел Типы операций и статусы заявок (payin). |
Оповещения о статусе
Общие сведения
Оповещения отправляются на URL-адреса, указанные при создании заявки:
-
merchant_callback_url— информативные оповещения по промежуточным статусам. -
merchant_success_callback_url— оповещения об успешных платежах. -
merchant_decline_callback_url— оповещения о неуспешных платежах.
|
Важно реализовать проверку дубликатов оповещений. Рекомендуется использовать ключ идемпотентности вида |
|
Каждое оповещение подписывается цифровой подписью HighHelp. Публичный ключ для проверки подписи можно получить в кабинете. Ключи различаются для разных касс. |
Информативные оповещения
|
Информативные оповещения по интернет-платежам в текущей версии не отправляются. |
Успешные оповещения
Оповещение отправляется, если заявка получила финальный статус success.
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "KZT-CARD-123456"
},
"status": {
"status": "success",
"sub_status": null,
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 5000,
"initial_amount": 3000,
"currency": "KZT",
"lifetime": 600,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-ecom",
"widget_method": "payin-ecom-card",
"type": "payin"
}
}
Неуспешные оповещения
Оповещение отправляется, если заявка получила финальный статус decline.
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "KZT-CARD-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": 600,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": null,
"widget_method": null,
"type": "payin"
}
}