Банковские переводы в Азербайджане
| Название | Код | Описание |
|---|---|---|
Тип интеграции |
|
Платеж через API HighHelp на стороне мерчанта |
Валюта |
|
Азербайджанский манат |
Страна |
|
Азербайджан |
Депозиты |
✅ |
Доступные методы оплаты: |
Выплаты |
✅ |
Доступные методы выплат: |
Оплата
Общие требования к интеграции P2P-оплат по API описаны в разделе Общие требования для P2P (H2H).
Создание заявки
POST https://api.hh-processing.com/api/v1/payment/p2p/payin
Параметры тела запроса при создании P2P-заявки.
-
general— информация о заявке-
project_id— идентификатор кассы, выданный HighHelp на этапе интеграции.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, уникальный в рамках кассы мерчанта. Допустимы любые символы в кодировке UTF-8.
(string) (<= 255 символа) -
merchant_callback_url— динамический URL для получения информативных оповещений, например об изменении промежуточных статусов заявки и реквизитах для оплаты P2P-заявки. Оповещения по финальным статусам отправляются на 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 символа) -
redirect_url— ссылка для перенаправления пользователя с платежной страницы после завершения оплаты.
(string<https-url>) (<= 2048 символа)
-
-
payment— информация об оплате-
method— код метода оплаты. Список кодов описан в разделе Платежные методы и коды (H2H).
(string) (<= 32 символа) -
amount— сумма, которую намерен оплатить пользователь. Сумма указывается в дробных единицах; подробнее см. в разделе Коды валют.
(integer) (1 <= X <= 10000000000000) -
currency— код валюты, в которой оплачивает пользователь, в форматеISO 4217 alpha-3. Список кодов приведен в разделе Коды валют.
(string) (regex: ^[A-Z]{3}$) -
lifetime— время жизни заявки в секундах. Максимум — 10 минут. Если параметр не указан, используется значение по умолчанию 10 минут.
(integer) (300 <= X <= 600) -
bank_symbol— код банка, на который пользователь хочет выполнить перевод. Если параметр не передан, банк выбирается случайным образом. Список доступных банков можно получить по API/api/v1/payment/p2p/bank/available. Примеры банков приведены в разделе Банки для P2P. Использование параметра снижает конверсию в выдачу реквизитов, поэтому его рекомендуется задавать только при необходимости.
(string) (<= 32 символа) -
description— описание платежа или комментарий. Отображается в кабинете мерчанта.
(string) (<= 255 символа) -
extra_param— дополнительный параметр для индивидуальной маршрутизации заявки. Настраивается совместно со специалистами HighHelp.
(string) (regex: ^[A-Za-z0-9_-]{1,16}$)
-
-
sender— данные карты или телефона отправителя-
pan— номер карты отправителя.
(string<pan>) (<= 32 символа) -
phone— номер телефона отправителя.
(string) (<= 24 символа)
(regex: ^\+7\d{10}$|^\+994\d{7,12}$) -
bank_symbol— код банка, с карты или счета которого пользователь будет оплачивать. Для получения кодов банков используйте API/api/v1/payment/p2p/bank/all. Если банка нет в списке, параметр можно не передавать.
(string) (<= 32 символа) -
card_holder— имя отправителя, как на карте.
(string) (<= 255 символа)
(regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЕРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$)
-
-
customer— информация о пользователе-отправителе-
id— уникальный идентификатор пользователя в системе мерчанта.
(string) (<= 255 символа) -
ip_address— IP-адрес отправителя.
(string<ip-address>) (<= 255 символа) -
first_name— имя пользователя, выполняющего оплату.
(string) (<= 255 символа) -
last_name— фамилия пользователя, выполняющего оплату.
(string) (<= 255 символа) -
customer_type— тип пользователя:ftd— первичный трафик,trust— повторный трафик.
(string) (regex: ^(ftd|trust)$) -
country— код страны пользователя в форматеISO 3166-1 alpha-2. Список кодов стран приведен в разделе Коды стран.
(string) (regex: ^[A-Z]{2}$) -
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/p2p/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": "AZN-PAYMENT-123456",
"merchant_callback_url": "https://your-domain.com/internal",
"merchant_success_callback_url": "https://your-domain.com/success",
"merchant_decline_callback_url": "https://your-domain.com/decline",
"redirect_url": "https://your-domain.com/order/page"
},
"payment": {
"method": "card-p2p",
"amount": 150000,
"currency": "AZN",
"lifetime": 300,
"description": "Comment about the payment",
"extra_param": "example"
},
"sender": {
"pan": "4850788018041726",
"card_holder": "Erik Ackerman"
},
"customer": {
"id": "random-customer-id",
"ip_address": "1.1.1.1",
"first_name": "John",
"last_name": "Snow",
"customer_type": "ftd",
"country": "AZ",
"language": "az",
"email": "[email protected]",
"browser": "Google Chrome v15.12",
"device_type": "Iphone 15 Pro"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "requisites",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "AZN-PAYMENT-123456",
"integration": {
"form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
"redirect_url": "https://your-domain.com/order/page"
}
}
Параметры ответа:
-
status— статус обработки оплаты. Список кодов статусов приведен в разделе Коды статусов.
(string) (<= 32 символа) -
sub_status— под-статус обработки платежа. Используется только для отдельных значенийstatus. Подробности см. в разделе Типы операций и статусы.
(string) (<= 32 символа) -
status_description— дополнительное описание статуса. Используется при ошибках или неуспешной оплате.
(string) (<= 1024 символа) -
request_id— идентификатор платежа, генерируемый платежной системой HighHelp.
(string) (<= 32 символа) -
project_id— идентификатор кассы, выданный HighHelp.
(string) (<= 32 символа) -
payment_id— идентификатор платежа в системе мерчанта.
(string) (<= 255 символа) -
integration— дополнительная метаинформация по платежу-
form_url— ссылка на платежную страницу. На странице отображаются реквизиты для оплаты, инструкция и сопутствующие данные.
(string<https-url>) (<= 255 символа) -
redirect_url— ссылка для перенаправления пользователя после завершения платежа.
(string<https-url>) (<= 2048 символа)
-
|
Поля |
|
Поля, помеченные , являются обязательными. |
Данные для отображения в платежной инструкции
Перед выводом платежной инструкции необходимо получить данные для ее формирования. Возможны два подхода:
-
дождаться оповещения со статусом
processing:awaiting_confirmна URL, указанный в параметреmerchant_callback_url. В теле оповещения будут переданы данные для инструкции; -
опрашивать метод
https://api.hh-processing.com/api/v1/payment/p2p/payin/infoс интервалом 15 секунд до тех пор, пока статус заявки не станетprocessing:awaiting_confirm. После этого в ответе будут доступны данные инструкции.
В теле оповещения или ответа необходимо получить поле display_data. Это массив объектов со следующими полями:
-
type— тип объекта. Для P2P-платежей используется значениеadd_info; -
title— имя атрибута инструкции. Возможные значения:-
recipient_card_holder— полное имя держателя карты; -
recipient_pan— номер карты, на которую нужно выполнить перевод; -
recipient_phone— номер телефона, на который нужно выполнить перевод; -
lifetime— время жизни инструкции (заявки) в секундах; -
valid_until— момент, до которого инструкция действительна, в формате Unix Timestamp (UTC); -
amount— сумма перевода в дробных единицах; подробнее см. в разделе Коды валют; -
currency— код валюты в форматеISO 4217 alpha-3; -
bank_name— наименование банка получателя; -
bank_country— код страны банка получателя в форматеISO 3166-1 alpha-2; полный список кодов см. в разделе Коды стран; -
confirm_url— URL для отправки запроса при подтверждении факта оплаты пользователем; -
reject_url— URL для отправки запроса при отказе пользователя от оплаты;
-
-
data— значение атрибута инструкции.
Пример фрагмента с платежной инструкцией:
"display_data": [
{
"type": "add_info",
"title": "recipient_card_holder",
"data": "John Snow"
},
{
"type": "add_info",
"title": "recipient_pan",
"data": "4850777018041155"
},
{
"type": "add_info",
"title": "recipient_phone",
"data": "+994909994433"
},
{
"type": "add_info",
"title": "lifetime",
"data": 300
},
{
"type": "add_info",
"title": "valid_until",
"data": 1721647251
},
{
"type": "add_info",
"title": "amount",
"data": 10000
},
{
"type": "add_info",
"title": "currency",
"data": "AZN"
},
{
"type": "add_info",
"title": "bank_name",
"data": "m10-az"
},
{
"type": "add_info",
"title": "bank_country",
"data": "AZ"
},
{
"type": "add_info",
"title": "confirm_url",
"data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm"
},
{
"type": "add_info",
"title": "reject_url",
"data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel"
}
]
Информация о заявке
POST https://api.hh-processing.com/api/v1/payment/p2p/payin/info
Параметры тела запроса для получения статуса P2P-заявки.
-
general— информация о заявке-
project_id— идентификатор кассы, выданный HighHelp.
(string) (<= 32 символа) -
payment_id— идентификатор платежа в системе мерчанта.
(string) (<= 255 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/p2p/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": "AZN-PAYMENT-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": "AZN-PAYMENT-123456",
"payment_info": {
"amount": 10000,
"old_amount": 10000,
"initial_amount": 3000,
"currency": "AZN",
"lifetime": 300,
"expiration_date": 1721647251,
"method": "card-p2p",
"payment_system": null,
"type": "payin"
},
"recipient_requisites": {
"pan": "4850788018041726",
"card_holder": "Khal Drogo",
"bank_name": "m10-az",
"bank_country": "AZ",
"currency": "AZN"
},
"sender": {
"pan_hidden": "48507****1726",
"card_holder_hidden": "Erik****rman"
},
"integration": {
"form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
"redirect_url": "https://your-domain.com/order/page"
}
}
Параметры ответа:
-
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) -
old_amount— исходная сумма заявки до апелляции. Если пользователь перевел сумму, отличающуюся от исходной, вamountпередается фактическая сумма, а вold_amount— исходная. При расхождении сумм требуется создать апелляцию через поддержку HighHelp.
(integer) (1 <= X <= 10000000000000) -
initial_amount— сумма, указанная при создании заявки. Значение не меняется.
(integer) (1 <= X <= 10000000000000) -
currency— код валюты оплаты в форматеISO 4217 alpha-3; см. в разделе Коды валют.
(string) (regex: ^[A-Z]{3}$) -
lifetime— время жизни заявки в секундах (не более 10 минут).
(integer) (300 <= X <= 600) -
expiration_date— момент, до которого заявка действительна, в формате Unix Timestamp (UTC).
(integer) (X <= 2^32) -
method— метод оплаты, выбранный при создании заявки; коды методов см. в разделе Платежные методы и коды (H2H).
(string) (<= 32 символа) -
type— тип операции, напримерpayin; общий список типов см. в разделе Типы платежей.
(string) (<= 32 символа)
-
-
recipient_requisites— реквизиты, на которые ожидается перевод-
pan— номер карты или телефона получателя платежа.
(string<pan>) (<= 4096 символа) -
card_holder— имя держателя карты (как на карте). В редких случаях может содержать техническое значение"--".
(string) (<= 255 символа) -
bank_name— наименование банка получателя.
(string) (<= 255 символа) -
currency— код валюты операции в форматеISO 4217 alpha-3; см. в разделе Коды валют.
(string) (regex: ^[A-Z]{3}$)
-
-
sender— реквизиты отправителя (пользователя мерчанта)-
pan_hidden— маскированный номер карты или телефона отправителя.
(string) (<= 32 символа) -
card_holder_hidden— маскированное имя держателя карты отправителя.
(string) (<= 255 символа)
-
-
integration— дополнительная метаинформация по платежу-
form_url— ссылка на платежную страницу с реквизитами и инструкцией.
(string<https-url>) (<= 255 символа) -
redirect_url— ссылка для перенаправления пользователя после завершения платежа.
(string<https-url>) (<= 2048 символа)
-
|
Поля |
Отмена заявки
POST https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel
Параметры тела запроса при отмене P2P-заявки.
-
general— информация о заявке-
project_id— идентификатор кассы HighHelp.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, который требуется отменить.
(string) (<= 255 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel \
-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": "AZN-PAYMENT-123456"
}
}'
Пример ответа:
{
"status": "decline",
"sub_status": null,
"status_description": "Canceled by client",
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "AZN-PAYMENT-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/p2p/payin/confirm
Параметры тела запроса для подтверждения, что пользователь перевел средства на выданные реквизиты.
-
general— информация о заявке-
project_id— идентификатор кассы HighHelp.
(string) (<= 32 символа) -
payment_id— идентификатор платежа, для которого выполняется подтверждение.
(string) (<= 255 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm \
-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": "AZN-PAYMENT-123456"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "paid",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "AZN-PAYMENT-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_confirm:
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "AZN-PAYMENT-123456"
},
"status": {
"status": "processing",
"sub_status": "awaiting_confirm",
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "AZN",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-p2p",
"payment_system": null,
"type": "payin"
},
"recipient_requisites": {
"pan": "4850788018041726",
"card_holder": "Khal Drogo",
"bank_name": "m10-az",
"bank_country": "AZ",
"currency": "AZN"
},
"integration": {
"form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
"redirect_url": "https://your-domain.com/order/page"
},
"additional_info": {
"display_data": [
{
"type": "add_info",
"title": "recipient_card_holder",
"data": "Khal Drogo"
},
{
"type": "add_info",
"title": "recipient_pan",
"data": "4850788018041726"
},
{
"type": "add_info",
"title": "lifetime",
"data": 300
},
{
"type": "add_info",
"title": "valid_until",
"data": 1721647251
},
{
"type": "add_info",
"title": "amount",
"data": 10000
},
{
"type": "add_info",
"title": "currency",
"data": "AZN"
},
{
"type": "add_info",
"title": "bank_name",
"data": "m10-az"
},
{
"type": "add_info",
"title": "bank_country",
"data": "AZ"
},
{
"type": "add_info",
"title": "confirm_url",
"data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm"
},
{
"type": "add_info",
"title": "reject_url",
"data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel"
}
]
}
}
|
Реквизиты ( |
Успешные оповещения
Оповещение отправляется, если заявка перешла в финальный успешный статус success.
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "AZN-PAYMENT-123456"
},
"status": {
"status": "success",
"sub_status": null,
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 5000,
"initial_amount": 3000,
"currency": "AZN",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-p2p",
"payment_system": null,
"type": "payin"
}
}
Неуспешные оповещения
Оповещение отправляется, если заявка завершилась неуспешно (например, финальный статус decline).
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "AZN-PAYMENT-123456"
},
"status": {
"status": "decline",
"sub_status": null,
"status_description": "Declined by anti-fraud"
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "AZN",
"lifetime": 300,
"expiration_date": 1721647251,
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-p2p",
"payment_system": null,
"type": "payin"
}
}
Выплата
Создание заявки на выплату
POST https://api.hh-processing.com/api/v1/payment/p2p/payout
Параметры тела запроса при создании P2P-выплаты на карту или телефон.
-
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— номер карты получателя; обязательный параметр, еслиpayment.method = "card-p2p".
(string<pan>) (<= 32 символа) -
phone— номер телефона получателя; обязательный параметр, еслиpayment.method = "phone-p2p".
(string) (<= 24 символа)
(regex: ^\+7\d{10}$|^\+994\d{7,12}$) -
bank_code— код банка получателя. Пример для "Сбербанка":100000000111. Список кодов банков доступен по API/api/v1/bank/all.
(string) (= 12 символов)
(regex: ^\d{12}$) -
card_holder— имя держателя карты получателя, как на карте.
(string) (<= 255 символа)
(regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЕРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$)
-
-
payment— информация о выплате-
method— код метода выплаты. Коды описаны в разделе Платежные методы и коды (H2H).
(string) (<= 32 символа) -
amount— сумма, которую необходимо отправить получателю. Сумма указывается в дробных единицах; подробнее см. в разделе Коды валют.
(integer) (1 <= X <= 10000000000000) -
currency— валюта выплаты в форматеISO 4217 alpha-3.
(string) (regex: ^[A-Z]{3}$) -
description— описание выплаты или комментарий. Отображается в кабинете мерчанта.
(string) (<= 255 символа) -
extra_param— дополнительный параметр для маршрутизации заявки, согласуется со специалистами HighHelp.
(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/p2p/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": "AZN-PAYOUT-123456",
"merchant_callback_url": "https://your-domain.com/internal",
"merchant_success_callback_url": "https://your-domain.com/success",
"merchant_decline_callback_url": "https://your-domain.com/decline"
},
"receiver": {
"pan": "4850788018041726",
"card_holder": "Erik Ackerman"
},
"payment": {
"method": "card-p2p",
"amount": 100,
"currency": "AZN",
"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"
}
}'
Пример ответа:
{
"status": "processing",
"sub_status": "new",
"status_description": null,
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"payment_id": "AZN-PAYOUT-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/p2p/payout/info
Параметры тела запроса для получения статуса P2P-выплаты.
-
general— информация о заявке-
project_id— идентификатор кассы HighHelp.
(string) (<= 32 символа) -
payment_id— идентификатор выплаты.
(string) (<= 255 символа)
-
|
Поля, помеченные , являются обязательными. |
Пример запроса:
curl https://api.hh-processing.com/api/v1/payment/p2p/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": "AZN-PAYOUT-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": "AZN-PAYOUT-123456",
"payment_info": {
"amount": 10000,
"old_amount": 10000,
"initial_amount": 3000,
"currency": "AZN",
"method": "card-p2p",
"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) -
old_amount— сумма заявки до апелляции. При расхождении с фактической суммой требуется апелляция через поддержку HighHelp.
(integer) (1 <= X <= 10000000000000) -
initial_amount— сумма, указанная при создании заявки.
(integer) (1 <= X <= 10000000000000) -
currency— код валюты выплаты в форматеISO 4217 alpha-3; см. в разделе Коды валют.
(string) (regex: ^[A-Z]{3}$) -
method— код метода выплаты; коды см. в разделе Платежные методы и коды (H2H).
(string) (<= 32 символа) -
type— тип операции, напримерpayout; список типов приведен в Типы платежей.
(string) (<= 32 символа)
-
Статусы выплат
Типы операций и статусов описаны в разделе Типы операций и статусы.
Коды статусов и возможные значения status и sub_status приведены в разделе Коды статусов.
| Статус | Под-статус | Описание | Состояние платежа |
|---|---|---|---|
error |
Выплата отклонена из-за ошибки, возникшей при проверке запроса. |
Промежуточное состояние |
|
processing |
new |
Проверка запроса перед обработкой. |
Промежуточное состояние |
requisites |
Подбор трейдера, который исполнит выплату. |
Промежуточное состояние |
|
payout_process |
Выполнение выплаты по указанным реквизитам. |
Промежуточное состояние |
|
dispute |
incorrect_requisites |
Трейдер сообщил о некорректных реквизитах выплаты. |
Промежуточное состояние |
payout_failed |
Трейдер не смог выполнить выплату на корректные реквизиты. |
Промежуточное состояние |
|
payout_timeout |
Время жизни заявки истекло, трейдер не успел исполнить выплату. |
Промежуточное состояние |
|
decline |
Выплата отклонена. |
Финальное состояние |
|
success |
Выплата успешно выполнена. |
Финальное состояние |
Оповещения
|
Рекомендуется реализовать проверку входящих оповещений на дубликаты. Ключ идемпотентности можно формировать по шаблону |
|
Каждое оповещение подписывается цифровой подписью 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": "AZN-PAYOUT-123456"
},
"status": {
"status": "processing",
"sub_status": "payout_process",
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "AZN",
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-p2p",
"type": "payout"
},
"additional_info": {}
}
Успешные оповещения
Оповещение отправляется при успешной выплате (статус success).
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "AZN-PAYOUT-123456"
},
"status": {
"status": "success",
"sub_status": null,
"status_description": null
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "AZN",
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-p2p",
"type": "payout"
}
}
Неуспешные оповещения
Оповещение отправляется, если выплата завершилась неуспешно (статус decline).
{
"project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
"general": {
"request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
"payment_id": "AZN-PAYOUT-123456"
},
"status": {
"status": "decline",
"sub_status": null,
"status_description": "Declined by anti-fraud"
},
"payment_info": {
"amount": 7000,
"old_amount": 7000,
"initial_amount": 3000,
"currency": "AZN",
"updated_date": 1721647251,
"created_date": 1721647251,
"method": "card-p2p",
"type": "payout"
}
}