A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Airwallex API is how an app or AI agent works with an Airwallex account: accepting a payment, refunding it, paying out to a beneficiary, or reading the balance across currencies. Access is granted by exchanging a client ID and API key for a short-lived token, and that token inherits whatever the key is permitted to do on the account. Airwallex pins behaviour to a dated version sent on each request, and a state change emits an event that Airwallex can deliver to a registered endpoint.
How an app or AI agent connects to Airwallex determines what it can reach. There is a route for making calls, a route for receiving events, and a developer server that helps an agent write Airwallex integration code, and each is governed by the API key behind it and the permissions that key carries.
The REST API takes JSON request bodies and returns JSON, at https://api.airwallex.com (production) and https://api-demo.airwallex.com (sandbox). A call authenticates with a Bearer access token obtained by exchanging a client ID and API key at the authentication endpoint; the token is valid for 30 minutes and reused across calls. Most write paths end in an action verb, like /api/v1/pa/payment_intents/{id}/confirm.
Airwallex POSTs an event to an HTTPS endpoint registered in the web app. The event carries a name like payment_intent.succeeded and a payload describing what changed, and the receiver verifies a signature on the request to confirm it came from Airwallex before acting on it. This lets an integration react to activity without polling.
A first-party Model Context Protocol server helps AI coding agents build Airwallex integrations. It exposes documentation and developer tooling rather than running live business operations, at https://mcp.airwallex.com/mcp for production, https://mcp-demo.airwallex.com/developer for sandbox, and https://mcp-demo.airwallex.com/docs for documentation only. The developer and production endpoints authenticate with an OAuth flow; the docs endpoint needs no authentication.
The primary method for first-party server calls. A client ID and API key, created in the web app, are sent to the authentication endpoint, which returns a Bearer access token valid for 30 minutes. The token is then sent on every request and reused until it expires. The key's account-level permissions, set at creation, govern what the token can do.
A platform connects to accounts it does not own through an authorisation flow, after which it can act on behalf of a connected account. The connection defines which accounts the platform may reach, and a request names the account it acts for. This is how marketplaces and platforms operate across many Airwallex accounts.
The Airwallex API is split into areas an agent can act on, like accepting payments, refunding them, paying out to beneficiaries, and reading balances and global accounts. Each area has its own methods, and writes in some areas move real money or issue spendable cards.
Methods for accepting payments, modeled as PaymentIntents.
Methods for refunding payments back to shoppers.
Methods for reading available payment method configuration.
Methods for storing shoppers to reuse on future payments.
Methods for saving payout recipients.
Methods for paying out to beneficiaries.
Methods for reading the account balance across currencies.
Methods for opening and reading multi-currency receiving accounts.
Methods for creating and managing spendable cards.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Payments (PaymentIntents)Methods for accepting payments, modeled as PaymentIntents.7 | ||||||
| POST | /api/v1/authentication/login | Exchange a client ID and API key for a Bearer access token valid for 30 minutes. | write | — | Current | |
Sends x-client-id and x-api-key; the returned token is reused on every call. This endpoint has its own limit of 100 requests per minute per key. Acts onaccess_token Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit100 / minute per API key SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/pa/payment_intents/create | Create a PaymentIntent to track and orchestrate a payment, with amount, currency, and a request_id idempotency key. | write | PaymentIntents write | Current | |
A core write; the request_id makes the create safe to repeat without double-charging. Acts onpayment_intent Permission (capability) PaymentIntents writeVersionAvailable since the API’s base version Webhook event payment_intent.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/pa/payment_intents/{id}/confirm | Confirm a PaymentIntent to attempt authorisation with the shopper's payment method. | write | PaymentIntents write | Current | |
Triggers authorisation; with automatic capture it also collects funds, otherwise the intent moves to requires_capture. Acts onpayment_intent Permission (capability) PaymentIntents writeVersionAvailable since the API’s base version Webhook event payment_intent.succeededRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/pa/payment_intents/{id}/capture | Capture the funds of an authorised manual-capture PaymentIntent. | write | PaymentIntents write | Current | |
Only for manual-capture intents; collects funds authorised earlier. Acts onpayment_intent Permission (capability) PaymentIntents writeVersionAvailable since the API’s base version Webhook event payment_intent.succeededRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/pa/payment_intents/{id}/cancel | Cancel a PaymentIntent that has not completed, optionally with a cancellation reason. | write | PaymentIntents write | Current | |
Cancels the full amount and releases any held funds. Acts onpayment_intent Permission (capability) PaymentIntents writeVersionAvailable since the API’s base version Webhook event payment_intent.cancelledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/pa/payment_intents/{id} | Retrieve the details and current status of a PaymentIntent. | read | PaymentIntents read | Current | |
Read-only. Acts onpayment_intent Permission (capability) PaymentIntents readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/pa/payment_intents | List PaymentIntents, with filters and paging. | read | PaymentIntents read | Current | |
Read-only. Acts onpayment_intent Permission (capability) PaymentIntents readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RefundsMethods for refunding payments back to shoppers.2 | ||||||
| POST | /api/v1/pa/refunds/create | Refund a payment, fully or partially, against a PaymentIntent, with a reason and optional amount. | write | Refunds write | Current | |
Returns money to the shopper; omitting the amount refunds the full payment. Acts onrefund Permission (capability) Refunds writeVersionAvailable since the API’s base version Webhook event refund.succeededRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/pa/refunds/{id} | Retrieve the details and status of a refund. | read | Refunds read | Current | |
Read-only. Acts onrefund Permission (capability) Refunds readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payment MethodsMethods for reading available payment method configuration.1 | ||||||
| GET | /api/v1/pa/config/payment_method_types | Retrieve the payment method types available for a given country, currency, and configuration. | read | Payment Config read | Current | |
Read-only configuration lookup; does not move money. Acts onpayment_method_type Permission (capability) Payment Config readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersMethods for storing shoppers to reuse on future payments.3 | ||||||
| POST | /api/v1/pa/customers/create | Create a customer to store a shopper's details and reuse them on future payments. | write | Customers write | Current | |
The returned customer id is passed into Create a PaymentIntent for returning shoppers. Acts oncustomer Permission (capability) Customers writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/pa/customers/{id} | Retrieve a stored customer. | read | Customers read | Current | |
Read-only. Acts oncustomer Permission (capability) Customers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/pa/customers/{id}/update | Update a stored customer's details. | write | Customers write | Current | |
Changes stored shopper data. Acts oncustomer Permission (capability) Customers writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BeneficiariesMethods for saving payout recipients.2 | ||||||
| POST | /api/v1/beneficiaries/create | Save a payout recipient (bank account or digital wallet), returning a beneficiary id to reuse on transfers. | write | Beneficiaries write | Current | |
type is BANK_ACCOUNT or DIGITAL_WALLET; the id is reused in place of full details on a transfer. Acts onbeneficiary Permission (capability) Beneficiaries writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/beneficiaries/update/{id} | Update a saved beneficiary. | write | Beneficiaries write | Current | |
Changes who money can be sent to. Acts onbeneficiary Permission (capability) Beneficiaries writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Transfers (Payouts)Methods for paying out to beneficiaries.2 | ||||||
| POST | /api/v1/transfers/create | Create a transfer to pay out to a beneficiary, with currency, amount, date, and reference. | write | Transfers write | Current | |
Sends real money out; takes a saved beneficiary id or an inline beneficiary object. Acts ontransfer Permission (capability) Transfers writeVersionAvailable since the API’s base version Webhook event transfer.settledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/transfers/{id} | Retrieve a transfer and its current status. | read | Transfers read | Current | |
Read-only. Acts ontransfer Permission (capability) Transfers readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BalancesMethods for reading the account balance across currencies.2 | ||||||
| GET | /api/v1/balances/current | Retrieve the current balance across currencies held in the account. | read | Balances read | Current | |
Read-only; reports available and pending funds per currency. Acts onbalance Permission (capability) Balances readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/balances/history | List balance history, the entries that make up the balance over time. | read | Balances read | Current | |
Read-only. Acts onbalance Permission (capability) Balances readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Global AccountsMethods for opening and reading multi-currency receiving accounts.2 | ||||||
| POST | /api/v1/global_accounts/create | Open a global account to receive funds, including multi-currency accounts. | write | Global Accounts write | Current | |
Opens a real receiving account; multi-currency accounts can receive several currencies. Acts onglobal_account Permission (capability) Global Accounts writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/global_accounts/{id} | Retrieve a global account and its receiving details. | read | Global Accounts read | Current | |
Read-only. Acts onglobal_account Permission (capability) Global Accounts readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Issuing (Cards)Methods for creating and managing spendable cards.4 | ||||||
| POST | /api/v1/issuing/cards/create | Create a physical or virtual card issued to a business or an individual cardholder. | write | Issuing Cards write | Current | |
Mints a spendable card; issue_to is ORGANISATION or INDIVIDUAL, and program.purpose selects consumer or commercial. Acts oncard Permission (capability) Issuing Cards writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/issuing/cards/{id} | Retrieve a card's details and status. | read | Issuing Cards read | Current | |
Read-only. Acts oncard Permission (capability) Issuing Cards readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/issuing/cards/{id}/update | Update a card's transaction limits, allowed currencies, or allowed merchant categories. | write | Issuing Cards write | Current | |
Changes how much and where a live card can spend. Acts oncard Permission (capability) Issuing Cards writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/issuing/cards/{id}/activate | Activate a physical card so it can be used; virtual cards are active by default. | write | Issuing Cards write | Current | |
Only physical cards need activation; virtual cards are auto-activated. Acts oncard Permission (capability) Issuing Cards writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Airwallex can notify an app when something happens in an account, like a payment succeeding or a transfer settling. It sends an event describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
payment_intent.created | A PaymentIntent was created and is ready to be confirmed. | /api/v1/pa/payment_intents/create |
payment_intent.succeeded | A PaymentIntent completed successfully and the funds are collected. An integration fulfils the order on this event. | /api/v1/pa/payment_intents/{id}/confirm/api/v1/pa/payment_intents/{id}/capture |
payment_intent.requires_capture | A manual-capture PaymentIntent was authorised and is now awaiting capture, meaning the shopper has paid but the funds are not yet collected. | /api/v1/pa/payment_intents/{id}/confirm |
payment_intent.cancelled | A PaymentIntent was cancelled before completion, releasing any held funds. | /api/v1/pa/payment_intents/{id}/cancel |
refund.succeeded | A refund against a payment completed and the funds were returned to the shopper. | /api/v1/pa/refunds/create |
transfer.settled | A payout transfer reached its destination and is settled. | /api/v1/transfers/create |
Airwallex limits how fast an app can call, by a per-second request rate measured both across the account and per endpoint, plus a separate cap on how many requests run at once.
Airwallex meters requests by a per-second rate, not by a per-method cost or point weighting. In production an account is allowed 100 requests per second across the account and 20 per second per endpoint; sandbox is lower, at 20 per second across the account and 10 per endpoint. A separate concurrency limit caps how many requests run at once, 50 in production and 10 in sandbox. The authentication endpoint is metered separately, at 100 requests per minute per API key, which is why tokens are meant to be reused. Going over returns HTTP 429 with the code too_many_requests and the message Rate Limit Exceeded.
List endpoints page through results with a page number and page size, and many time-based lists also accept from and to filters to bound the range. A response reports whether more pages remain, so an integration walks pages until the set is exhausted. Exact page-size ceilings are stated per endpoint in the reference rather than as one global number.
An access token is valid for 30 minutes and is meant to be cached and reused across calls until it expires. A request_id (the idempotency key on payment creation) is supplied by the caller to make a create safe to repeat. Per-field and per-list size limits are stated on the individual endpoint in the reference.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_argument / validation_error | The request was malformed or a field failed validation. The body carries a code naming the error, and for a field-level failure a params or errors object pinpointing what was wrong. | Read the code and field details, correct the request, and resend. The request is not retryable unchanged. |
| 401 | unauthorized | No valid access token was provided, or the token has expired (tokens last 30 minutes). | Re-exchange the client ID and API key at the authentication endpoint for a fresh token, then retry. |
| 403 | forbidden | The token is valid but the API key lacks permission for this action, or it targets an account it may not act on. | Grant the key the needed account permission, or act on an account the key is connected to. |
| 404 | resource_not_found | The requested object does not exist or is not visible to this account or environment. | Verify the object id and confirm it lives in the same environment (production vs sandbox) and account. |
| 429 | too_many_requests | Requests exceeded the per-second or per-endpoint rate, or the concurrency cap. The message is Rate Limit Exceeded. | Back off and retry with exponential backoff, and reuse the access token rather than re-authenticating per call. |
| 500 | internal_error | An error on Airwallex's side. It is rare. | Retry idempotently with backoff, and contact Airwallex support if it persists. |
Airwallex pins API behaviour to a dated version, sent on each request, and ships dated releases that can carry breaking changes, so an integration moves up deliberately rather than being changed underneath it.
Airwallex pins behaviour to a dated version, sent in the x-api-version header on each request. A dated release can carry breaking changes, so an integration pins a version and upgrades deliberately. This cut revamped the Card and Cardholder experience in the issuing API.
A dated release on the changelog timeline. Each dated version is selected per request via the x-api-version header.
A dated release on the changelog timeline.
A dated release on the changelog timeline.
A dated release on the changelog timeline.
Pin a dated version and move up on a schedule that suits the integration.
Airwallex API changelog ↗Bollard AI sits between a team's AI agents and Airwallex. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.