Интернет-платежи через виджет (ECOM, H2C)

В этом разделе описан сценарий приема интернет-платежей через виджет HighHelp (тип интеграции H2C) с использованием метода /api/v1/widget/payin.

Параметры продукта

Параметр Код Описание

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

H2C

Платеж выполняется на платежной странице HighHelp (виджет).

Валюта

Поддерживаемые валюты:
KZT, UZS, RUB.
Полный список валют см. в разделе Коды валют.

Депозиты

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

Выплаты

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

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

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

В теле запроса передаются следующие параметры.

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

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

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

    • merchant_callback_url — 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 — URL, на который пользователь будет перенаправлен с платежной страницы после завершения платежа. Если параметр не передан, используется URL, заданный в настройках кассы.
      (string<https-url>) (<= 2048 символа)

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

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

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

    • lifetime — время жизни заявки в секундах. По умолчанию 600 секунд.
      (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/success",
      "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",
      "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  — статус обработки оплаты. Список статусов см. в разделах Статусы оплат (payin) и Коды статусов.
    (string) (<= 32 символа)

  • sub_status — подстатус обработки платежа.
    (string) (<= 32 символа)

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

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

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

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

  • integration — блок с параметрами для интеграции.

    • form_url  — URL платежной страницы, на которую необходимо перенаправить пользователя.
      (string<https-url>) (<= 255 символа)

    • redirect_url — URL для редиректа пользователя после завершения платежа.
      (string<https-url>) (<= 2048 символа)

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

Получение информации о заявке

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

Запрос:

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

    • project_id  — идентификатор кассы.
      (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  — идентификатор заявки во внутренней системе HighHelp.
    (string) (<= 32 символа)

  • project_id  — идентификатор кассы.
    (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 — метод оплаты, выбранный при обработке платежа. Список методов см. в разделе Методы оплаты (H2H).
      (string) (<= 32 символа)

    • widget_method — метод платежной страницы, выбранный во время оплаты.
      (string) (<= 32 символа)

    • type — тип платежа. Значения описаны в разделе Типы платежей.
      (string) (<= 32 символа)

  • integration — дополнительные данные интеграции.

    • form_url  — URL платежной страницы, по которому доступна заявка.
      (string<https-url>) (<= 255 символа)

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

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

Статусы и переходы для ecom-заявок совпадают с жизненным циклом оплат по H2H. См. раздел Типы операций и статусы заявок (payin).
Полный перечень кодов статусов и описаний приведен в разделе Коды статусов.

Оповещения о статусе

Общие сведения

Оповещения отправляются на URL-адреса, указанные при создании заявки:

  • merchant_callback_url — информативные оповещения по промежуточным статусам.

  • merchant_success_callback_url — оповещения об успешных платежах.

  • merchant_decline_callback_url — оповещения о неуспешных платежах.

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

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

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

Информативные оповещения по интернет-платежам в текущей версии не отправляются.

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

Оповещение отправляется, если заявка получила финальный статус 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"
  }
}