Download the PHP package wpzinc/airwallex-php without Composer

Airwallex PHP SDK

An unofficial PHP library for the Airwallex API, modelled on Stripe's PHP SDK.

• Covers the full Airwallex API: Payments, Billing, Checkout, Payouts (incl. batch transfers and payers), Spend, Transactional FX, Issuing, Embedded Finance, Lending, Finance, Reconciliation, Accounting, Risk and the sandbox Simulation endpoints (460+ endpoints, see docs/SERVICES.md)
• Handles authentication: exchanges your client ID and API key for an access token, caches it and refreshes it when it expires
• Adds request_id idempotency keys automatically on the endpoints that take them
• Retries connection errors, 429s and 5xxs with backoff (POSTs are only retried when idempotent)
• Typed exceptions, auto-pagination for both of Airwallex's pagination styles, and webhook signature verification
• No dependencies beyond ext-curl and ext-json. Bring your own HTTP client or token cache if you want

This package is not affiliated with or endorsed by Airwallex. "Airwallex" is a trademark of Airwallex Pty Ltd, used here only to describe API compatibility.

Requirements

PHP 8.2 or later.

Installation

Getting started

Create an API key in the Airwallex web app under Developer > API keys.

Services are properties on the client. Resources from the core payments and treasury APIs live at the top level. Other products are grouped by namespace, as in Stripe's SDK:

Every method takes path parameters first, then $params (query string for GET, JSON body otherwise) and $opts (request options). See docs/SERVICES.md for the full list.

Billing (subscriptions)

Field names follow the Airwallex API reference. The SDK passes $params through unchanged, so check the docs for each endpoint's fields.

Pagination

List methods return a Collection. Iterate the current page, or use autoPagingIterator() to walk every page lazily. Both of Airwallex's pagination styles are handled: page_num with has_more, and the page cursor with page_after / page_before.

Endpoints that return a bare JSON array, such as balances->current(), also come back as a Collection.

Request options

Idempotency

Airwallex uses a request_id body field as its idempotency key. The SDK adds a random UUID on the endpoints that accept one, and reuses it when it retries. Pass your own to make retries across processes safe:

Airwallex doesn't replay a reused request_id. It rejects it with duplicate_request, which the SDK throws as IdempotencyException. If you get one after a timeout or retry, the original request almost certainly succeeded, so look the resource up (e.g. by merchant_order_id) rather than creating it again.

Set 'auto_request_id' => false in the config to turn this off.

Errors

API errors throw a subclass of WPZinc\Airwallex\Exception\ApiErrorException:

Network failures throw ApiConnectionException. Every SDK exception implements ExceptionInterface.

Webhooks

Airwallex signs each delivery with HMAC-SHA256 over the x-timestamp header followed by the raw body. Verify it before trusting the event:

Webhook::constructEventFromHeaders($payload, $headers, $secret) reads the headers from an array instead (e.g. getallheaders() or a PSR-7 request). Timestamps older than 5 minutes are rejected; pass a different tolerance in seconds, or null to skip the check.

Manage webhook endpoints with $airwallex->webhooks.

Files

Uploads go to Airwallex's separate files host:

Configuration

Caching access tokens

Access tokens last 30 minutes. The default store only keeps them for the current PHP process, so a web app would otherwise log in on every request. Implement TokenStoreInterface against your cache to share tokens:

Custom HTTP client

Implement WPZinc\Airwallex\HttpClient\ClientInterface (one request() method) to send requests through Guzzle, Laravel's HTTP client, or a mock in your tests.

Endpoints the SDK doesn't wrap yet

Development

Sandbox tests

tests/Sandbox runs real requests against the Airwallex sandbox: payments, billing checkout, pagination, webhooks, file uploads and errors. Create a scoped sandbox API key, then add a .env (git-ignored):

The default composer test only runs the offline unit suite.

The service classes, resource classes and codegen/README.md.

Roadmap

• Laravel package: service provider, config, cache-backed token store, webhook route and middleware
• A Cashier-style billing package for Laravel on top of Airwallex Billing

License

MIT