Банковские переводы E-commerce¶

Название	Код	Описание
Тип интеграции	`H2H`	Платеж на вашей форме оплаты
Валюта		Поддерживаемые валюты: - `KZT` - `UZS` - `RUB`
Депозиты	✅	Доступные методы для оплаты: - `card-ecom`
Выплаты	✅	Доступные методы для выплаты: - `card-ecom`

Оплата¶

Схема оплаты¶

Для проведения card-ecom платежа в одну стадию, клиенту необходимо использовать один из следующих методов передачи реквизитов:

Передача реквизитов карты в явном виде.
Другие методы скоро станут доступны. =)

Аутентификации 3DS может потребоваться в зависимости от эмитента карты. Решение о проведении аутентификации принимает сам эмитент. Со стороны мерчанта выбрать предпочтительный метод аутентификации невозможно.

3DS аутентификция может выполниться одном из следующих вариантах:

Действия со стороны клиента не требуются (frictionless flow). В этом случае эмитенту достаточно тех данных, которые были переданы мерчантом при создании платежа. Поэтому крайне важно передавать всю доступную информацию о клиента при создании платежа (ФИО, информация о браузере и т.д.).
Требуются дополнительные действия со стороны клиента (challenge flow). В этом случае клиенту необходимо пройти дополнительную аутентификацию. Эмитент карты определяет какой метод аутентификации использовать (ввод кода подтверждения, биометрическая аутентификация и т.д.).

Процесс оплаты¶

Создание заявки
Мерчант создаёт заявку на оплату. В заявке указываются все необходимые данные для проведения платежа.
Получение данных для отображения в платежной инструкции
Если эмитент требует 3DS аутентификацию, мерчант получит колбэк со статусом processing:awaiting_3ds_result/processing:awaiting_redirect_result. В теле ответа будут содержаться данные для перенаправления клиента. Подробнее можно прочитать в данном разделе. Если дополнительная аутентификация не требуется, происходит финализация платежа (пункт 6)
Перенаправление клиента на страницу аутентификации
Согласно полученным данным, мерчант перенаправляет клиента на страницу эмитента для прохождения 3DS аутентификации. Клиенту будет необходимо ввести код подтверждения, либо пройти другого рода аутентификацию.
Подтверждение оплаты от эмитента
В случае успешной аутентификации, эмитент отправит данные о результате. Эти данные необходимо отправить в API провайдера (HighHelp).
Подтверждение оплаты от мерчанта
В случае успешной аутентификации, мерчанту необходимо подтвердить платеж в API провайдера (HighHelp).
Финализация платежа
Платеж завершается, средства списываются с карты клиента и зачисляются на счёт мерчанта. Клиент перенаправляется на страницу мерчанта.

Ниже прикреплена схема изменения статусов заявки от создания до завершения.

Схема изменений статусов заявки

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

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

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

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 символа)
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 - 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"
}

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

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

Перенаправление клиента¶

В случае, если эмитент требует 3DS аутентификацию, мерчант получит колбэк со статусом processing:awaiting_3ds_result/processing:awaiting_redirect_result. В теле колбэка будет создержаться информация для аутентификации, пример такого колбэка можно посмотреть тут.

Механизм колбэков устроен таким образом, что если колбэк доставить не удалось, то он будет переотправляться до тех пор, пока не будет успешно доставлен, либо срок жизни заявки не истечёт.

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

Аутентификация 3‑D Secure¶

Давайте на примере разберем какие действия необходимо предпринять при получении колбэка со статусом processing:awaiting_3ds_result.

В теле колбэка в поле asc_info будут содержаться следующие данные:

pa_req — зашифрованные данные с информацией о платеже. Эти данные следует отправить банку эмитенту при формировании формы.
acs_url — URL эмитента, на который необходимо перенаправить пользователя.
md — данные о заявке мерчанта в платежной системе.

После того как вы получили данные для аутентификации, необходимо перенаправить клиента на страницу эмитента для прохождения 3DS аутентификации. Для этого можно использовать пример формы приведенной ниже.

<!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 провайдера. Подробнее об этом можно прочитать тут.
MD: В этом поле указывается параметр из колбека md

Аутентификация путем перенаправления клиента¶

Давайте на примере разберем какие действия необходимо предпринять при получении колбэка со статусом processing:awaiting_redirect_result.

В теле колбэка в поле redirect_info будут содержаться следующие данные:

method — метод отправки запроса.
url — URL для перенаправления клиента.
body — данные для отправки на указанный URL (может быть пустым).

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

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

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

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

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции.
  (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** - идентификатор платежа, который генерируется в нашей платежной системе
(string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции
(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 - информация для 3DS
- pa_req** - зашифрованные данные с информацией о платеже для 3DS. (string) (<= 2048 символа)
- acs_url** - URL страницы эмитента для 3DS (string<https-url>) (<= 4096 символа)
- md** - данные мерчанта в платежной системе для 3DS (string) (<= 4096 символа)

asc_info - поле может быть пустым (т.е null), если заявка находится в статусе, отличном от processing:awaiting_3ds_result.

Подтверждение 3DS аутентификации¶

POST https://api.hh-processing.com/api/v1/payment/ecom/payin/confirm-3ds-result

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

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции.
  (string) (<= 32 символа)
- payment_id** - идентификатор платежа, для которого необходимо выполнить подтверждение.
  (string) (<= 255 символа)
pares** - информация о PARes
- data** - данные, полученные от эмитента после 3DS аутентификации.
  (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** - идентификатор платежа, который генерируется в нашей платежной системе
(string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции
(string) (<= 32 символа)
payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта
(string) (<= 255 символа)

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

Статус	Под-статус	Описание	Состояние платежа
error		Платеж не был осуществлен из-за ошибки, возникшей при проверке запроса	Промежуточное состояние
processing	new	Проверка запроса перед непосредственной его обработкой	Промежуточное состояние
	requisites	Платеж прошел проверка и взят в работу	Промежуточное состояние
	awaiting_3ds_result	Ожидание подтверждения клиента 3DS аутентификации	Промежуточное состояние
	awaiting_redirect_result	Ожидание завершения аутентификации клиента у эмитента	Промежуточное состояние
decline		Платеж отклонен	Финальное состояние
success		Платеж проведен	Финальное состояние

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

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

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

Информативные - оповещения по промежуточным статусам заявок. Оповещение отправляется, если у заявки меняется статус. URL для отправки оповещений указывается при создании заявки в параметре merchant_callback_url
Успешные - оповещения по успешным заявкам. Оповещение отравляется, если заявка завершена успешно. URL для отправки оповещений указывается при создании заявки в параметре merchant_success_callback_url
Неуспешные - оповещения по неуспешным заявкам. Оповещение отправляется, если в процессе обработки заявки возникла ошибка, либо время жизни заявки истекло. 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"
      }
  }
}

asc_info - поле может быть пустым (т.е null), если заявка находится в статусе, отличном от processing:awaiting_3ds_result

redirect_info - поле может быть пустым (т.е null), если заявка находится в статусе, отличном от processing:awaiting_redirect_result

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

Данное оповещение отправляется в том случае, если заявка приняла успешное финальное состояние - статус 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** - идентификатор кассы, полученный от 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** - номер карты получателя.
  (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** - идентификатор платежа, который генерируется в нашей платежной системе
(string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции
(string) (<= 32 символа)
payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта
(string) (<= 255 символа)

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

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

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

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

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции.
  (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** - идентификатор платежа, который генерируется в нашей платежной системе
(string) (<= 32 символа)
project_id** - идентификатор кассы, полученный от HH в процессе интеграции
(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 символа)

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

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

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

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

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

У ecom выплат есть 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": "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"
  }
}