Карты
H2H-интеграция для оплаты картами
H2H-интеграция (Host-to-Host) позволяет принимать платежи напрямую через API, минуя платёжную форму. Это даёт полный контроль над процессом оплаты.
Перед тем как начать
Как авторизовывать запросы
Эта интеграция доступна не всем мерчантам. Уточняйте доступность у вашего менеджера.
Создание заказа
Перед отправкой данных карты необходимо создать заказ и получить его UUID из поля id.
Как создавать заказы
Отправка данных карты
Отправьте данные карты на следующий endpoint:
POST /v1/orders/{orderId}/h2h/cardПример запроса
curl -X POST "https://api.panel.valutix.kz/v1/orders/{orderId}/h2h/card" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"cardNumber": "4111111111111111",
"expiryDate": "12/25",
"cardholderName": "John Doe",
"cvv": "123"
}'Тело запроса
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| cardNumber | string | ✅ Да | Номер карты |
| expiryDate | string | ✅ Да | Срок действия (ММ/ГГ) |
| cardholderName | string | ✅ Да | Имя держателя карты |
| cvv | string | ✅ Да | Код CVV/CVC |
Если в ответе вернулась информация о заказе — данные карты валидны и приняты. Теперь нужно проверить, требуется ли подтверждение SMS-кодом.
Проверка необходимости SMS-кода
Проверка статуса H2H-транзакции:
GET /v1/orders/{orderId}/h2h/statusПример запроса
curl -X GET "https://api.panel.valutix.kz/v1/orders/{orderId}/h2h/status" \
-H "X-Api-Token: YOUR_API_TOKEN"Пример ответа
{
"isSmsRequired": true,
"status": "PROCESSING"
}Поля ответа
| Поле | Описание |
|---|---|
| isSmsRequired | true — требуется ввод SMS-кода |
| status | Текущий статус H2H-транзакции |
Отправка SMS-кода
Отправка кода означает, что вы передаёте код из SMS банка плательщика в API. Это НЕ отправка SMS пользователю!
Отправьте SMS-код на endpoint:
POST /v1/orders/{orderId}/h2h/codeПример запроса
curl -X POST "https://api.panel.valutix.kz/v1/orders/{orderId}/h2h/code" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"code": "123456"
}'Алгоритм проверки
- Успешный ответ — код принят, продолжайте проверять статус
- Опрашивайте статус H2H-транзакции, пока
status = "PROCESSING" - Если
isSmsRequiredснова сталоtrue— код был неверным, запросите его повторно
Статусы H2H
Статусы H2H-транзакции — это НЕ то же самое, что статусы основного заказа. Они описывают внутренний процесс Host-to-Host. Финальный результат всегда подтверждайте по статусу заказа и webhook-уведомлениям.
Отслеживайте оба потока статусов:
- Опрос H2H-статуса (
/orders/{orderId}/h2h/status) до терминального состояния - Webhook-события заказа (финальное подтверждение оплаты)
Список H2H-статусов
| Статус | Описание |
|---|---|
| INITIALIZING | H2H инициализируется |
| PROCESSING | H2H обрабатывается (валидация, 3-D Secure, антифрод и пр.) |
| SUCCESS | Этап H2H завершён успешно (ждите финальный статус заказа через webhook) |
| CANCELLED | H2H-платёж отменён |
| FAILED | H2H завершился ошибкой |
| EXPIRED | Срок действия H2H-сессии истёк |
Рекомендации по обработке
- Опрашивайте статус, пока он
INITIALIZINGилиPROCESSING - На
SUCCESS— переходите к проверке финального статуса заказа и ждите webhook-событие - На терминальных
CANCELLED,FAILED,EXPIRED— прекращайте опрос и фиксируйте неуспех - Если после отправки SMS-кода статус снова
PROCESSING, продолжайте ждать; если код снова требуется (isSmsRequired = true) — запросите его повторно
Только статус заказа (через webhook / прямой запрос) окончательно
подтверждает списание средств. Статус SUCCESS на уровне H2H — это
промежуточный успех.
Общий процесс H2H-интеграции
Проверка статуса заказа
После завершения H2H-процесса проверьте финальный статус заказа: