South Korea

Before you start

Authorization

How to sign your requests with the API token.

Create payment

The base order request that this page extends.

This payment method is not enabled for all merchants. Check availability with your manager.

Overview

Currency	Payment method
`KRW`	Local bank and wallet methods

The payer is redirected to paymentLink and chooses a method on the provider page.

What is different from a regular order

The order is created through the standard POST /v1/orders endpoint. The base fields (amount, currency, successUrl, failUrl, callbackUrl, etc.) are the same as for a regular order; on top of them you pass the customer object with payer details.

Field	Type	Description
`customer`	object	Payer details. The required set is listed below

The externalUserId field is required for this payment method.

Customer fields

Field	Type	Required	Description
`phone`	string	✅ Yes	Phone number: 11 digits starting with `0`, without country code (e.g. `01012345678`)
`email`	string	✅ Yes	Payer email
`firstName`	string	✅ Yes	First name, must match the phone number owner
`lastName`	string	✅ Yes	Last name, must match the phone number owner
`ip`	string	✅ Yes	Payer IP address (real)
`birthday`	string	Virtual account	Date of birth, `YYYY-MM-DD`. Required for virtual account payments only

Pass the payer's real data. Names and phone numbers are checked against the phone number owner on the provider side; mismatches lead to declined payments.

Request example

{
  "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"
  }
}

Response

The response is a standard order object. The order is created with the CREATED status; redirect the payer to paymentLink to complete the payment.

Order object fields

Next steps

Order status and webhooks

Get notified when the payment is completed.

Payments by country

Other countries and payment methods.

H2H and the payment form

Ask your manager to enable H2H for the required method. The create-order request stays the same unless an extra field is listed below. Open the returned paymentLink: the platform payment form displays the QR code, bank details, or wallet action and waits for the final result. Existing payment-page integrations remain available.

H2H is available for virtual accounts and NizPay. Other wallet and card methods continue to use the provider payment page.

For a virtual account, send customer.birthday. If identity verification is required, send the payer to paymentLink first: the form opens verification and then receives the account details automatically. Until verification is complete, the bank-details endpoint can return 503.

Receiving bank details via API

curl -X POST "https://api.panel.valutix.kz/v1/orders/{orderId}/h2h/bank-transfer" \
  -H "x-api-token: YOUR_API_TOKEN"

The response contains accountNumber, accountName, bankName, bankCode, amount, currency, and details. Missing optional values are null. Show every returned entry in details, including the branch or transfer reference. Repeated calls reuse the same payment. HTTP 503 means details are not ready; retry after a few seconds. HTTP 400 means this method does not issue bank details (or the order is a test order), 404 means the order was not found, and 409 means it is no longer payable.

NizPay payer account

For NizPay H2H, add additional.payerId to the regular create-order request. This is the payer's actual NizPay account ID, not your externalUserId and not the terminal merchant ID. It is a non-empty string of up to 128 characters.

{
  "additional": {
    "payerId": "nizpay-account-123"
  }
}

Open paymentLink to initiate the wallet request. The payer confirms the payment in NizPay, while the form waits for the final status. NizPay does not issue bank details or a payment QR in this flow.