Quickstart: Native API guest checkout

Complete a minimal guest (one-off) card payment using the Payments API only: your servers call Create a PaymentIntent API and Confirm a PaymentIntent API with raw card details. This path is often called Native API in Airwallex docs. By the end of this tutorial, you will have authorized a test card payment in the demo environment and know how to interpret the PaymentIntent status.

You'll do the following:

• Authenticate to Airwallex and generate an access token.
• Create a PaymentIntent on your server.
• Confirm the PaymentIntent with a card payment_method from your server.
• Interpret status (for example REQUIRES_CAPTURE or SUCCEEDED) and verify the outcome.

Before you begin

• You must have a sandbox account for testing.
• You must be able to call Airwallex REST APIs from a trusted backend only. Never send your API key or raw card data from a public browser client in production.
• Confirm your account can accept card payments for the currency you test with. You can call Get available payment method types API to see what is enabled.
• Read Build an advanced integration for PCI eligibility, versioning (x-api-version), and how Native API fits alongside 3D Secure authentication.

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. You attach the card when you confirm in Step 3.

When the shopper begins checkout, call Create a PaymentIntent API with request_id, amount, currency, and merchant_order_id. Always set the amount on the server.

Provide return_url so Airwallex can return the shopper after redirect-based flows (for example some 3DS paths). For 3DS-specific fields on confirm, see 3D Secure authentication (Native API).

You can send extra fields on create and confirm to improve risk scoring. See Payment data for enhanced fraud protection.

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": "USD",
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 schema.

1{
2  "id": "int_your_payment_intent_id",
3  "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
4  "amount": 100,
5  "currency": "USD",
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 Step 3, copy the PaymentIntent id from the response and use it in the confirm URL. If your flow uses a browser (for example 3DS return handling with client components), also retain the client_secret per the API reference; a pure server-to-server confirm in this step uses the Bearer token only.

Step 3: Confirm the PaymentIntent with a card

When the shopper submits card details to your PCI-controlled environment, call Confirm a PaymentIntent API with a new request_id and a payment_method of type: "card" including number, expiry_month, expiry_year, cvc, and optional name.

Replace int_your_payment_intent_id with the id from Step 2. The example uses a sandbox test PAN for shape only—use the test card numbers page for current scenarios, success paths, and 3DS.

Request

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_your_payment_intent_id/confirm \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "request_id": "c128e39a-7234-11ea-aa94-7fd44ffd1b82",
6    "payment_method": {
7      "type": "card",
8      "card": {
9        "number": "4012000300001003",
10        "expiry_month": "01",
11        "expiry_year": "2030",
12        "cvc": "123",
13        "name": "Test Shopper"
14      }
15    }
16  }'

Response

Inspect status and latest_payment_attempt in the response. A successful authorization often returns REQUIRES_CAPTURE when auto_capture is false, or SUCCEEDED when the payment is auto-captured. See Confirm a PaymentIntent API for all statuses and next actions (including 3DS next_action).

1{
2  "id": "int_your_payment_intent_id",
3  "request_id": "c128e39a-7234-11ea-aa94-7fd44ffd1b82",
4  "amount": 100,
5  "currency": "USD",
6  "status": "REQUIRES_CAPTURE",
7  "latest_payment_attempt": {
8    "id": "att_example",
9    "status": "AUTHORIZED",
10    "payment_method": {
11      "type": "card",
12      "card": {
13        "last4": "1003",
14        "brand": "visa"
15      }
16    }
17  }
18}

The sample above is abbreviated; your live response includes more fields.

Step 4: Capture (if required), test, and verify

Capture the funds when you use manual capture

If status is REQUIRES_CAPTURE, you must Capture a PaymentIntent API (or capture in the web app) before funds settle according to your capture settings. If you omit capture when required, you will not receive the payment.

If status is SUCCEEDED and you use auto-capture, no separate capture step is needed for that payment.

Test in the sandbox

Use test card numbers for success, failure, and 3DS scenarios. For challenge flows and return_url behavior on Native API, follow 3D Secure authentication.

Verify the PaymentIntent

1. Airwallex web app — Payments > Payments Activity.
2. Retrieve a PaymentIntent API with your server token.
3. Webhooks — listen for payment_intent.succeeded and related events (Listen for webhook events).

Next steps

• Save cards for returning shoppers

  See Save and reuse payment details (Native API).

• 3D Secure

  Implement frictionless and challenge flows with 3D Secure authentication.

• Lower PCI scope

  Consider Card element, Hosted Payment Page, or Drop-in element so Airwallex collects card data.

Complete the Test and go-live checklist before production. For API errors, see the Payments API reference API and your integration logs.