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

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

Оплата¶

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

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

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

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 символа)
- redirect_url - cсылка для редиректа пользователя с формы оплаты после завершения платежа. Если параметр не будет передан, то будет успользован url указанный при создании кассы.
  (string<https-url>) (<= 2048 символа)
payment** - информация по платежу
- amount** - сумма, которую намеревается оплатить пользователь. Сумму необходимо указывать в дробных единицах. Подробнее об этом можно прочитать в разделе "Коды валют"
  (integer) (1 <= X <= 10000000000000)
- currency** - код валюты в которой оплачивает пользователь в формате "ISO-4217 alpha-3". Подробнее о кодах валют в разделе "Коды валют"
  (string) (regex: ^[A-Z]{3}$)
- lifetime - время жизни заявки в секундах. Максимальное время жизни - 10 мин. Если время не указано, то устанавливается значение по умолчанию - 10 мин.
  (integer) (300 <= X <= 600)
- description - описание платежа или комментарий. Данные будут отображены в личном кабинете мерчанта.
  (string) (<= 255 символа)
- extra_param - дополнительный параметр, используемый для индивидуальной маршрутизации заявки. Настраивается совместно с администратором.
  (string) (regex: ^[A-Za-z0-9_-]{1,16}$)
- widget_method - метод платежной страницы, который будет пред-выбран в виджете. Подробнее о методах платежной страницы можно прочитать в разделе "Поддерживаемые методы платежной страницы"
  (string) (<= 32 символа)
customer** - информация об отправителе
- id** - уникальный идентификатор пользователя (отправителя) в проекте мерчанта
  (string) (<= 255 символа)
- ip_address** - ip адрес отправителя
  (string<ip-address>) (<= 255 символа)
- country** - код страны пользователя в формате "ISO 3166-1 alpha-2". Список поддерживаемых стран можете увидеть в разделе "Коды стран".
  (string) (regex: ^[A-Z]{2}$)
- language - код языка в формате "ISO 639-1", который будет предвыбран на платежной странице. Если язык не указан, то будет выбран язык по умолчанию для страны. Список поддерживаемых языков можете увидеть в разделе "Коды языков".
  (string) (regex: ^[a-z]{2}$)
- email - имейл адрес отправителя
  (string<email>) (<= 255 символа)

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

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

curl https://api.hh-processing.com/api/v1/widget/payin \
-X POST \
-H 'x-access-timestamp: 1706182847' \  
-H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \  
-H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \  
-H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \  
-H 'content-type: application/json' \
-d '{
  "general": {
    "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
    "payment_id": "KZT-CARD-123456",
    "merchant_callback_url": "https://your-callback-domain.com/internal",
    "merchant_success_callback_url": "https://your-callback-domain.com/sucess",
    "merchant_decline_callback_url": "https://your-callback-domain.com/decline",
    "redirect_url": "https://your-web-site-url.com/order/page"
  },
  "payment": {
    "amount": 1500000,
    "currency": "KZT",
    "lifetime": 600,
    "description": "Comment about the payment",
    "extra_param": "example",
    "widget_method": "payin-ecom-card"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "country": "KZ",
    "language": "kk",
    "customer_type": "ftd",
    "email": "[email protected]"
  }
}'

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

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-CARD-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

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

status** - статус обработки оплаты. Список статусов можно посмотреть в разделе "Статусы оплат"
(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/widget/payin/info

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

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

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

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

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

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

{
  "status": "processing",
  "sub_status": "awaiting_confirm",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-CARD-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 12000,
    "currency": "KZT",
    "lifetime": 600,
    "expiration_date": 1721647251,
    "method": "card-ecom",
    "widget_method": "payin-ecom-card",
    "type": "payin"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

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

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

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

Статусы оплат для ecom заявок смотрите в этом разделе

Оповещения (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

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

Этот тип оповещений для ecom платежей, на данный момент не отправляется.

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

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

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

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

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

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