Accept payments with South Korean issuer-authenticated cards
This topic describes how to integrate South Korean issuer-authenticated cards using the hosted mode. Since Korean local card payments do not support 3DS authentication, merchants in specific industries (such as digital entertainment) face payment limit constraints. To increase transaction limits and effectively reduce risk, it is recommended that you integrate the South Korean issuer-authenticated card payment method.
In the authenticated card payment scenario, each payment must be authenticatied. Through the hosted mode, Antom provides an intermediate payment page where your buyers can select their preferred card brand. You do not need to handle the card brand selection logic directly, nor will you need to handle the buyer's payment data. This ensures a seamless and reliable payment experience for buyers while maintaining security and compliance.
User experience
The following image illustrates the user experience for South Korean issuer-authenticated card payments:
Payment flow
For South Korean issuer-authenticated card payments, the payment flow is composed of the following steps:
- The buyer selects products and submits payment.
- Initiate a payment request.
The merchant server calls the pay (One-time Payments) API to obtain the payment continuation URL. - Redirect the buyer to the bank selection page.
Antom returns the payment continuation URL (normalUrl) in the response of the pay (One-time Payments) API. The merchant client displays an intermediate payment page, allowing the buyer to select their preferred South Korean issuer-authenticated card brand. The buyer is then redirected to the corresponding South Korean issuer-authenticated card payment page to pay. After payment is completed, the buyer returns to the merchant payment result page. - Obtain the authorized payment result.
The merchant server receives the authorized payment notification returned by Antom and performs corresponding business processing based on the result. - Obtain the capture result.
If the authorized payment is successful, Antom will automatically initiate capture on your behalf. You can obtain the capture result through either of the following two methods:
- Asynchronous notification: Specify paymentNotifyUrl in the pay (One-time Payments) API or configure on Antom Dashboard to set the address for receiving asynchronous notifications. Upon capture completion, Antom will send you asynchronous notifications via the notifyCapture (One-time Payments) API.
- Synchronous inquiry: Call the inquiryPayment API to check the capture status.
Integration preparations
Before you start integrating, read the Integration Guide and API Overview documents to understand the integration steps of the server-side API and the precautions for calling the API. Furthermore, ensure that the following prerequisites are met:
- Obtain a client ID
- Complete the key configuration
- Complete the configuration of paymentNotifyUrl to receive the asynchronous notification
- Integrate the server-side SDK package, install the server-side library, and initialize a request instance. For more details, refer to Server-side SDKs.
Integration steps
Start your integration by taking the following steps:
- Initiate a payment request
- Redirect to the bank selection page
- Obtain the authorized payment result
- Obtain the capture result
Step 1: Initiate a payment request
Follow Step 1: Initiate an authorized payment to call the pay (One-time Payments) API and submit the payment request. You need to pass in the basic parameters, order parameters, and device parameters in the payment request. At the same time, you do not need to pass in card payment parameters or 3DS information, but you need to pass in the following parameters:
Parameter name | Required | Description |
requireIssuerAuthentication | Yes | For South Korean issuer-authenticated card payments, set this parameter to |
selectedCardBrand | No | The card brand selected by the buyer. In South Korean issuer-authenticated card payments:
|
isAuthorization.captureMode | No | The capture mode. For South Korean issuer-authenticated card payments, only automatic capture by Antom is supported. Please keep the default value |
The following code shows a sample of the request message:
{
"env": {
"osType": "ANDROID",
"terminalType": "WAP",
"clientIp": "192.168.1.1"
},
"order": {
"orderAmount": {
"currency": "KRW",
"value": "46000"
},
"orderDescription": "클룩과 함께 떠날 즐거운 시간",
"referenceOrderId": "referenceOrderId01",
"buyer": {
"buyerEmail": "xxx @xxx.com"
}
},
"paymentAmount": {
"currency": "KRW",
"value": "46000"
},
"paymentFactor": {
"isAuthorization": true
},
"paymentMethod": {
"paymentMethodType": "CARD",
"paymentMethodMetaData": {
"selectedCardBrand": "HYUNDAI", // Optional. Used to specify the card brand to skip the Antom bank selection page
"requireIssuerAuthentication": true
}
},
"paymentNotifyUrl": "https://www.yourNotifyUrl.com",
"paymentRedirectUrl": "https://www.yourMerchantWeb.com",
"paymentRequestId": "paymentRequestId01",
"productCode": "CASHIER_PAYMENT",
"settlementStrategy": {
"settlementCurrency": "KRW"
}
}The following code shows an example of the response message after initiating an authorized payment. It does not directly return the authorized payment result, but instead returns normalUrl to redirect the buyer to the payment method page for payment.
{
"normalUrl": "https://payment-gateway.tosspayments.com/link/payment?urlToken=checkout-url-****",
"paymentActionForm": "{\"method\":\"GET\",\"paymentActionFormType\":\"RedirectActionForm\",\"redirectUrl\":\"https://payment-gateway.tosspayments.com/link/payment?urlToken=checkout-url-****\"}",
"paymentAmount": {
"currency": "KRW",
"value": "46000"
},
"paymentCreateTime": "2025-12-16T18:09:37-08:00",
"paymentId": "20251217194******0236670295",
"paymentRequestId": "paymentRequestId01",
"paymentResultInfo": {
"avsResultRaw": "",
"cvvResultRaw": "",
"threeDSResult": {
"cavv": "",
"eci": ""
}
},
"paymentTime": "2025-12-16T18:09:38-08:00",
"redirectActionForm": {
"method": "GET",
"redirectUrl": "https://payment-gateway.tosspayments.com/link/payment?urlToken=checkout-url-****"
},
"result": {
"resultCode": "PAYMENT_IN_PROCESS",
"resultMessage": "payment in process",
"resultStatus": "U"
}
}Step 2: Redirect to the bank selection page
After the merchant server obtains normalUrl returned in the response of pay (One-time Payments), it should pass this URL to the client side. The merchant client then redirects to the corresponding bank payment page or the bank selection page (Antom intermediate page). The user experience is as follows:
Bank payment page | Antom intermediate page |
If you specified the buyer's card brand in the selectedCardBrand parameter of the pay (One-time Payments) API, the buyer will be directly redirected to that bank’s payment page. Example normalUrl returned by Antom: The figure below shows the user experience of direct redirection to the bank payment page:
| If you did not specify selectedCardBrand, the buyer will be redirected to the Antom-hosted bank selection page to select their preferred South Korean issuer-authenticated card brand, then be redirected to the corresponding card payment page. Example normalUrl returned by Antom: The figure below shows the user experience of redirecting to the Antom intermediate page for card brand selection:
|
Process the obtained normalUrl according to the instructions in Step 2: Redirect to the card information collection page.
Step 3: Obtain the authorized payment result
Obtain the authorized payment result by following the steps detailed in Step 3: Obtain the authorization result. The sample code below demonstrates the asynchronous notification returned by Antom via the notifyPayment API:
{
"actualPaymentAmount": {
"currency": "KRW",
"value": "46000"
},
"cardInfo": {
"avsResultRaw": "",
"cardNo": "************513*",
"cvvResultRaw": "",
"paymentMethodRegion": "KR",
"threeDSResult": {
"cavv": "",
"challengeCancel": "",
"challenged": false,
"eci": "",
"threeDSOffered": false,
"threeDStransactionStatusReason": ""
}
},
"notifyType": "PAYMENT_RESULT",
"paymentAmount": {
"currency": "KRW",
"value": "46000"
},
"paymentCreateTime": "2025-12-16T18:09:37-08:00",
"paymentId": "20251217194******0236670295",
"paymentRequestId": "paymentRequestId01",
"paymentResultInfo": {
"avsResultRaw": "",
"cardNo": "************513*",
"cvvResultRaw": "",
"paymentMethodRegion": "KR",
"threeDSResult": {
"cavv": "",
"challengeCancel": "",
"challenged": false,
"eci": "",
"threeDSOffered": false,
"threeDStransactionStatusReason": ""
}
},
"paymentTime": "2025-12-16T18:09:56-08:00",
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}Step 4: Obtain the capture result
If the authorized payment is successful, Antom will automatically initiate capture on your behalf. You can obtain the capture result through asynchronous notification or active query.
Note: South Korean issuer-authenticated card payments only support capture initiated automatically by Antom. Additionally, authorized payment of successful orders cannot be voided.
After payments
After completing the payment, you can perform the following actions:
Cancellation
South Korean issuer-authenticated card payments do not support voiding orders that have been successfully authorized. For orders where authorization has not yet been completed, you may cancel them directly. Refer to Cancel for specific operations.
Refund
Different payment methods have varying refund capabilities. To learn about Antom refund rules and how to initiate a refund for a successful transaction, refer to Refund.
Dispute
Antom provides dispute resolution services for contested transactions. For more information, refer to Dispute Guidance.