Integrated terminals

Connect your point-of-sale (POS) system to Airwallex Smart POS terminals via the Airwallex payment gateway. In this mode, your server creates a PaymentIntent, delivers it to a registered terminal, and the shopper pays on the device—giving you a clear link between order information and payment information.

This integration model is API-only on your side (no terminal SDK in your app). It suits vertical SaaS platforms and enterprise retailers that need scalable, omnichannel checkout with consistent integration and unified reporting alongside online payments.

As with Web checkout, you use the standard PaymentIntents API API to create a payment request. You then need to call Process a PaymentIntent in a Terminal API to wake the device and complete the payment. You can also register and manage terminals with the Payments Terminals API API.

When to use integrated terminals

Choose this integration model when you:

• Operate a POS, ordering system, or vertical SaaS product that must trigger in-person payments on Airwallex hardware.
• Need clear linkage between order info and payment info for reconciliation (versus manual matching on standalone terminals).
• Want to integrate only with Airwallex APIs while Airwallex manages terminal delivery and card-present processing in the cloud.
• Serve first-party retail merchants or vertical SaaS platforms adopting Airwallex terminals at scale.

Trade-offs compared with standalone mode:

How integrated terminals work

In integrated terminals, a POS payment takes three steps:

1. Create a PaymentIntent (server): Your backend calls Create a PaymentIntent API with order amount, currency, and merchant_order_id.
2. Process the PaymentIntent on a terminal (server): Your backend calls Process a PaymentIntent in a Terminal API. Airwallex delivers the intent to the terminal, which opens a screen awaiting the card.
3. Shopper pays on the terminal: The shopper taps, inserts, or swipes the card (or uses a supported wallet) on the device.

Before you begin

• POS payments and terminal APIs are enabled on your Airwallex account.
• You have a Client ID and Admin API key from the Airwallex web app. Use an Admin API key, not a scoped API key—Terminal API permission controls may require Admin keys when enforced. See Manage API keys.
• At least one Airwallex terminal is registered and active (activation code from the device).
• You can run HTTPS requests from a backend server.

Contact your Airwallex Account Manager for POS onboarding, terminal provisioning, and sandbox access.

For product context and comparison with SoftPOS or BYOD paths, see Compare integration options.

Step 1: Obtain an access token

Authenticate with your Client ID and API key.

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

Response

1{
2  "expires_at": "2026-10-26T06:38:13+0000",
3  "token": "eyJhbGci..."
4}

Include Authorization: Bearer {{token}} on all subsequent requests. Refresh the token before expires_at.

Terminal management

Airwallex provides POS terminal lifecycle management through the Payments Terminals API API—register terminals, update status, list inventory with filters, and reset passwords.

Terminal object

Key fields on a terminal resource:

• id: Terminal resource ID (for example ter_sthb7thh2rq2tsoru). Use this in Process PaymentIntent calls.
• serial_number: Physical device serial number.
• model: Device model (for example morefun_m90).
• status: ACTIVE, INACTIVE, or TERMINATED.
• nickname: Friendly name for the terminal.
• admin_password_status: ACTIVE, LOCKED, or RESET_REQUESTED.
• refund_password_status: ACTIVE, LOCKED, RESET_REQUESTED, or OPT_OUT.
• connected_account_id: Optional. Platform use only—identifies a connected account for the transaction. Cannot be used with the x-on-behalf-of header.

Create a terminal

Register a terminal with the activation code displayed on the device.

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/pos/terminals/create \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
6    "activation_code": "{{ACTIVATION_CODE_FROM_DEVICE}}",
7    "nickname": "Store counter 1"
8  }'

Returns a terminal object with status ACTIVE.

See Create a Terminal API.

List terminals

Retrieve terminals for use in payment routing. Use the id from the response when calling Process PaymentIntent.

1curl -G https://api-demo.airwallex.com/api/v1/pa/pos/terminals \
2  --data-urlencode 'page=0' \
3  --data-urlencode 'page_size=20' \
4  --data-urlencode 'status=ACTIVE' \
5  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Optional query parameters include serial_number, model, status, and nickname.

See List Terminals API.

Retrieve, activate, deactivate, and terminate

• Retrieve: GET /api/v1/pa/pos/terminals/{id} API
• Activate (INACTIVE → ACTIVE): POST /api/v1/pa/pos/terminals/{id}/activate API
• Deactivate (ACTIVE → INACTIVE): POST /api/v1/pa/pos/terminals/{id}/deactivate API
• Terminate (ACTIVE or INACTIVE → TERMINATED): POST /api/v1/pa/pos/terminals/{id}/terminate API
• Update nickname: POST /api/v1/pa/pos/terminals/{id}/update API

Each mutating call requires a unique request_id.

Reset terminal password

Reset the admin or refund password on a terminal.

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/pos/terminals/{{TERMINAL_ID}}/reset_password \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
6    "password_type": "admin"
7  }'

password_type is admin or refund.

See Reset Terminal Password API.

Step 2: Create a PaymentIntent

Create a PaymentIntent when the shopper is ready to pay.

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": 112.81,
7    "currency": "SGD",
8    "merchant_order_id": "D202503210001"
9  }'

Response (201 Created)

1{
2  "id": "int_sgstpgqqmh7sl0mbv6z",
3  "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
4  "amount": 112.81,
5  "currency": "SGD",
6  "merchant_order_id": "D202503210001",
7  "status": "REQUIRES_PAYMENT_METHOD"
8}

Save id for the process and capture steps.

Step 3: Process the PaymentIntent on a terminal

Deliver the PaymentIntent to a specific terminal. Airwallex pushes the intent to the device, which displays a payment screen.

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/pos/terminals/{{TERMINAL_ID}}/process_payment_intent \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
6    "payment_intent_id": "int_sgstpgqqmh7sl0mbv6z",
7    "payment_method_options": {
8      "card": {
9        "authorization_type": "final_auth",
10        "auto_capture": true
11      }
12    }
13  }'

• payment_intent_id: PaymentIntent id from Step 2.
• payment_method_options.card.authorization_type: final_auth (default) or pre_auth (Visa/Mastercard only).
• payment_method_options.card.auto_capture: true (default)—capture after authorization. Set false for manual capture.

Response

Returns the terminal object (for example id, serial_number, status, nickname).

Step 4: Capture a PaymentIntent (manual capture only)

If you set auto_capture to false in Process PaymentIntent, the PaymentIntent moves to REQUIRES_CAPTURE after the shopper pays. Call Capture a PaymentIntent API to settle funds.

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
6    "amount": 112.81
7  }'

See Place a hold on a payment method.

Cancel a PaymentIntent

Use Cancel a PaymentIntent API for both reversal and void purposes. Cancel is allowed when status is REQUIRES_PAYMENT_METHOD or REQUIRES_CAPTURE. Canceling an authorized payment (REQUIRES_CAPTURE) reverses the authorized amount.

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_intents/{{PAYMENT_INTENT_ID}}/cancel \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "request_id": "1ccb6e97-37c6-45fe-ac3f-1380b7c0a0cd",
6    "cancellation_reason": "Cancelled by customer",
7    "cancellation_reason_code": "cancelled_by_customer"
8  }'

• cancelled_by_customer: Default. The shopper or merchant canceled.
• processing_error: Processing error—for example card-present chip verification failed.
• timeout: The terminal or your server did not receive a timely response.

If a timeout occurs and you do not know the PaymentIntent id, look up the intent using merchant_order_id from your server records.

Refund a payment

Refund a SUCCEEDED PaymentIntent with Create a Refund API. The refund amount can be equal to or less than the original amount; multiple partial refunds are allowed until the PaymentIntent is fully refunded.

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/refunds/create \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
6    "payment_intent_id": "int_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",
7    "amount": 10.01,
8    "reason": "Return good"
9  }'

Refunds can also be initiated from the Airwallex web app or your commerce admin where supported; status is reflected on the terminal.

Check the payment result

• Server — Retrieve a PaymentIntent API after the terminal flow completes. Subscribe to Payments webhooks (for example payment_intent.succeeded) as a supplementary signal.
• Timeouts — If the terminal does not return a definitive outcome in time, query by PaymentIntent id or merchant_order_id from your server before updating order status.

Terminal capabilities

Integrated terminals support the same core capabilities as standalone terminals where enabled for your region. See Capabilities on the terminal.

See also

• POS payments overview
• Standalone terminals
• Quickstart: SoftPOS SDK
• PaymentIntents