Казахстан (ECOM) — Оплата

В этом разделе описан сценарий оплаты через мобильную коммерцию для Казахстана (KZ, KZT) при H2C-интеграции через платежный виджет HighHelp. При оплате пользователь получает от сервиса провайдера сообщение с кодом, который он использует для подтверждения оплаты.

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

Название	Код	Описание
Тип интеграции	`H2C`	Платеж через платежный виджет HighHelp
Валюта	`KZT`	Казахстанский тенге
Страна	`KZ`	Республика Казахстан
Депозиты	✅	Доступные методы для оплаты: - `payin-ecom-mobile`

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

H2C

Платеж через платежный виджет HighHelp

Валюта

KZT

Казахстанский тенге

Страна

KZ

Республика Казахстан

Депозиты

✅

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

Поддерживаемые операторы связи

Оператор связи Код

Оператор связи	Код
Beeline	`BEELINE`
Tele2	`TELE2`
Altel	`ALTEL`
Kcell	`KCELL`
Activ	`ACTIV`

Beeline

BEELINE

Tele2

TELE2

Altel

ALTEL

Kcell

KCELL

Activ

ACTIV

Сценарий оплаты

sequenceDiagram
    autonumber

    participant U as Пользователь
    participant M as Система мерчанта
    participant HH as Платежная страница HighHelp
    participant O as Оператор связи

    U->>M: Инициирует оплату
    M->>HH: Запрос на открытие платежной страницы
    HH-->>U: Отображение платежной страницы
    U->>HH: Выбор оператора связи и ввод номера телефона
    HH->>O: Запрос OTP-кода
    O-->>U: Отправка OTP-кода
    HH-->>U: Форма ввода OTP-кода
    U->>HH: Ввод OTP-кода
    HH->>O: Отправка OTP-кода на проверку
    O-->>HH: Результат проверки OTP-кода
    loop Повторный запрос OTP-кода
        U->>HH: Повторный запрос OTP-кода
        HH->>O: Запрос нового OTP-кода
        O-->>HH: Новый OTP-код запрошен
        O-->>U: Отправка нового OTP-кода
        U->>HH: Повторный ввод OTP-кода
        HH->>O: Повторная отправка OTP-кода на проверку
        O-->>HH: Результат повторной проверки OTP-кода
    end
    HH-->>U: Отображение результата

Описание переходов

Пользователь инициирует оплату в системе мерчанта.
Система мерчанта отправляет запрос на открытие платежной страницы в HighHelp.
Платежная страница HighHelp отображается пользователю.
Пользователь выбирает оператора связи и вводит номер телефона.
Платежная страница запрашивает OTP-код у оператора связи.
Оператор связи отправляет пользователю OTP-код.
Платежная страница HighHelp отображает пользователю форму ввода OTP-кода.
Пользователь вводит OTP-код на платежной странице.
Платежная страница отправляет OTP-код на проверку.
Платежная страница получает результат проверки OTP-кода.
Пользователь выполняет повторный запрос OTP-кода после наступления времени повторного запроса.
Платежная страница запрашивает у оператора связи новый OTP-код.
Оператор связи подтверждает, что новый OTP-код запрошен.
Оператор связи отправляет пользователю новый OTP-код.
Пользователь повторно вводит OTP-код на платежной странице.
Платежная страница повторно отправляет OTP-код на проверку.
Платежная страница получает результат повторной проверки OTP-кода.
Платежная страница отображает пользователю результат.

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

Параметры тела запроса при создании заявки.

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 — сумма платежа в дробных единицах валюты. Подробнее см. Коды валют.
  (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 — дополнительный параметр для индивидуальной маршрутизации заявки. Значение согласуется с HighHelp.
  (string) (regex: ^[A-Za-z0-9_-]{1,16}$)
- widget_method — код метода виджета, который будет предвыбран на платежной странице. Для этого сценария используется payin-ecom-mobile. Подробнее см. Методы виджета (H2C).
  (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: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
  -H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
  -H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-MOBILE-ECOM-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-mobile"
    },
    "customer": {
      "id": "cus_12345",
      "ip_address": "192.0.2.1",
      "country": "KZ",
      "language": "kk",
      "email": "[email protected]"
    }
  }'

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

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539fcb34ff5a3e286625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-MOBILE-ECOM-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 символа)

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

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

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

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: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
  -H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
  -H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-MOBILE-ECOM-123456"
    }
  }'

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

{
  "status": "processing",
  "sub_status": "awaiting_3ds_result",
  "status_description": null,
  "request_id": "16a10539fcb34ff5a3e286625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-MOBILE-ECOM-123456",
  "payment_info": {
    "amount": 1500000,
    "old_amount": 1500000,
    "initial_amount": 1500000,
    "currency": "KZT",
    "lifetime": 600,
    "expiration_date": 1721647251,
    "method": "mobile-ecom",
    "widget_method": "payin-ecom-mobile",
    "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 — код метода оплаты. Для этого сценария используется значение mobile-ecom.
  (string) (<= 32 символа)
- widget_method — код метода платежной страницы. Для этого сценария используется значение payin-ecom-mobile.
  (string) (<= 32 символа)
- type — тип платежа. Значения описаны в разделе Типы платежей.
  (string) (<= 32 символа)
integration — дополнительные данные интеграции.
- form_url — URL платежной страницы, по которому доступна заявка.
  (string<https-url>) (<= 255 символа)
- redirect_url — URL для редиректа с платежной страницы после завершения платежа.
  (string<https-url>) (<= 2048 символа)

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

Метод подтверждает оплату по заявке, созданной через виджет.

Запрос:

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

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

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

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

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

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539fcb34ff5a3e286625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-MOBILE-ECOM-123456"
}

Отмена оплаты

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

Запрос:

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

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

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

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

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

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539fcb34ff5a3e286625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-MOBILE-ECOM-123456"
}

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

Полный перечень статусов и подстатусов приведен в разделе Коды статусов.

Схема переходов статусов

%%{init: {"flowchart": {"curve": "stepBefore"}} }%%
flowchart LR
    R["processing:<br/>requisites"]
    A["processing:<br/>awaiting_3ds_result"]
    S["processing:<br/>sent_verification"]
    P["processing:<br/>paid"]
    I["processing:<br/>invalid_verification"]
    OK["success"]
    NO["decline"]

    R -->|OTP запрошен| A
    A -->|OTP отправлен<br/>на проверку| S
    S -->|OTP корректный| P
    S -->|OTP неверный| I
    I -->|Повтор OTP| S
    I -->|Лимит 3<br/>неверных OTP| NO
    P -->|Успешная<br/>финализация| OK
    P -->|Неуспешная<br/>финализация| NO
    A -.->|Прямая<br/>финализация| OK
    A -.->|Прямой<br/>отказ| NO

Описание переходов

processing:requisites → processing:awaiting_3ds_result — OTP запрошен у пользователя.
processing:awaiting_3ds_result → processing:sent_verification — OTP отправлен на проверку.
processing:sent_verification → processing:paid — получено подтверждение корректности OTP.
processing:sent_verification → processing:invalid_verification — получен неверный OTP.
processing:invalid_verification → processing:sent_verification — пользователь повторно вводит OTP-код, и заявка возвращается к проверке кода.
processing:invalid_verification → decline — после трех неверных попыток ввода OTP-кода заявка завершается отказом.
processing:paid → success — оплата успешно финализируется.
processing:paid → decline — оплата финализируется отказом.
processing:awaiting_3ds_result → success — оплата успешно завершается без отдельного промежуточного статуса processing:paid.
processing:awaiting_3ds_result → decline — оплата завершается отказом без отдельного промежуточного статуса processing:paid.

Правила обработки OTP

Пользователь вводит OTP после перехода заявки в processing:awaiting_3ds_result.
После отправки OTP заявка переходит в processing:sent_verification.
При корректном OTP заявка либо переходит в processing:paid с последующей финализацией, либо сразу финализируется в success или decline.
При неверном OTP заявка переходит в processing:invalid_verification. После этого пользователь может повторно ввести OTP-код на платежной странице. После трех неверных попыток ввода OTP-кода заявка переходит в decline.
После окончания времени действия текущего OTP пользователь может запросить новый OTP-код.
Время до повторного запроса OTP-кода не фиксировано. Оно определяется платежным сценарием на стороне провайдера и отображается пользователю на платежной странице.
Пользователь может запросить новый OTP-код до трех раз. После третьего повторного запроса заявка переходит в decline.
После повторного запроса нового OTP-кода сценарий продолжается в ожидании нового OTP.

Статус Подстатус Описание Действия мерчанта

Статус	Подстатус	Описание	Действия мерчанта
`processing`	`new`	Заявка создана и принята в обработку.	Дождитесь перехода в следующий статус.
	`requisites`	Платежная страница приняла номер телефона и запустила сценарий оплаты.	Дождитесь перехода в следующий статус.
	`awaiting_3ds_result`	OTP запрошен у пользователя.	Ожидайте информативное оповещение на `merchant_callback_url`.
	`sent_verification`	OTP передан на проверку.	Дождитесь следующего информативного или финального оповещения.
	`invalid_verification`	Пользователь передал неверный OTP. После трех неверных попыток ввода OTP-кода заявка переходит в `decline`.	Дождитесь следующего информативного или финального оповещения.
	`paid`	Оператор подвердил корректность OTP. Ожидается финализация оплаты.	Дождитесь следующего информативного или финального оповещения.
`success`		Финальное успешное завершение оплаты.	Зафиксируйте успешную оплату в системе мерчанта.
`decline`		Финальный отказ в оплате.	Зафиксируйте отказ и сообщите пользователю о результате.

processing

new

Заявка создана и принята в обработку.

Дождитесь перехода в следующий статус.

requisites

Платежная страница приняла номер телефона и запустила сценарий оплаты.

Дождитесь перехода в следующий статус.

awaiting_3ds_result

OTP запрошен у пользователя.

Ожидайте информативное оповещение на merchant_callback_url.

sent_verification

OTP передан на проверку.

Дождитесь следующего информативного или финального оповещения.

invalid_verification

Пользователь передал неверный OTP. После трех неверных попыток ввода OTP-кода заявка переходит в decline.

Дождитесь следующего информативного или финального оповещения.

paid

Оператор подвердил корректность OTP. Ожидается финализация оплаты.

Дождитесь следующего информативного или финального оповещения.

success

Финальное успешное завершение оплаты.

Зафиксируйте успешную оплату в системе мерчанта.

decline

Финальный отказ в оплате.

Зафиксируйте отказ и сообщите пользователю о результате.

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

Оповещения отправляются на 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": "16a10539fcb34ff5a3e286625a2dc3d3",
    "payment_id": "KZT-MOBILE-ECOM-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 1500000,
    "old_amount": 1500000,
    "initial_amount": 1500000,
    "currency": "KZT",
    "lifetime": 600,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "mobile-ecom",
    "widget_method": "payin-ecom-mobile",
    "type": "payin"
  }
}

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

Оповещение отправляется, если заявка получила финальный статус decline.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539fcb34ff5a3e286625a2dc3d3",
    "payment_id": "KZT-MOBILE-ECOM-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Payment general decline"
  },
  "payment_info": {
    "amount": 1500000,
    "old_amount": 1500000,
    "initial_amount": 1500000,
    "currency": "KZT",
    "lifetime": 600,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "mobile-ecom",
    "widget_method": "payin-ecom-mobile",
    "type": "payin"
  }
}

Казахстан (ECOM) — Оплата

Поддерживаемые операторы связи

Сценарий оплаты

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

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

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

Отмена оплаты

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

Схема переходов статусов

Правила обработки OTP

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

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

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

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

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