Одностадийный интернет-платеж (ECOM H2H)

Название Код Описание

Тип интеграции

H2H

Платеж через API HighHelp на стороне мерчанта

Валюта

Поддерживаемые валюты:
- KZT
- UZS
- RUB

Депозиты

Доступные методы для оплаты:
- card-ecom

Выплаты

Доступные методы для выплаты:
- card-ecom

Оплата

Схема оплаты

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

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

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

  • аутентификация без участия клиента (frictionless flow): эмитенту достаточно данных, переданных мерчантом при создании платежа; поэтому важно передавать всю доступную информацию о клиенте (ФИО, информация о браузере и т.п.);

  • аутентификация с действиями клиента (challenge flow): клиент проходит дополнительную проверку (код подтверждения, биометрия и т.п.), способ аутентификации определяет эмитент.

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

  1. Создание заявки.
    Мерчант создает заявку на оплату и передает все необходимые данные для проведения платежа.

  2. Получение данных для отображения в платежной инструкции.
    Если эмитент требует 3-D Secure, мерчант получает оповещение со статусом processing:awaiting_3ds_result или processing:awaiting_redirect_result. В теле оповещения содержатся данные для перенаправления клиента. Подробнее см. раздел Перенаправление клиента. Если дополнительная аутентификация не требуется, происходит финализация платежа (пункт 6).

  3. Перенаправление клиента на страницу аутентификации.
    Мерчант перенаправляет клиента на страницу эмитента для прохождения 3-D Secure.

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

  5. Подтверждение оплаты от мерчанта.
    В случае успешной аутентификации мерчант подтверждает платеж в API HighHelp. См. раздел Подтверждение 3DS аутентификации.

  6. Финализация платежа.
    Средства списываются с карты клиента и зачисляются на счет мерчанта. Клиент перенаправляется на страницу мерчанта.

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

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

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

  • general  — информация по заявке.

    • project_id  — идентификатор кассы (проекта), полученный от HighHelp в процессе интеграции.
      (string) (<= 32 символа)

    • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта. Можно использовать любые буквы, цифры и символы в кодировке UTF-8.
      (string) (<= 255 символа)

    • merchant_callback_url — динамический URL для получения оповещений информативного характера (изменения промежуточных статусов заявки и т.д.). Оповещения по финальным статусам приходят на URL, указанные в merchant_success_callback_url и merchant_decline_callback_url.
      (string<https-url>) (<= 2048 символа)

    • merchant_success_callback_url — динамический URL для получения оповещения при успешном завершении операции.
      (string<https-url>) (<= 2048 символа)

    • merchant_decline_callback_url — динамический URL для получения оповещения, если операция не завершилась успешно.
      (string<https-url>) (<= 2048 символа)

  • payment  — информация по платежу.

    • method  — код метода оплаты. Список методов приведен в разделе Платежные методы.
      (string) (<= 32 символа)

    • amount  — сумма платежа в дробных единицах валюты. Подробнее см. раздел Коды валют.
      (integer) (1 <= X <= 10000000000000)

    • currency  — код валюты платежа в формате ISO-4217 alpha-3. Подробнее о кодах валют см. в разделе Коды валют.
      (string) (regex: ^[A-Z]{3}$)

    • description — описание платежа или комментарий. Отображается в личном кабинете мерчанта.
      (string) (<= 255 символа)

    • extra_param — дополнительный параметр для индивидуальной маршрутизации заявки. Настраивается совместно с администратором.
      (string) (regex: ^[A-Za-z0-9_-]{1,16}$)

  • card  — реквизиты карты клиента, с которой списываются средства.

    • pan  — номер карты клиента.
      (string<pan>) (<= 32 символа)

    • year  — год окончания срока действия карты клиента.
      (integer) (2020 <= X <= 2099)

    • month  — месяц окончания срока действия карты клиента.
      (integer) (1 <= X <= 12)

    • card_holder  — имя держателя карты (как на карте).
      (string) (<= 255 символа) (regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЁРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$)

    • cvv — код проверки подлинности карты (CVV/CVC).
      (string) (regex: ^\d{3,4}$)

  • customer  — информация о клиенте.

    • id  — уникальный идентификатор клиента в проекте мерчанта.
      (string) (<= 255 символа)

    • ip_address  — IP-адрес клиента.
      (string<ip-address>) (<= 255 символа)

    • country  — код страны клиента в формате ISO 3166-1 alpha-2. Список поддерживаемых стран см. в разделе Коды стран.
      (string) (regex: ^[A-Z]{2}$)

    • first_name — имя клиента.
      (string) (<= 255 символа)

    • last_name — фамилия клиента.
      (string) (<= 255 символа)

    • language — код языка в формате ISO 639-1, на котором будет показана платежная страница. Если язык не указан, используется язык по умолчанию для страны. Список поддерживаемых языков см. в разделе Коды языков.
      (string) (regex: ^[a-z]{2}$)

    • email — адрес электронной почты клиента.
      (string<email>) (<= 255 символа)

    • browser — название и версия браузера клиента.
      (string) (<= 512 символа)

    • device_type — тип устройства клиента.
      (string) (<= 512 символа)

    • user_agent — идентификационная строка клиентского приложения.
      (string) (<= 1024 символа)

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

Пример запроса:

curl https://api.hh-processing.com/api/v1/payment/ecom/payin \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
  "general": {
    "project_id": "8b03432e-385b-4670-8d06-064591096795",
    "payment_id": "KZT-ECOM-123456",
    "merchant_callback_url": "https://your-domain.com/internal",
    "merchant_success_callback_url": "https://your-domain.com/sucess",
    "merchant_decline_callback_url": "https://your-domain.com/decline"
  },
  "payment": {
    "method": "card-ecom",
    "amount": 150000,
    "currency": "KZT",
    "description": "Comment about the payment",
    "extra_param": "example"
  },
  "card": {
    "pan": "4242242442422424",
    "year": 2029,
    "month": 1,
    "card_holder": "John Snow",
    "cvv": "666"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "first_name": "John",
    "last_name": "Snow",
    "country": "RU",
    "language": "ru",
    "email": "[email protected]",
    "browser": "Google Chrome v15.12",
    "device_type": "Iphone 15 Pro",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
  }
}'

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

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-ECOM-123456"
}

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

Если эмитент требует 3-D Secure, мерчант получает оповещение со статусом processing:awaiting_3ds_result или processing:awaiting_redirect_result. В теле оповещения содержатся данные для аутентификации. Пример такого оповещения приведен в разделе Информативные оповещения по оплате.

Оповещения доставляются с повторными попытками до успешной доставки или до истечения времени жизни заявки. Если оповещение не было получено и заявка остается в промежуточном статусе, можно запросить информацию о заявке через API. См. раздел Информация о заявке (оплата).

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

В оповещении со статусом processing:awaiting_3ds_result в поле asc_info передаются:

  • pa_req — зашифрованные данные с информацией о платеже для 3-D Secure.

  • acs_url — URL страницы эмитента, на которую необходимо перенаправить клиента.

  • md — данные о заявке мерчанта в платежной системе.

После получения данных мерчант формирует HTML-форму и перенаправляет клиента на страницу эмитента для прохождения аутентификации.

<!DOCTYPE html>
<html>
<head>
    <title>3D Secure Authentication</title>
</head>
<body>

<form id="3dsform" action="{{acs_url}}" method="post" enctype="application/x-www-form-urlencoded">
    <input type="hidden" name="PaReq" value="{{pa_req}}"/>
    <input type="hidden" name="TermUrl" value="{{term_url}}"/>
    <input type="hidden" name="MD" value="{{md}}"/>
</form>

<script type="text/javascript">
    setTimeout(function () {
        document.getElementById("3dsform").submit();
    }, 1000);
</script>

</body>
</html>
  • {{acs_url}} — значение параметра acs_url из оповещения.

  • {{pa_req}} — значение параметра pa_req из оповещения.

  • {{term_url}} — ваш URL, на который эмитент отправляет результат аутентификации в формате FormData. Пример: PaRes=ewogISsg2&MD=eyJwdXJ&Action=sendBy. После получения результата необходимо передать данные в API HighHelp. См. раздел Подтверждение 3DS аутентификации.

  • MD — значение параметра md из оповещения.

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

В оповещении со статусом processing:awaiting_redirect_result в поле redirect_info передаются:

  • method — HTTP-метод для запроса.

  • url — URL, на который необходимо перенаправить клиента.

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

После получения оповещения мерчант перенаправляет клиента на указанный URL.

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

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

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

  • general  — информация по заявке.

    • project_id  — идентификатор кассы, полученный от HighHelp в процессе интеграции.
      (string) (<= 32 символа)

    • payment_id  — идентификатор платежа.
      (string) (<= 255 символа)

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

Пример запроса:

curl https://api.hh-processing.com/api/v1/payment/ecom/payin/info \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
  "general": {
    "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
    "payment_id": "KZT-ECOM-123456"
  }
}'

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

{
  "status": "processing",
  "sub_status": "awaiting_3ds_result",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-ECOM-123456",
  "payment_info": {
    "amount": 150000,
    "currency": "KZT",
    "lifetime": 1800,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  },
  "card": {
    "pan": "424224******2424",
    "year": 2029,
    "month": 1,
    "card_holder": "John Snow"
  },
  "customer": {
    "id": "random-customer-id"
  },

  // если статус заявки `processing:awaiting_3ds_result`
  "asc_info": {
    "acs_url": "https://acs-url.com/order/1234",
    "pa_req": "123456789",
    "md": "V2hhdCdzIHVwIGR1ZGU="
  }

  // если статус заявки `processing:awaiting_redirect_result`
  "redirect_info": {
    "method": "POST",
    "url": "https://bank-domain.com/redirect/1234",
    "body": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

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

  • status  — статус обработки оплаты. Список статусов приведен в разделе Статусы оплат.
    (string) (<= 32 символа)

  • sub_status — подстатус обработки платежа. Используется только для отдельных статусов. Список подстатусов приведен в разделе Статусы оплат.
    (string) (<= 32 символа)

  • status_description — дополнительная информация по статусу. Используется, если оплата не прошла или произошла ошибка.
    (string) (<= 1024 символа)

  • request_id  — идентификатор платежа, который генерируется в системе HighHelp.
    (string) (<= 32 символа)

  • project_id  — идентификатор кассы, полученный от HighHelp в процессе интеграции.
    (string) (<= 32 символа)

  • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта.
    (string) (<= 255 символа)

  • payment_info  — информация об оплате.

    • amount  — сумма платежа в дробных единицах валюты. Подробнее см. раздел Коды валют.
      (integer) (1 <= X <= 10000000000000)

    • currency  — код валюты в формате ISO-4217 alpha-3. Подробнее о кодах валют см. в разделе Коды валют.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime  — время жизни заявки в секундах.
      (integer) (X <= 2^32)

    • expiration_date — время, до которого заявка действительна, в формате Unix Timestamp (UTC).
      (integer) (X <= 2^32)

    • created_date  — время создания заявки в формате Unix Timestamp (UTC).
      (integer) (X <= 2^32)

    • method  — код метода оплаты. Список методов приведен в разделе "Платежные методы".
      (string) (<= 32 символа)

    • type  — тип оплаты. Подробнее о типах см. в разделе Поддерживаемые типы платежей.
      (string) (<= 32 символа)

  • card  — информация о карте, с которой производится оплата.

    • pan  — номер карты отправителя (маскированный).
      (string<pan>) (<= 32 символа)

    • year  — год окончания срока действия карты.
      (integer) (2020 <= X <= 2099)

    • month  — месяц окончания срока действия карты.
      (integer) (1 <= X <= 12)

    • card_holder  — имя держателя карты.
      (string) (<= 255 символа) (regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЁРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$)

    • cvv — код проверки подлинности карты отправителя.
      (string) (<= 3 символа)

  • customer  — информация об отправителе.

    • id  — уникальный идентификатор пользователя в проекте мерчанта.
      (string) (<= 255 символа)

  • asc_info — информация для 3-D Secure.

    • pa_req  — зашифрованные данные о платеже для 3-D Secure.
      (string) (<= 2048 символа)

    • acs_url  — URL-страницы эмитента для 3-D Secure.
      (string<https-url>) (<= 4096 символа)

    • md  — данные мерчанта в платежной системе для 3-D Secure.
      (string) (<= 4096 символа)

Поле 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  — идентификатор кассы, полученный от HighHelp в процессе интеграции.
      (string) (<= 32 символа)

    • payment_id  — идентификатор платежа, для которого выполняется подтверждение.
      (string) (<= 255 символа)

  • pares  — информация о результате 3-D Secure.

    • data  — данные, полученные от эмитента после аутентификации.
      (string) (<= 2^16 символа)

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

Пример запроса:

curl https://api.hh-processing.com/api/v1/payment/ecom/payin/confirm-3ds-result \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
  "general": {
    "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
    "payment_id": "KZT-ECOM-123456"
  },
  "pares": {
  	"data": "base64string"
  }
}'

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

{
  "status": "processing",
  "sub_status": "awaiting_3ds_result",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-ECOM-123456"
}

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

  • status  — статус обработки оплаты. Список статусов приведен в разделе Статусы оплат.
    (string) (<= 32 символа)

  • sub_status — подстатус обработки платежа. Используется только для отдельных статусов. Список подстатусов приведен в разделе Статусы оплат.
    (string) (<= 32 символа)

  • status_description — дополнительная информация по статусу. Используется, если оплата не прошла или произошла ошибка.
    (string) (<= 1024 символа)

  • request_id  — идентификатор платежа, который генерируется в системе HighHelp.
    (string) (<= 32 символа)

  • project_id  — идентификатор кассы, полученный от HighHelp в процессе интеграции.
    (string) (<= 32 символа)

  • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта.
    (string) (<= 255 символа)

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

Типы операций и статусов описаны в разделе Типы операций и статусы.
Коды статусов и возможные значения status и sub_status приведены в разделе Коды статусов.

Статус Подстатус Описание Состояние платежа

error

Платеж не был выполнен из-за ошибки, возникшей при проверке запроса

Промежуточное состояние

processing

new

Проверяется корректность запроса перед началом обработки

Промежуточное состояние

requisites

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

Промежуточное состояние

awaiting_confirm

Ожидается подтверждение оплаты от клиента, так как реквизиты уже предоставлены

Промежуточное состояние

paid

Клиент подтвердил, что отправил сумму на выданные реквизиты

Промежуточное состояние

dispute

no_payment

Клиент не выполнил оплату по заявке за время ее жизни (lifetime)

Промежуточное состояние

different_amount

Клиент отправил сумму, отличающуюся от указанной в заявке

Промежуточное состояние

confirm_timeout

Время жизни заявки истекло, но клиент позднее подтвердил оплату и предоставил чек

Промежуточное состояние

decline

Платеж отклонен

Финальное состояние

success

Платеж выполнен

Финальное состояние

Оповещения

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

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

Предусмотрены три типа оповещений:

  • Информативные — оповещения по промежуточным статусам заявок. Оповещение отправляется при изменении статуса. URL задается в параметре merchant_callback_url при создании заявки.

  • Успешные — оповещения по заявкам, завершившимся в статусе success. URL задается в параметре merchant_success_callback_url.

  • Неуспешные — оповещения по заявкам, завершившимся в статусе decline или с ошибкой. URL задается в параметре merchant_decline_callback_url.

Информативные оповещения

Пример оповещения со статусами processing:awaiting_3ds_result и processing:awaiting_redirect_result:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_3ds_result",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "KZT",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  },
  "card": {
    "pan": "427212******1234",
    "year": 2029,
    "month": 1,
    "card_holder": "John Snow"
  },

  // если статус заявки `processing:awaiting_3ds_result`
  "asc_info": {
    "pa_req": "123456789",
    "acs_url": "https://acs-url.com/order/1234",
    "md": "V2hhdCdzIHVwIGR1ZGU="
  }

  // если статус заявки `processing:awaiting_redirect_result`
  "redirect_info": {
      "method": "POST",
      "url": "https://bank-domain.com/redirect/1234",
      "body": {
        "key1": "value1",
        "key2": "value2"
      }
  }
}
  • Поле 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  — идентификатор кассы, полученный от HighHelp в процессе интеграции.
      (string) (<= 32 символа)

    • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта. Можно использовать любые буквы, цифры и символы в кодировке UTF-8.
      (string) (<= 255 символа)

    • merchant_callback_url — динамический URL для получения оповещений информативного характера (изменения промежуточных статусов заявки и т.д.). Оповещения по финальным статусам заявок отправляются на URL, указанные в merchant_success_callback_url и merchant_decline_callback_url.
      (string<https-url>) (<= 2048 символа)

    • merchant_success_callback_url — динамический URL для получения оповещения при успешном завершении операции.
      (string<https-url>) (<= 2048 символа)

    • merchant_decline_callback_url — динамический URL для получения оповещения, если операция не завершилась успешно.
      (string<https-url>) (<= 2048 символа)

  • receiver  — данные получателя выплаты.

    • pan  — номер карты получателя.
      (string<pan>) (<= 32 символа)

    • year — год окончания срока действия карты получателя. Обязательное поле для валюты UZS.
      (integer) (2020 <= X <= 2099)

    • month — месяц окончания срока действия карты получателя. Обязательное поле для валюты UZS.
      (integer) (1 <= X <= 12)

  • payment  — информация о выплате.

    • method  — код метода выплаты. Список методов приведен в разделе Платежные методы.
      (string) (<= 32 символа)

    • amount  — сумма выплаты в дробных единицах валюты. Подробнее см. раздел Коды валют.
      (integer) (1 <= X <= 10000000000000)

    • currency  — валюта выплаты в формате ISO-4217 alpha-3. Подробнее о кодах валют см. в разделе Коды валют.
      (string) (regex: ^[A-Z]{3}$)

    • description — описание выплаты или комментарий. Отображается в личном кабинете мерчанта.
      (string) (<= 255 символа)

    • extra_param — дополнительный параметр для индивидуальной маршрутизации заявки. Настраивается совместно с администратором.
      (string) (regex: ^[A-Za-z0-9_-]{1,16}$)

  • customer  — информация об отправителе.

    • id  — уникальный идентификатор пользователя в проекте мерчанта.
      (string) (<= 255 символа)

    • ip_address  — IP-адрес пользователя.
      (string<ip-address>) (<= 255 символа)

    • first_name — имя клиента, получающего выплату.
      (string) (<= 255 символа)

    • last_name — фамилия клиента, получающего выплату.
      (string) (<= 255 символа)

    • country  — код страны пользователя в формате ISO 3166-1 alpha-2.
      (string) (regex: ^[A-Z]{2}$)

    • email — адрес электронной почты пользователя.
      (string<email>) (<= 255 символа)

    • browser — название и версия браузера пользователя.
      (string) (<= 512 символа)

    • device_type — тип устройства пользователя.
      (string) (<= 512 символа)

    • user_agent — идентификационная строка клиентского приложения.
      (string) (<= 1024 символа)

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

Пример запроса:

curl https://api.hh-processing.com/api/v1/payment/ecom/payout \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
  "general": {
    "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
    "payment_id": "KZT-ECOM-123456",
    "merchant_callback_url": "https://your-domain.com/internal",
    "merchant_success_callback_url": "https://your-domain.com/sucess",
    "merchant_decline_callback_url": "https://your-domain.com/decline"
  },
  "receiver": {
    "pan": "4242242442422424"
  },
  "payment": {
    "method": "card-ecom",
    "amount": 150000,
    "currency": "KZT",
    "description": "Comment about the payout",
    "extra_param": "example"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "first_name": "John",
    "last_name": "Snow",
    "country": "RU",
    "email": "[email protected]",
    "browser": "Google Chrome v15.12",
    "device_type": "Iphone 15 Pro",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
  }
}'

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

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-ECOM-123456"
}

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

  • status  — статус обработки выплаты. Список статусов приведен в разделе Статусы выплат.
    (string) (<= 32 символа)

  • sub_status — подстатус обработки выплаты. Используется только для отдельных статусов. Список подстатусов приведен в разделе Статусы выплат.
    (string) (<= 32 символа)

  • status_description — дополнительная информация по статусу. Используется, если выплата не прошла или произошла ошибка.
    (string) (<= 1024 символа)

  • request_id  — идентификатор платежа, который генерируется в системе HighHelp.
    (string) (<= 32 символа)

  • project_id  — идентификатор кассы, полученный от HighHelp в процессе интеграции.
    (string) (<= 32 символа)

  • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта.
    (string) (<= 255 символа)

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

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

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

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

  • general  — информация по заявке.

    • project_id  — идентификатор кассы, полученный от HighHelp в процессе интеграции.
      (string) (<= 32 символа)

    • payment_id  — идентификатор платежа.
      (string) (<= 255 символа)

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

Пример запроса:

curl https://api.hh-processing.com/api/v1/payment/ecom/payout/info \
-X POST \
-H 'x-access-timestamp: 1706182847' \
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
-H 'content-type: application/json' \
-d '{
  "general": {
    "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
    "payment_id": "KZT-ECOM-123456"
  }
}'

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

{
  "status": "processing",
  "sub_status": "payout_process",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-ECOM-123456",
  "payment_info": {
    "amount": 10000,
    "currency": "KZT",
    "method": "card-ecom",
    "type": "payout"
  }
}

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

  • status  — статус обработки выплаты. Список статусов приведен в разделе Статусы выплат.
    (string) (<= 32 символа)

  • sub_status — подстатус обработки выплаты. Используется только для отдельных статусов. Список подстатусов приведен в разделе Статусы выплат.
    (string) (<= 32 символа)

  • status_description — дополнительная информация по статусу. Используется, если выплата не прошла или произошла ошибка.
    (string) (<= 1024 символа)

  • request_id  — идентификатор платежа, который генерируется в системе HighHelp.
    (string) (<= 32 символа)

  • project_id  — идентификатор кассы, полученный от HighHelp в процессе интеграции.
    (string) (<= 32 символа)

  • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта.
    (string) (<= 255 символа)

  • payment_info  — информация о выплате.

    • amount  — сумма заявки в дробных единицах валюты. Подробнее см. раздел Коды валют.
      (integer) (1 <= X <= 10000000000000)

    • currency  — код валюты, в которой выполняется выплата, в формате "ISO-4217 alpha-3". Подробнее о кодах валют см. в разделе Коды валют.
      (string) (regex: ^[A-Z]{3}$)

    • method  — код метода выплаты. Список методов приведен в разделе Платежные методы.
      (string) (<= 32 символа)

    • type — тип оплаты, который выбран при создании платежа. Подробнее о типах см. в разделе Поддерживаемые типы платежей.
      (string) (<= 32 символа)

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

Статус Подстатус Описание Состояние платежа

error

Выплата не была выполнена из-за ошибки при проверке запроса.

Промежуточное состояние.

processing

new

Проверка запроса перед обработкой.

Промежуточное состояние.

requisites

Подбор трейдера, который исполнит выплату.

Промежуточное состояние.

payout_process

Выполняется процесс выплаты по указанным реквизитам.

Промежуточное состояние.

dispute

incorrect_requisites

Указаны неверные реквизиты для выплаты.

Промежуточное состояние.

payout_failed

Не удалось выполнить выплату на указанные реквизиты.

Промежуточное состояние.

payout_timeout

Выплата не была исполнена до истечения времени жизни заявки.

Промежуточное состояние.

decline

Операция отклонена.

Финальное состояние.

success

Операция выполнена.

Финальное состояние.

Оповещения

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

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

Предусмотрены три типа оповещений:

  • Информативные — оповещения по промежуточным статусам заявок. Оповещение отправляется при изменении статуса. URL задается в параметре merchant_callback_url при создании заявки.

  • Успешные — оповещения по заявкам, завершившимся в статусе success. URL задается в параметре merchant_success_callback_url.

  • Неуспешные — оповещения по заявкам, завершившимся в статусе decline или с ошибкой. URL задается в параметре merchant_decline_callback_url.

Информативные оповещения

Пример оповещения со статусом processing:payout_process:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "payout_process",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "currency": "KZT",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payout"
  },
  "additional_info": {}
}

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

Оповещение отправляется при успешном финальном статусе success.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "KZT",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payout"
  }
}

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

Оповещение отправляется при неуспешном финальном статусе decline.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "KZT",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payout"
  }
}