.png)
Airwallex Integration Guide
Connect Airwallex payment, transfer, payout, customer, and balance operations with enterprise systems through REST APIs and selected webhook events.
Airwallex integration options at a glance
Airwallex’s primary integration surface is its REST API, covering Customers, Payment Intents, Payment Links, Transfers, Payouts, Balance Accounts, and related financial operations. Selected products and event types provide webhook notifications for payment, payout, transfer, and account-related changes. Airwallex uses client credentials to obtain bearer access tokens, while webhook signatures should be verified separately. Some operations may be asynchronous or require polling, and file endpoints are available for selected use cases rather than as a universal attachment model. Martini can authenticate, orchestrate API calls, receive webhook events, map JSON payloads, apply financial business rules, and synchronize results with databases or enterprise applications.
| Integration point | Supported by Airwallex? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Airwallex’s main integration surface for Customers, Payment Intents, Payment Links, Transfers, Payouts, Balance Accounts, and related financial operations. | Martini workflows can consume Airwallex REST endpoints, transform requests and responses, apply business rules, and expose APIs that orchestrate Airwallex operations. |
| Webhooks / outbound callbacks | Limited | Selected payment, payout, transfer, and account-related events can notify external systems about status changes. | Martini can expose an API endpoint, verify signatures, deduplicate event IDs, and route accepted events into asynchronous workflows. |
| Authentication | Yes | Client ID and API key credentials are exchanged for a bearer access token for subsequent API requests; sandbox and production hosts may differ. | Martini stores credentials as environment secrets, calls the authentication endpoint, caches tokens, and adds bearer authorization to requests. |
| Bulk / async / batch APIs | Limited | Some financial operations may be asynchronous or require status polling, but broad bulk coverage is not universal across resources. | Martini can model submission, polling, checkpointing, and bounded retry flows after confirming the behavior of the relevant endpoint. |
| File / attachment APIs | Limited | File or document operations exist for selected Airwallex use cases and should not be assumed for every resource. | Martini can call documented file endpoints, handle required multipart or encoded payloads, and map returned file identifiers. |
| Scheduled synchronization | Yes | Periodic reconciliation can retrieve payments, transfers, payouts, balances, or other resources using pagination, timestamps, and status fields. | Martini scheduler-triggered workflows can persist checkpoints, process pages, reconcile results, and restart from the last successful point. |
| SDKs | Limited | Airwallex provides developer tooling and API documentation, but a REST implementation is generally sufficient for Martini integrations. | Martini can use standard REST calls; custom JVM-compatible logic can be added for specialized payload handling or reconciliation requirements. |
| Database access | Not confirmed | No direct customer database or analytics access mechanism is identified; integrations should use Airwallex APIs and supported exports or reporting capabilities. | Martini can persist synchronized data in an approved enterprise database, but it does not require direct Airwallex database access. |
How Airwallex exposes data and business events
Airwallex REST APIs
Airwallex documents REST APIs for payments, customers, payment links, transfers, payouts, balances, and related financial operations. Availability and operations can depend on the product, legal entity, account setup, and enabled payment methods.
Martini implementation pattern
Martini implementation pattern: a workflow obtains or refreshes an Airwallex bearer token, calls the required endpoint, validates the response, maps Airwallex JSON into an internal model, persists identifiers and statuses, and invokes downstream APIs or databases.
Implementation sequence
Airwallex Webhooks
Airwallex supports webhook notifications for selected payment, payout, transfer, and account-related events. Coverage is product- and event-specific and does not represent notification for every API state change.
Martini implementation pattern
Martini implementation pattern: expose a Martini API for the webhook, preserve the raw request when required for signature verification, acknowledge promptly, and pass the event into a workflow that deduplicates, maps, enriches, and updates downstream systems.
Implementation sequence
Airwallex Authentication
Airwallex’s documented core API pattern uses client credentials to obtain an access token, followed by bearer-token authorization on API calls. OAuth should not be assumed unless a particular product documents it.
Martini implementation pattern
Martini implementation pattern: keep client credentials in environment secrets, call the authentication endpoint, cache the token for its validity period, refresh it after expiry, and inject the bearer header into Airwallex requests.
Implementation sequence
Airwallex Reconciliation
Airwallex integrations can combine selected webhook events with timestamp or status-based polling and pagination to identify missed events, delayed transitions, and financial discrepancies.
Martini implementation pattern
Martini implementation pattern: a scheduled workflow retrieves relevant Payments, Transfers, Payouts, or Balance Accounts, resumes from a checkpoint, transforms monetary values and currencies, compares source and target states, and routes exceptions for review.
Implementation sequence
Airwallex File APIs
Airwallex provides file-related endpoints for selected document or file use cases. These operations are product-specific and should not be treated as a universal attachment model.
Martini implementation pattern
Martini implementation pattern: call the documented file endpoint, construct the required multipart or encoded payload, validate the response, and associate the returned file identifier with an internal object.
Implementation sequence
Common Airwallex integration patterns
Pattern 1: Orchestrate Payment Intents
When to use this pattern
Use this pattern when an ecommerce, sales, or customer-facing application needs to initiate payment collection through Airwallex while applying internal validation and returning payment information to the caller.
Integration direction
Example Mapping
| Airwallex Field | Canonical Field | Target Field |
|---|---|---|
| amount | paymentAmount | amount |
| currency | currencyCode | currency |
| customer_id | customerReference | customer_id |
| metadata | paymentContext | metadata |
Martini implementation pattern
A Martini API receives the payment request and workflow validation checks amount, currency, customer reference, and business approval rules. The workflow obtains an Airwallex token, creates or retrieves a Customer, creates a Payment Intent, persists the Airwallex ID, and returns the response. Unknown outcomes are reconciled before a financial request is retried.
Martini capabilities used
- APIs
- workflows
- API consumption
- data mapping
- business rules
- secrets management
- error handling
Pattern 2: Process payment and payout events
When to use this pattern
Use this pattern when downstream systems need near-real-time updates for selected Airwallex payment, transfer, or payout events without relying exclusively on polling.
Integration direction
Example Mapping
| Airwallex Field | Canonical Field | Target Field |
|---|---|---|
| event_id | sourceEventId | externalEventId |
| payment_intent_id | paymentReference | externalPaymentId |
| status | financialStatus | paymentStatus |
| amount | settlementAmount | amount |
Martini implementation pattern
Martini receives the webhook through an exposed API, verifies its signature, records the event ID, and applies idempotency checks. The workflow maps the event to the target accounting model, optionally retrieves the current Airwallex resource to resolve ordering, updates the target, and sends failures to a retry or review path.
Martini capabilities used
- APIs
- webhook consumption
- workflows
- data mapping
- idempotency rules
- error handling
- asynchronous execution
Pattern 3: Reconcile Airwallex with an ERP
When to use this pattern
Use this pattern for scheduled financial reconciliation across Payments, Transfers, Payouts, and Balance Accounts, especially where webhook coverage is partial or events may be delayed.
Integration direction
Example Mapping
| Airwallex Field | Canonical Field | Target Field |
|---|---|---|
| id | sourceTransactionId | externalReference |
| status | sourceStatus | paymentStatus |
| currency | currencyCode | documentCurrency |
| amount | sourceAmount | transactionAmount |
Martini implementation pattern
A scheduler starts a restartable workflow that retrieves paginated resources using supported filters and checkpoints. Martini normalizes financial values, compares Airwallex data with the ERP, applies rules for unmatched payments, reversed transactions, and currency discrepancies, writes valid records, and routes exceptions for investigation.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination orchestration
- data mapping
- business rules
- database persistence
- monitoring
Pattern 4: Synchronize customers and Payment Links
When to use this pattern
Use this pattern when a sales or commerce application creates customer payment experiences in Airwallex and needs to retain the generated URL and identifiers.
Integration direction
Example Mapping
| Airwallex Field | Canonical Field | Target Field |
|---|---|---|
| customer.email | customerEmail | |
| amount | paymentAmount | amount |
| currency | currencyCode | currency |
| payment_link_url | hostedPaymentUrl | paymentUrl |
Martini implementation pattern
Martini receives customer and order information, validates the requested currency and amount, maps the data to Airwallex Customer and Payment Link requests, and stores the returned URL and resource ID. Duplicate prevention uses a stable internal order reference, while later webhook events update the payment lifecycle.
Martini capabilities used
- workflows
- API consumption
- data mapping
- validation
- business rules
- webhook processing
- error handling
Applications commonly integrated with Airwallex
Airwallex can be integrated with payment, commerce, finance, and operational applications through Martini workflows and APIs. The exact objects, endpoints, and mappings depend on the Airwallex products enabled in the account and the receiving application.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize customer and payment information, initiate payment collection, and update Accounts, Opportunities, or Orders with payment status. | Salesforce → Martini → Airwallex | Expose or consume Salesforce API operations, validate the payment request, obtain an Airwallex bearer token, create or retrieve the relevant Customer or Payment Intent, and return the resulting identifier and status. Webhook workflows can propagate later status changes back to Salesforce. |
| Shopify | Coordinate checkout or payment-link experiences, reconcile orders with Airwallex transactions, and propagate payment status. | Shopify → Martini → Airwallex | Receive an order or payment request, map amount, currency, customer, and metadata fields, call Airwallex REST endpoints, and use selected Airwallex webhook events to update the commerce workflow or order status. |
| NetSuite | Reconcile Airwallex Payments, Transfers, Payouts, and balances with invoices, customers, deposits, and accounting records. | Airwallex → Martini → NetSuite | Run scheduled reconciliation workflows with pagination and date filters, map financial fields into NetSuite models, persist Airwallex identifiers, and route unmatched or discrepant transactions for review. |
| SAP S/4HANA | Send payment and settlement information into enterprise finance processes and exchange relevant customer or payment references. | Airwallex → Martini → SAP S/4HANA | Retrieve or receive Airwallex financial events, normalize currencies and statuses, apply validation rules, and call SAP APIs while recording checkpoints and failed items for controlled retry. |
| Xero | Synchronize payment, payout, and reconciliation information with accounting records. | Airwallex → Martini → Xero | Use scheduled API workflows to retrieve Airwallex financial data, transform it into Xero accounting structures, preserve source identifiers, and prevent duplicate postings through stored keys and reconciliation rules. |
| Stripe | Coordinate selected payment operations during provider migration, route payment use cases, or consolidate payment reporting. | Stripe → Martini → Airwallex | Use Martini as an orchestration layer between provider APIs, normalize payment and status models, apply routing rules, and retain provider-specific identifiers for reconciliation. This is an architectural use case rather than an implied Airwallex partnership. |
| ServiceNow | Create operational cases for failed payouts, rejected payments, reconciliation exceptions, or other financial processing issues. | Airwallex → Martini → ServiceNow | Receive Airwallex events or reconciliation exceptions, apply severity and ownership rules, and create or update ServiceNow records through its API with links to the original Airwallex resource and event. |
| Jira | Create implementation, reconciliation, or remediation tasks when Airwallex events fail processing or require manual review. | Airwallex → Martini → Jira | Route failed workflow outcomes and unresolved discrepancies into Jira, include Airwallex identifiers and diagnostic context, and update the task when the retry or remediation workflow completes. |
How to build a Airwallex integration in Martini
Objective
Establish separate sandbox and production connections using Airwallex’s client credential authentication pattern.
Instructions in Martini
- Store the client ID and API key in Martini environment secrets
- Configure the environment-specific Airwallex API host
- Request and cache bearer access tokens
- Keep credentials and signing material out of workflow payloads
Objective
Select an API, webhook, or scheduled trigger based on the required business latency and Airwallex event coverage.
Instructions in Martini
- Expose a Martini API for selected Airwallex webhook events
- Use a scheduler for reconciliation and polling
- Use an inbound application API for payment or Payment Link orchestration
- Confirm event coverage for the exact Airwallex product and event type
Objective
Call the relevant Airwallex endpoint and handle pagination, asynchronous status, and resource lookups.
Instructions in Martini
- Call the documented REST endpoint with bearer authorization
- Process all pages using the supported cursor, marker, or timestamp
- Poll asynchronous operations only at bounded intervals
- Retrieve the current resource when an event may be delayed or out of order
Objective
Coordinate Airwallex operations with validation, enrichment, persistence, and downstream calls.
Instructions in Martini
- Validate required customer, amount, currency, and reference fields
- Apply approval and routing rules before financial operations
- Persist Airwallex IDs, event IDs, and checkpoints
- Separate rapid webhook acknowledgment from longer processing when appropriate
Objective
Convert Airwallex JSON and financial values into the canonical and target application models.
Instructions in Martini
- Map Customers, Payment Intents, Payment Links, Transfers, Payouts, and Balance Accounts explicitly
- Preserve currency codes and documented monetary precision
- Translate Airwallex statuses through an explicit mapping table
- Retain unknown fields or payloads needed for audit and future schema changes
Objective
Update the target database, ERP, commerce platform, accounting application, or operational system safely.
Instructions in Martini
- Create or update the target object using the mapped model
- Store the source Airwallex identifier and processing status
- Use stable idempotency keys for supported write operations
- Route unmatched or invalid data to an exception path
Common Airwallex data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Customers | Customer profiles used by payment and account-related workflows. | Salesforce, Shopify, NetSuite, Xero, internal customer databases | Martini retrieves or creates Customers through REST workflows, maps identity and metadata fields, stores Airwallex IDs, and applies duplicate checks. |
| Payment Intents | Payment collection objects representing an attempt or process to collect funds. | Shopify, Salesforce, NetSuite, order databases | Martini validates amount and currency, creates or retrieves Payment Intents, persists request and resource identifiers, and processes later status events. |
| Payment Links | Hosted payment experiences that can be created and managed through the API. | Salesforce, Shopify, customer portals, order systems | Martini maps customer, amount, currency, metadata, and callback references, then returns or stores the generated payment URL. |
| Transfers | Movement of funds between Airwallex accounts or supported destinations. | NetSuite, SAP S/4HANA, reconciliation databases, ServiceNow | Martini initiates or retrieves Transfers where permitted, applies idempotency and approval rules, and reconciles status and amount fields. |
| Payouts | Outbound payments to beneficiaries or external recipients. | NetSuite, SAP S/4HANA, Xero, operational case systems | Martini processes selected payout events, maps status transitions, protects retries, and routes failed or unmatched payouts for review. |
| Balance Accounts | Accounts and balances used to hold and manage funds. | NetSuite, SAP S/4HANA, finance data stores, reporting systems | Martini retrieves balance information on a schedule, preserves currency and precision, and compares balances with internal ledgers. |
Authentication and security considerations
Credential and token handling
Airwallex’s core API pattern uses a client ID and API key to obtain a bearer access token. Store credentials in Martini environment secrets, separate sandbox and production configuration, cache tokens until expiry, and rotate credentials according to organizational policy.
Webhook validation
Verify Airwallex webhook signatures before processing events. Preserve the raw request body when required for verification, acknowledge valid requests promptly, and keep longer processing in a workflow.
Access control
Limit credential permissions, protect exposed Martini APIs with appropriate authentication and authorization, and avoid placing credentials or signing material in mappings, logs, or workflow payloads.
Operational considerations for Airwallex integrations
Rate limits and retries
Confirm current Airwallex limits for the relevant product. Handle 429 responses with bounded backoff and retry transient 5xx responses only when the operation is safe to repeat.
Pagination and checkpoints
Do not assume a default page contains all Customers, Payments, Transfers, or Payouts. Persist cursors, page markers, or timestamps so scheduled workflows can resume safely.
Idempotency and ordering
Use stable idempotency keys for supported financial operations and event IDs for webhook deduplication. Design for duplicate, delayed, and out-of-order events.
Financial data quality
Preserve currency codes and documented precision, avoid floating-point calculations, retain original statuses, and keep an audit trail for fees, conversions, and settlement amounts.
Schema and testing
Validate required fields, retain relevant unknown fields, treat unsupported event types safely, and test sandbox flows, retries, signature validation, reconciliation, and endpoint version changes before production deployment.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Martini provides a maintainable workflow layer for coordinating Airwallex APIs, webhook events, databases, files, queues, and enterprise applications without duplicating integration logic across scripts.
Reusable controls
Authentication, validation, mapping, idempotency, retries, checkpointing, and exception routing can be implemented consistently across payment, payout, transfer, and reconciliation workflows.
API-led integration
Martini can expose controlled APIs for payment orchestration and webhook receipt while consuming Airwallex REST endpoints behind those interfaces. This separates external contracts from vendor-specific implementation details.
Operational visibility
Workflow logging, structured error paths, persisted identifiers, and reconciliation checkpoints make financial integrations easier to monitor, troubleshoot, and evolve than isolated point-to-point scripts.
Frequently asked questions
Airwallex can be integrated through its REST APIs for Customers, Payment Intents, Payment Links, Transfers, Payouts, Balance Accounts, and related operations. Selected products and event types also provide webhook notifications. Enterprise workflows commonly combine API calls, signature-verified webhooks, scheduled reconciliation, pagination, and bearer-token authentication.
Yes. Martini can consume Airwallex REST APIs, obtain and reuse bearer access tokens, receive supported Airwallex webhook events through an exposed API, map JSON payloads, and coordinate Airwallex with databases and enterprise applications.
No. A dedicated Airwallex connector is not required. Martini can use Airwallex’s confirmed native integration mechanisms, including REST APIs, client-credential authentication, selected webhook events, and product-specific file endpoints.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Airwallex. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Airwallex, cloud infrastructure, or other third-party systems depending on subscriptions, usage, and deployment model.
Use the Airwallex REST APIs as the primary integration method. Use selected webhook events for near-real-time payment, transfer, payout, or account updates, and scheduled API reconciliation for missed events, delayed status changes, and financial completeness. File endpoints should be used only for documented product-specific use cases.
No. Airwallex supports webhook notifications for selected products and event types, not necessarily every resource or state change. The required event, payload, signature behavior, and retry model should be confirmed for the specific Airwallex product being implemented.
Martini can retrieve or receive Airwallex JSON, map actual objects such as Payment Intents, Payouts, Transfers, and Customers to canonical models, preserve identifiers and currency information, and write the result to databases or business applications. Scheduled workflows can use pagination, timestamps, status fields, and checkpoints for incremental reconciliation.
Martini can validate payloads, apply bounded retries for transient failures, handle rate limiting with backoff, and route persistent errors for review. Financial writes should use Airwallex idempotency support where documented, stable internal keys, persisted resource IDs, and a lookup-before-retry strategy when the original response is unknown.
Related Martini documentation
Workflows
Connect Airwallex to your enterprise systems
Use Martini to build secure, observable Airwallex integrations across payments, payouts, transfers, accounting, commerce, and operational workflows.