Банковские переводы в Казахстане¶

Название	Код	Описание
Тип интеграции	`H2H`	Платеж на вашей форме оплаты
Валюта	`KZT`	Казахстанский тенге
Страна	`KZ`	Республика Казахстан
Депозиты	✅	Доступные методы для оплаты: - `international-card-p2p`
Выплаты	✅	Доступные методы для выплаты: - `card-p2p`

Оплата¶

Создание заявки¶

POST https://api.hh-processing.com/api/v1/payment/p2p/payin

Параметры, которые необходимо отправить в теле запроса при создании p2p заявки.

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции. (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 - cсылка для редиректа пользователя с формы оплаты после завершения платежа (string<https-url>) (<= 2048 символа)
payment** - информация по платежу
- method** - код метода оплаты. Список методов находится в разделе "Поддерживаемые платежные методы". (string) (<= 32 символа)
- amount** - сумма, которую намеревается оплатить пользователь. Сумму необходимо указывать в дробных единицах. Подробнее об этом можно прочитать в разделе "Коды валют" (integer) (1 <= X <= 10000000000000)
- currency** - код валюты в которой оплачивает пользователь в формате "ISO-4217 alpha-3". Подробнее о кодах валют в разделе "Коды валют" (string) (regex: ^[A-Z]{3}$)
- lifetime - время жизни заявки в секундах. Максимальное время жизни — 15 мин. Если время не указано, то устанавливается значение по умолчанию — 10 мин. (integer) (300 <= X <= 900)
- bank_symbol - символ банка на который клиент хотел бы исполнить перевод. Если банк не указывается, то банк выбирается случайным образом. Список доступных банков можно получить по API: /api/v1/payment/p2p/bank/available. В разделе "Поддерживаемые банки для p2p оплат" приведены примеры банков. Будьте аккуратны используя данный параметр, т.к. он сильно снижает конверсию в выдачу реквизитов. (string) (<= 32 символа)
- description - описание платежа или комментарий. Данные будут отображены в личном кабинете мерчанта. (string) (<= 255 символа)
- extra_param - дополнительный параметр, используемый для индивидуальной маршрутизации заявки. Настраивается совместно с администратором. (string) (regex: ^[A-Za-z0-9_-]{1,16}$)
sender - информация о карте пользователя, с которой производится оплата
- pan - номер карты отправителя (string<pan>) (<= 32 символа)
- phone - номер телефона отправителя (string) (<= 24 символа) (regex: ^\+7\d{10}$)
- 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: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
-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-VISA-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",
    "redirect_url": "https://your-domain.com/order/page"
  },
  "payment": {
    "method": "international-card-p2p",
    "amount": 500000,
    "currency": "KZT",
    "lifetime": 300,
    "description": "Comment about the payment",
    "extra_param": "example"
  },
  "sender": {
    "pan": "4400430140020306"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "first_name": "Aidar",
    "last_name": "Nurgaliev",
    "customer_type": "ftd",
    "country": "KZ",
    "language": "kk",
    "email": "example@mailer.com",
    "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": "KZT-VISA-123456",
  "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** - идентификатор платежа, который генерируется в нашей платежной системе (string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции (string) (<= 32 символа)
payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта (string) (<= 255 символа)
integration - дополнительная мета информация по платежу
- form_url** - ссылка на платежную страницу, на которую можно пере-адресовать пользователя. На платежной странице отображаются реквизиты для оплаты, платёжная инструкция и другая информация необходимая для платежа. (string<https-url>) (<= 255 символа)
- redirect_url - cсылка для редиректа пользователя с формы оплаты после завершения платежа (string<https-url>) (<= 2048 символа)

Поля помеченные ** являются обязательными

Информация о заявке¶

POST https://api.hh-processing.com/api/v1/payment/p2p/payin/info

Параметры, которые необходимо отправить в теле запроса для получения статуса p2p заявки.

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции. (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: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
-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-VISA-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-VISA-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-domain.com/order/page"
  },
  "payment_info": {
    "amount": 500000,
    "old_amount": 500000,
    "initial_amount": 500000,
    "currency": "KZT",
    "lifetime": 300,
    "expiration_date": 1769765858,
    "type": "payin",
    "payment_system": null,
    "method": "international-card-p2p"
  },
  "recipient_requisites": {
    "pan_hidden": "card****8951",
    "card_holder_hidden": null
  }
}

Параметры ответа:

status** - статус обработки оплаты. Список статусов можно посмотреть в разделе "Статусы оплат" (string) (<= 32 символа)
sub_status - под-статус обработки платежа. Используется только для определенных статусов оплат. Список под-статусов можно посмотреть в разделе "Статусы оплат" (string) (<= 32 символа)
status_description - дополнительная информация по статусу. Используется в случае, если оплата не прошла, либо произошла ошибка (string) (<= 1024 символа)
request_id** - идентификатор платежа, который генерируется в нашей платежной системе (string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции (string) (<= 32 символа)
payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта (string) (<= 255 символа)
payment_info** - информация по оплате
- amount** - сумма заявки. Сумма указывается в дробных единицах. Подробнее об этом можно прочитать в разделе "Коды валют"; (integer) (1 <= X <= 10000000000000)
- old_amount** - сумма заявки до апелляции. Сумма может измениться, если заявка была создана на одну сумму, но пользователь перевёл другую сумму. В таком случае, в поле amount указывается фактическая сумма, полученная от пользователя (необходимо связаться с тех. поддержкой HH и решить апелляцию по заявке). А в поле 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 <= 900)
- expiration_date** - unix timestamp до какого момента заявка будет валидна (integer)
- updated_date - unix timestamp последнего изменения заявки (integer)
- created_date - unix timestamp создания заявки (integer)
- method** - код метода оплаты. Список методов находится в разделе "Поддерживаемые платежные методы". (string) (<= 32 символа)
- type** - тип оплаты, который был выбран при создании платежа. Подробнее о методах оплаты можно прочитать в разделе "Поддерживаемые типы платежей" (string) (<= 32 символа)
recipient_requisites - реквизиты получателя
- pan** - номер карты получателя (string<pan>) (<= 32 символа)
- card_holder - имя получателя (в точности как написано на карте) (string) (<= 255 символа)
- bank_name** - название банка получателя (string) (<= 255 символа)
- bank_country - код страны банка получателя в формате "ISO 3166-1 alpha-2" (string) (regex: ^[A-Z]{2}$)
- currency - код валюты реквизита в формате "ISO-4217 alpha-3" (string) (regex: ^[A-Z]{3}$)
integration - дополнительная мета информация по платежу
- form_url** - ссылка на платежную страницу, на которую можно переадресовать пользователя. На платежной странице отображаются реквизиты для оплаты, платёжная инструкция и другая информация необходимая для платежа. (string<https-url>) (<= 255 символа)
- redirect_url - cсылка для редиректа пользователя с формы оплаты после завершения платежа (string<https-url>) (<= 2048 символа)

Поля помеченные ** являются обязательными

Отмена заявки¶

POST https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel

Параметры, которые необходимо отправить в теле запроса для отмены p2p заявки.

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции. (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: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
-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-VISA-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": "KZT-VISA-123456"
}

Параметры ответа:

status** - статус обработки оплаты. Список статусов можно посмотреть в разделе "Статусы оплат" (string) (<= 32 символа)
sub_status - под-статус обработки платежа. Используется только для определенных статусов оплат. Список под-статусов можно посмотреть в разделе "Статусы оплат" (string) (<= 32 символа)
status_description - дополнительная информация по статусу. Используется в случае, если оплата не прошла, либо произошла ошибка (string) (<= 1024 символа)
request_id** - идентификатор платежа, который генерируется в нашей платежной системе (string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции (string) (<= 32 символа)
payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта (string) (<= 255 символа)

Подтверждение оплаты¶

POST https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm

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

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции. (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: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
-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-VISA-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": "KZT-VISA-123456"
}

Параметры ответа:

status** - статус обработки оплаты. Список статусов можно посмотреть в разделе "Статусы оплат" (string) (<= 32 символа)
sub_status - под-статус обработки платежа. Используется только для определенных статусов оплат. Список под-статусов можно посмотреть в разделе "Статусы оплат" (string) (<= 32 символа)
status_description - дополнительная информация по статусу. Используется в случае, если оплата не прошла, либо произошла ошибка (string) (<= 1024 символа)
request_id** - идентификатор платежа, который генерируется в нашей платежной системе (string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции (string) (<= 32 символа)
payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта (string) (<= 255 символа)

Статусы оплат¶

Статус	Под-статус	Описание	Состояние платежа
error		Платеж не был осуществлен из-за ошибки, возникшей при проверке запроса	Промежуточное состояние
processing	new	Проверка запроса перед непосредственной его обработкой	Промежуточное состояние
	requisites	Подбор реквизитов, на которые клиенту будет необходимо перечислить указанную в запросе сумму	Промежуточное состояние
	awaiting_confirm	Ожидание подтверждения оплаты от клиента, т.к. реквизиты ему уже были предоставлены	Промежуточное состояние
	paid	Клиент подтвердил, что он отправил сумму на выданные реквизиты	Промежуточное состояние
dispute	no_payment	Клиент не произвёл оплату по заявке, за время её жизни (lifetime)	Промежуточное состояние
	different_amount	Клиент отправил неверную сумму	Промежуточное состояние
	confirm_timeout	Время жизни заявки истекло, но клиент подтвердил оплату предоставив чек	Промежуточное состояние
decline		Платеж отклонен	Финальное состояние
success		Платеж проведен	Финальное состояние

Оповещения (callback):¶

Важно, чтобы в вашей системе была реализована логика проверки оповещений на дубликаты. Мы рекомендуем собирать ключ идемпотентности вам самостоятельно по следующему принципу: {project_id}:{payment_id}:{status}:{sub_status}. Если вы получается повторные опощения, то система должна их игнорировать, чтобы исключить задвойки.

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

У p2p платежей есть 3 типа оповещений:

Информативные - оповещения по промежуточным статусам заявок. Оповещение отправляется, если у заявки меняется статус. URL для отправки оповещений указывается при создании заявки в параметре merchant_callback_url
Успешные - оповещения по успешным заявкам. Оповещение отравляется, если заявка завершена успешно. URL для отправки оповещений указывается при создании заявки в параметре merchant_success_callback_url
Неуспешные - оповещения по неуспешным заявкам. Оповещение отправляется, если в процессе обработки заявки возникла ошибка, либо время жизни заявки истекло. 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": "KZT-VISA-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_confirm",
    "status_description": null
  },
  "payment_info": {
    "amount": 500000,
    "old_amount": 500000,
    "initial_amount": 500000,
    "currency": "KZT",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "international-card-p2p",
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "4400430140020306",
    "card_holder": "Alibek Kairat",
    "bank_name": "Kaspi Bank",
    "bank_country": "KZ",
    "currency": "KZT"
  },
  "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": "Alibek Kairat"
      },
      {
        "type": "add_info",
        "title": "recipient_pan",
        "data": "4400430140020306"
      },
      {
        "type": "add_info",
        "title": "lifetime",
        "data": 300
      },
      {
        "type": "add_info",
        "title": "valid_until",
        "data": 1721647251
      },
      {
        "type": "add_info",
        "title": "amount",
        "data": 500000
      },
      {
        "type": "add_info",
        "title": "currency",
        "data": "KZT"
      },
      {
        "type": "add_info",
        "title": "bank_name",
        "data": "Kaspi Bank"
      },
      {
        "type": "add_info",
        "title": "bank_country",
        "data": "KZ"
      },
      {
        "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"
      }
    ]
  }
}

Реквизиты (recipient_requisites) и платежная инструкция (additional_info) отправляются в колбэках, но только для статусов: processing:awaiting_confirm и processing:paid.
В случае, если статус заявки другой, то реквизиты не будут отправлены. Пример: "recipient_requisites": null и "additional_info": null.

Успешные оповещения¶

Данное оповещение отправляется в том случае, если заявка приняла успешное финальное состояние - статус success. Пример оповещения показан ниже.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-VISA-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 500000,
    "old_amount": 500000,
    "initial_amount": 500000,
    "currency": "KZT",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "payment_system": null,
    "type": "payin"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Неуспешные оповещения¶

Данное оповещение отправляется в том случае, если заявка приняла неуспешное финальное состояние - статус decline. Пример оповещения показан ниже.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-VISA-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Order cancelled by timeout"
  },
  "payment_info": {
    "amount": 500000,
    "old_amount": 500000,
    "initial_amount": 500000,
    "currency": "KZT",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "null",
    "payment_system": null,
    "type": "payin"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Примеры кода¶

Пример кода Python3, для принятия оповещений и проверки их цифровой подписи

import json  
import base64  

from Crypto.Hash import SHA256  
from Crypto.PublicKey import RSA  
from Crypto.Signature.pkcs1_15 import PKCS115_SigScheme  

from fastapi import FastAPI, Request, Response  
from uvicorn import run  


app = FastAPI()  


pub_key_file_path = "./public.pem"  
with open(pub_key_file_path, "rb") as f:  
    encoded_pub_key = base64.urlsafe_b64encode(  
        RSA.importKey(f.read()).export_key(),  
    ).decode('utf-8')  


def parse_json(prefix, obj, _result):  
    if isinstance(obj, dict):  
        for key, value in obj.items():  
            new_prefix = f"{prefix}:{key}" if prefix else key  
            parse_json(new_prefix, value, _result)  
    elif isinstance(obj, list):  
        for index, item in enumerate(obj):  
            new_prefix = f"{prefix}:{index}"  
            parse_json(new_prefix, item, _result)  
    else:  
        _result.append(f"{prefix}:{obj or 'None'}")  


def normalize_message(_payload):  
    _result = []  
    parse_json('', _payload, _result)  
    _result.sort()  
    _joined_result = ";".join(_result)  
    return _joined_result  


@app.route("/callback", methods=["POST", "GET"])  
async def validate_request(  
    request: Request,  
):  
    _headers = request.headers  
    body = await request.body()  

    if not body:  
        payload = {}  
    else:  
        payload = json.loads(body.decode("utf-8"))  

    joined_result = normalize_message(payload).encode("utf-8")  

    message = "{}{}".format(  
        base64.urlsafe_b64encode(joined_result).decode("utf-8"),  
        str(  
            _headers.get("x-access-timestamp"),  
        ),  
    )  

    if _headers.get("x-access-token") != encoded_pub_key:  
        raise ValueError("Invalid public key")  

    signature = _headers.get("x-access-signature")  

    pub_key = base64.urlsafe_b64decode(  
        encoded_pub_key.encode("utf-8"),  
    )  
    pub_key_rsa = RSA.importKey(pub_key)  
    hash_of_received = SHA256.new(message.encode("utf-8"))  
    verifier = PKCS115_SigScheme(pub_key_rsa)  
    try:  
        base64_bytes = signature.encode("ascii")  
        signature_bytes = base64.urlsafe_b64decode(base64_bytes)  
        verifier.verify(hash_of_received, signature_bytes)  
    except ValueError:  
        raise ValueError("Invalid signature")  

    return Response(status_code=200)  


if __name__ == '__main__':  
    run(app, host="0.0.0.0", port=8080)

Выплата¶

Создание заявки на выплату¶

POST https://api.hh-processing.com/api/v1/payment/p2p/payout

Параметры, которые необходимо отправить в теле запроса при создании выплаты на карту.

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции. (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 - номер телефона получателя. (string) (<= 24 символа) (regex: ^\+7\d{10}$|^\+994\d{7,12}$)
- card_holder - имя получателя (в точности как написано на карте)
  (string) (<= 255 символа)
  (regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЁРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$)
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/p2p/payout \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
-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": "PAYOUT-KZT-MASTER-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": "5169497700000008",
    "card_holder": "Nurlan Temirbek"
  },
  "payment": {
    "method": "card-p2p",
    "amount": 300000,
    "currency": "KZT",
    "description": "Comment about the payout",
    "extra_param": "example"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "first_name": "Aidar",
    "last_name": "Nurgaliev",
    "country": "KZ",
    "email": "example@mailer.com",
    "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": "PAYOUT-KZT-MASTER-123456"
}

Параметры ответа:

status** - статус обработки выплаты. Список статусов можно посмотреть в разделе "Статусы выплат" (string) (<= 32 символа)
sub_status - под-статус обработки выплаты. Используется только для определенных статусов выплат. Список под-статусов можно посмотреть в разделе "Статусы выплат" (string) (<= 32 символа)
status_description - дополнительная информация по статусу. Используется в случае, если выплата не прошла, либо произошла ошибка (string) (<= 1024 символа)
request_id** - идентификатор платежа, который генерируется в нашей платежной системе (string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции (string) (<= 32 символа)
payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта (string) (<= 255 символа)

Поля помеченные ** являются обязательными

Информация о заявке¶

POST https://api.hh-processing.com/api/v1/payment/p2p/payout/info

Параметры, которые необходимо отправить в теле запроса для получения статуса p2p заявки.

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции. (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: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
-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": "PAYOUT-KZT-MASTER-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": "PAYOUT-KZT-MASTER-123456",
  "payment_info": {
    "amount": 300000,
    "old_amount": 300000,
    "currency": "KZT",
    "method": "card-p2p",
    "type": "payout"
  }
}

Параметры ответа:

status** - статус обработки оплаты. Список статусов можно посмотреть в разделе "Статусы оплат" (string) (<= 32 символа)
sub_status - под-статус обработки платежа. Используется только для определенных статусов оплат. Список под-статусов можно посмотреть в разделе "Статусы оплат" (string) (<= 32 символа)
status_description - дополнительная информация по статусу. Используется в случае, если оплата не прошла, либо произошла ошибка (string) (<= 1024 символа)
request_id** - идентификатор платежа, который генерируется в нашей платежной системе (string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции (string) (<= 32 символа)
payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта (string) (<= 255 символа)
payment_info** - информация по оплате
- amount** - сумма заявки. Сумма указывается в дробных единицах. Подробнее об этом можно прочитать в разделе "Коды валют"; (integer) (1 <= X <= 10000000000000)
- old_amount** - сумма заявки до апелляции. Сумма может измениться, если заявка была создана на одну сумму, но пользователь перевёл другую сумму. В таком случае, в поле amount указывается фактическая сумма, полученная от пользователя (необходимо связаться с тех. поддержкой HH и решить апелляцию по заявке). А в поле old_amount указывается сумма, на которую был создана заявка изначально. Если сумма не менялась, то значения данных полей будут равны; (integer) (1 <= X <= 10000000000000)
- initial_amount - сумма, указанная при создании заявки. Значение данного поля остаётся неизменным (integer) (1 <= X <= 10000000000000)
- currency** - код валюты, в которой исполняется выплата в формате "ISO-4217 alpha-3". Подробнее о кодах валют в разделе "Коды валют" (string) (regex: ^[A-Z]{3}$)
- method** - код метода оплаты. Список методов находится в разделе "Поддерживаемые платежные методы". (string) (<= 32 символа)
- type - тип оплаты, который был выбран при создании платежа. Подробнее о методах оплаты можно прочитать в разделе "Поддерживаемые типы платежей" (string) (<= 32 символа)

Статусы выплат¶

Статус	Под-статус	Описание	Состояние платежа
error		Выплата не была осуществлена из-за ошибки, возникшей при проверке запроса	Промежуточное состояние
processing	new	Проверка запроса перед непосредственной его обработкой	Промежуточное состояние
	requisites	Подбор трейдера, который исполнит выплату	Промежуточное состояние
	payout_process	Исполняется процесс выплаты по указанным реквизитам	Промежуточное состояние
dispute	incorrect_requisites	Трейдер ответил нам тем, что полученные реквизиты выплаты неверные	Промежуточное состояние
	payout_failed	Трейдеру не удалось выполнить выплату на верные реквизиты	Промежуточное состояние
	payout_timeout	Заявка в системе помечается данным статусом в случае, если трейдер не исполнил выплату и время жизни заявки в системе истекло	Промежуточное состояние
decline		Операция отклонена	Финальное состояние
success		Операция выполнена	Финальное состояние

Оповещения (callback):¶

Важно, чтобы в вашей системе была реализована логика проверки оповещений на дубликаты. Мы рекомендуем собирать ключ идемпотентности вам самостоятельно по следующему принципу: {project_id}:{payment_id}:{status}:{sub_status}. Если вы получается повторные опощения, то система должна их игнорировать, чтобы исключить задвойки.

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

У p2p выплат есть 3 типа оповещений:

Информативные - оповещения по промежуточным статусам заявок. Оповещение отправляется, если у заявки меняется статус. URL для отправки оповещений указывается при создании заявки в параметре merchant_callback_url
Успешные - оповещения по успешным заявкам. Оповещение отравляется, если заявка завершена успешно. URL для отправки оповещений указывается при создании заявки в параметре merchant_success_callback_url
Неуспешные - оповещения по неуспешным заявкам. Оповещение отправляется, если в процессе обработки заявки возникла ошибка, либо время жизни заявки истекло. 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": "PAYOUT-KZT-MASTER-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "payout_process",
    "status_description": null
  },
  "payment_info": {
    "amount": 300000,
    "old_amount": 300000,
    "initial_amount": 300000,
    "currency": "KZT",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payout"
  },
  "additional_info": {}
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Успешные оповещения¶

Данное оповещение отправляется в том случае, если заявка приняла успешное финальное состояние - статус success. Пример оповещения показан ниже.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "PAYOUT-KZT-MASTER-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 300000,
    "old_amount": 300000,
    "initial_amount": 300000,
    "currency": "KZT",
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payout"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Неуспешные оповещения¶

Данное оповещение отправляется в том случае, если заявка приняла неуспешное финальное состояние - статус decline. Пример оповещения показан ниже.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "PAYOUT-KZT-MASTER-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 300000,
    "old_amount": 300000,
    "initial_amount": 300000,
    "currency": "KZT",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "payment_system": null,
    "type": "payout"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}