Южная Корея
Локальные способы оплаты в KRW
Перед тем как начать
Авторизация
Как подписывать запросы API-токеном.
Создание платежа
Базовый запрос на создание заказа, который расширяет эта страница.
Этот способ оплаты доступен не всем мерчантам. Уточните доступность у вашего менеджера.
Обзор
| Валюта | Способ оплаты |
|---|---|
KRW | Локальные банковские способы и кошельки |
Плательщик перенаправляется на paymentLink и выбирает способ оплаты на странице провайдера.
Чем отличается от обычного заказа
Заказ создаётся через стандартный эндпоинт POST /v1/orders. Базовые поля (amount, currency, successUrl, failUrl, callbackUrl и т. д.) такие же, как у обычного заказа; дополнительно к ним передаётся объект customer с данными плательщика.
| Поле | Тип | Описание |
|---|---|---|
customer | object | Данные плательщика. Набор обязательных полей приведён ниже |
Для этого способа оплаты поле externalUserId обязательно.
Поля объекта customer
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
phone | string | ✅ Да | Номер телефона: 11 цифр, начинается с 0, без кода страны (например, 01012345678) |
email | string | ✅ Да | Email плательщика |
firstName | string | ✅ Да | Имя, должно совпадать с владельцем номера телефона |
lastName | string | ✅ Да | Фамилия, должна совпадать с владельцем номера телефона |
ip | string | ✅ Да | IP-адрес плательщика (реальный) |
birthday | string | Виртуальный счёт | Дата рождения, YYYY-MM-DD. Обязательно только для платежей через виртуальный счёт |
Передавайте реальные данные плательщика. Имена и номера телефонов сверяются с владельцем номера на стороне провайдера; при несовпадении платежи отклоняются.
Пример запроса
{
"purpose": "Payment for order #1234",
"amount": "5000",
"currency": "KRW",
"externalId": "23456789",
"externalUserId": "437568",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments",
"customer": {
"lastName": "Kim",
"firstName": "Minsu",
"email": "minsu.kim@example.com",
"phone": "01012459077",
"ip": "192.168.0.1",
"birthday": "1992-08-15"
}
}Ответ
В ответе возвращается стандартный объект заказа. Заказ создаётся со статусом CREATED; перенаправьте плательщика на paymentLink, чтобы он завершил оплату.
Поля объекта заказа
Следующие шаги
Статус заказа и webhook-уведомления
Получайте уведомления о завершении оплаты.
Платежи по странам
Другие страны и способы оплаты.
H2H и платёжная форма
Для нужного метода менеджер должен включить H2H. Запрос создания заказа остаётся прежним, кроме дополнительных полей, указанных ниже. Откройте полученный paymentLink: платёжная форма платформы покажет QR-код, банковские реквизиты или действие для кошелька и дождётся результата. Прежняя интеграция с платёжной страницей остаётся доступной.
H2H доступен для виртуальных счетов и NizPay. Остальные кошельки и карточные методы используют платёжную страницу провайдера.
Для виртуального счёта передайте customer.birthday. Если требуется проверка личности, сначала направьте плательщика на paymentLink: форма откроет проверку, а затем автоматически получит реквизиты. До завершения проверки ручка банковских реквизитов может возвращать 503.
Получение реквизитов через API
curl -X POST "https://api.panel.valutix.kz/v1/orders/{orderId}/h2h/bank-transfer" \
-H "x-api-token: YOUR_API_TOKEN"Ответ содержит accountNumber, accountName, bankName, bankCode, amount, currency и details. Отсутствующие необязательные значения равны null. Показывайте все поля из details, включая отделение банка и назначение перевода. Повторные запросы используют тот же платёж. HTTP 503 означает, что реквизиты ещё не готовы: повторите запрос через несколько секунд. HTTP 400 — метод не выдаёт банковские реквизиты либо заказ тестовый, 404 — заказ не найден, 409 — заказ уже недоступен для оплаты.
Аккаунт плательщика NizPay
Для NizPay H2H добавьте additional.payerId к обычному запросу создания заказа. Это настоящий ID аккаунта плательщика в NizPay, а не ваш externalUserId и не ID терминального мерчанта. Непустая строка длиной до 128 символов.
{
"additional": {
"payerId": "nizpay-account-123"
}
}Откройте paymentLink, чтобы инициировать запрос в кошелёк. Плательщик подтверждает оплату в NizPay, а форма ожидает итоговый статус. В этом сценарии NizPay не выдаёт банковские реквизиты или платёжный QR.