Quickstart: Korean local card elements

Complete a minimal end-to-end checkout using Airwallex.js and the Korean local card elements (split fields for Korean card networks). By the end of this tutorial, you will have a working checkout page that collects Korean local card details and confirms a PaymentIntent from the browser.

You'll do the following:

• Authenticate to Airwallex and generate an access token.
• Create a PaymentIntent on your server.
• Build a checkout page that mounts the Korean local card elements and confirms the PaymentIntent when the shopper submits payment.
• Arrange testing and verify results with your Airwallex team (Korean local cards do not offer a public card sandbox).

Before you begin

• You must have a sandbox account for testing.
• You need an Airwallex account with online payments enabled and Korean local cards enabled for your integration (beta). Contact your Account Manager if you are unsure.
• You must have your Client ID and API key from Developer > API keys in the sandbox web app.
• You must be able to make HTTP requests from a backend server and serve a simple HTML page (or equivalent) that loads the Airwallex.js script from the CDN.
• Install Airwallex.js JS from the CDN (as in this tutorial) or via @airwallex/components-sdk . If you currently use Airwallex Payment elements , see the upgrade guide.

Step 1: Get an access token on your server

Payment APIs require an access token generated from your Client ID and API key.

Request

1curl -X POST https://api-demo.airwallex.com/api/v1/authentication/login \
2  -H 'Content-Type: application/json' \
3  -H 'x-api-key: {{YOUR_SANDBOX_API_KEY}}' \
4  -H 'x-client-id: {{YOUR_SANDBOX_CLIENT_ID}}'

Response

1{
2  "token": "your_access_token",
3  "expires_at": "2025-12-31T23:59:59Z"
4}

Save the token in your backend and reuse it until it expires.

Step 2: Create a PaymentIntent on your server

A PaymentIntent represents your intent to collect a specific amount from a shopper. The Korean local card elements collect details against that intent; you confirm it when the shopper submits payment.

When the shopper begins checkout, call Create a PaymentIntent API on your server with request_id, amount, currency, and merchant_order_id. Always decide how much to charge on the server so shoppers cannot alter the amount.

Use a currency supported for your Korean local cards integration (commonly KRW). Provide return_url so Airwallex can return the shopper to your site after any redirect-based flow. Learn more about the PaymentIntents API.

Request

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_intents/create \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
6    "amount": 100,
7    "currency": "KRW",
8    "merchant_order_id": "D202503210001",
9    "return_url": "https://www.example.com/payment-return"
10  }'

Response

The API returns a PaymentIntent object. See Create a PaymentIntent API for the full response schema.

1{
2  "id": "int_your_payment_intent_id",
3  "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
4  "amount": 100,
5  "currency": "KRW",
6  "merchant_order_id": "D202503210001",
7  "status": "REQUIRES_PAYMENT_METHOD",
8  "created_at": "2024-01-30T03:31:29+0000",
9  "updated_at": "2024-01-30T03:31:29+0000",
10  "client_secret": "your_client_secret"
11}

For the checkout page in Step 3, you will need:

• id: The PaymentIntent ID (intent_id on the client).
• client_secret: Used on the client to attach card details and confirm securely.
• currency: The same currency you passed when creating the PaymentIntent.

Step 3: Build a basic checkout page with Korean local card elements

Build a simple HTML page that loads Airwallex.js from the CDN, initializes the SDK, creates the Korean card number JS, Korean card identifier JS (date of birth or business number), Korean card expiry JS, and Korean card password first-two JS elements, mounts them into containers, and calls confirm() JS on the card number element when the shopper clicks Pay. Mount each element only once per payment flow.

The example below defaults to Personal card type for krCardIdentifier (date of birth). If the shopper selects Company, recreate krCardIdentifier with cardType: 'company' and use a container for the business number field as described in the Korean Card Identifier JS reference.

Add the SDK, form layout, and script

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="utf-8" />
5  <title>Quickstart — Korean local card elements</title>
6  <script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>
7</head>
8<body>
9  <h1>Korean local card elements</h1>
10  <p>Enter card details, then click Pay to confirm the PaymentIntent.</p>
11
12  <div>
13    <div>Card number</div>
14    <div id="krCardNumber"></div>
15  </div>
16
17  <div>
18    <div>Card type</div>
19    <label>
20      <input type="radio" name="cardTypeRadio" value="personal" checked />
21      <span>Personal</span>
22    </label>
23    <label>
24      <input type="radio" name="cardTypeRadio" value="company" />
25      <span>Company</span>
26    </label>
27  </div>
28
29  <div>
30    <div>Date of birth / identifier</div>
31    <div id="krCardIdentifier"></div>
32  </div>
33
34  <div>
35    <div>Expiry date</div>
36    <div id="krCardExpiry"></div>
37  </div>
38
39  <div>
40    <div>First two digits of card password</div>
41    <div id="krCardPswFirstTwo"></div>
42  </div>
43
44  <button id="submit" type="button">Pay</button>
45
46  <script async>
47    const intent_id = 'replace-with-your-intent-id';
48    const client_secret = 'replace-with-your-client-secret';
49    const currency = 'replace-with-your-currency';
50
51    (async () => {
52      await window.AirwallexComponentsSDK.init({
53        env: 'demo',
54        enabledElements: ['payments'],
55      });
56
57      const krCardNumber = await window.AirwallexComponentsSDK.createElement('krCardNumber', {
58        intent_id,
59        client_secret,
60        currency,
61      });
62
63      const krCardIdentifier = await window.AirwallexComponentsSDK.createElement('krCardIdentifier', {
64        cardType: 'personal',
65      });
66
67      const krCardExpiry = await window.AirwallexComponentsSDK.createElement('krCardExpiry');
68      const krCardPswFirstTwo = await window.AirwallexComponentsSDK.createElement('krCardPswFirstTwo');
69
70      krCardNumber.mount('krCardNumber');
71      krCardIdentifier.mount('krCardIdentifier');
72      krCardExpiry.mount('krCardExpiry');
73      krCardPswFirstTwo.mount('krCardPswFirstTwo');
74
75      document.getElementById('submit').addEventListener('click', () => {
76        krCardNumber
77          .confirm({
78            intent_id,
79            client_secret,
80          })
81          .then((response) => {
82            console.log(response);
83          })
84          .catch((err) => {
85            console.error(err);
86          });
87      });
88    })();
89  </script>
90</body>
91</html>

Replace replace-with-your-intent-id, replace-with-your-client-secret, and replace-with-your-currency with the values from the PaymentIntent you created in Step 2.

Optionally, omit intent_id, client_secret, and currency from createElement('krCardNumber', …) and pass them only in confirm() after you create the PaymentIntent when the shopper clicks Pay. For all element options, see Korean Card Number JS, Korean Card Identifier JS, Korean Card Expiry Date JS, and Korean Card Password First-2 Digits JS.

Using npm instead of the CDN

If you bundle your frontend with npm, use the same flow with module imports:

1import { init, createElement } from '@airwallex/components-sdk';
2
3await init({
4  env: 'demo',
5  enabledElements: ['payments'],
6});
7
8const krCardNumber = createElement('krCardNumber', {
9  intent_id: 'replace-with-your-intent-id',
10  client_secret: 'replace-with-your-client-secret',
11  currency: 'replace-with-your-currency',
12});
13
14const krCardIdentifier = createElement('krCardIdentifier', {
15  cardType: 'personal',
16});
17
18const krCardExpiry = createElement('krCardExpiry');
19const krCardPswFirstTwo = createElement('krCardPswFirstTwo');
20
21krCardNumber.mount('krCardNumber');
22krCardIdentifier.mount('krCardIdentifier');
23krCardExpiry.mount('krCardExpiry');
24krCardPswFirstTwo.mount('krCardPswFirstTwo');
25
26document.getElementById('submit').addEventListener('click', () => {
27  krCardNumber
28    .confirm({
29      intent_id: 'replace-with-your-intent-id',
30      client_secret: 'replace-with-your-client-secret',
31    })
32    .then((response) => {
33      console.log(response);
34    })
35    .catch((err) => {
36      console.error(err);
37    });
38});

Step 4: Test with your Airwallex team and verify the payment

Arrange Korean local cards testing

Korean local cards do not offer a public sandbox for card entry. Work with your Airwallex Account Manager and solution engineer to run test payments in the environment they provide.

Verify the PaymentIntent status

When a test payment completes, verify the outcome on your server:

1. Airwallex web app

   Check Payments > Payments Activity (or the view your team recommends) for the PaymentIntent.

2. Retrieve PaymentIntent via API

   Shell

   1curl -G https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_your_payment_intent_id \
   2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

   Inspect status (for example SUCCEEDED on success). Do not rely on the browser alone—the shopper may close the page before your client handler runs.

3. Webhooks (recommended for production)

   Configure a webhook endpoint for payment_intent.succeeded and related events. See Listen for webhook events.

Next steps

• Prepare for production

  Add robust error handling for declines and network flows, and validate behavior with your Account Manager. See Airwallex.js error codes.

• Product overview

  See Korean local card elements for supported features and FAQs.

• Customize checkout

  See Customize style and appearance.

• Save payment details for later

  For returning shoppers, see Save and reuse payment details.

• Other web checkout options

  For generic split card fields, see Quickstart: Split card element. For a pre-built multi-method block, see Quickstart: Drop-in element. For more options, see Web checkout overview.

Complete the Test and go-live checklist before going live.