Build integrations with Developer MCP

Best practices, tools reference, and troubleshooting for the Airwallex Developer MCP server

To get the most out of the Airwallex Developer MCP server, follow the best practices below, explore the available tools, and refer to the troubleshooting guidance if you encounter issues.

Follow best practices

Apply these practices when working with your AI coding assistant to improve the accuracy and relevance of responses.

Always mention "Airwallex" in your prompts

When asking your coding assistant about Airwallex products, APIs, or integrations, explicitly mention "Airwallex" in your prompt. This helps the model select the appropriate MCP server and tools.

Examples:

Integrate Airwallex's Drop-in Element with this website.
Using Airwallex, can you find me test card numbers for the 3D Secure (3DS) authentication failure case?
I tried to make a payout with Airwallex and got this error: amount_below_transfer_method_limit. What does that mean?

Clarify your business and technical context

Providing context upfront helps the model return more targeted, accurate responses. Include the following in your prompt where relevant:

What you're building: for example, online payments (HPP or Embedded Elements), payouts, issuing, or billing subscriptions.
Your tech stack: for example, React, Node.js, Java, or PHP.
Your environment: sandbox or production. Note that MCP sandbox tools only operate in the sandbox environment.

Use plan mode

Enable plan mode for complex tasks. This allows you to review the agent's planned actions before execution, ensuring you understand and approve each step of the implementation.

If you're using Cursor, you can activate plan mode in either of the following ways:

Select Plan from the agent mode dropdown in Cursor's composer.
Mention it explicitly in your prompt (for example, "Using plan mode, help me integrate Airwallex Embedded Elements").

Be specific with your requirements

Provide detailed context about your use case, including the specific Airwallex product or feature you're working with, your preferred programming language and framework, the environment (sandbox or production), and any specific business requirements or constraints.

Leverage sandbox credentials

Configure your sandbox API credentials to unlock additional MCP tools for testing and simulation. With sandbox credentials, the agent can:

Create test transactions and billing plans.
Simulate transfer status updates.
Generate payment links for testing.
Interact with your sandbox account directly.

This enables end-to-end development and testing workflows without leaving your coding environment.

Example:

Can you create a new billing plan on Airwallex called Startup for $29.99/month and create a hosted URL to subscribe to it?

Review available tools

The Developer MCP server provides different tools depending on which endpoint or deployment you use:

Tool category	`/developer` endpoint	`/docs` endpoint	Local server
Documentation tools
Sandbox tools
Billing tools

Documentation tools

Available on: /developer endpoint, /docs endpoint, and local server.

Name	Description
`search_public_docs`	Search the Airwallex documentation. Covers the following sources: Product docs, API reference API, Airwallex.js JS, Payments iOS and Android SDKs
`read_integration_best_practices`	Read Airwallex integration best practices. This tool provides essential guidelines for API usage, payment handling, SDK implementation, and common pitfalls to avoid. Called automatically before code generation tasks.

Sandbox tools

Available on: /developer endpoint and local server.

All data retrieved and actions performed with the tools below are in the authenticated sandbox account.

Core Resources

Name	Description
`list_global_accounts`	List all available global accounts
`get_balances`	List balances in all currencies
`list_deposits`	List all deposits
`simulate_create_deposit`	Simulate a deposit to an available global account
`list_linked_accounts`	List all linked accounts
`create_linked_account`	Create a linked account with mandate for direct debit (supports AU, CA, EU, GB, NZ, US banks)
`verify_micro_deposits`	Confirm the linked bank account is usable and owned by the user: submit the micro-deposit amounts credited to that account. In sandbox, use values such as `0.01` and `0.02`.
`simulate_mandate_operation`	Simulate direct debit mandate status transitions (only needed for GB bank)
`list_direct_debits`	List all direct debit transactions
`create_direct_debit_deposit`	Create a direct debit deposit to pull funds from a verified linked account

Transactional FX

Name	Description
`get_fx_rate`	Get current foreign exchange rate for a currency pair
`create_fx_quote`	Create a foreign exchange quote for a currency conversion

Payouts

Name	Description
`list_transfers`	List transfers initiated
`create_transfer`	Initiate a new transfer to a recipient
`simulate_transfer_result`	Simulate the status of a transfer
`list_beneficiaries`	List available transfer recipients

Payment Acceptance

Name	Description
`list_payment_customers`	List all payment customers
`create_payment_customer`	Create a payment customer
`list_payment_intents`	List all payment intents
`create_payment_link`	Create a new payment link
`list_payment_links`	List created payment links
`list_payment_consents`	List all payment consents
`list_refunds`	List all refunds
`create_refund`	Create a refund against a PaymentIntent or PaymentAttempt
`list_payment_disputes`	List all payment disputes
`simulate_create_payment_dispute`	Simulate creating a payment dispute for testing dispute handling
`accept_payment_dispute`	Accept a payment dispute
`challenge_payment_dispute`	Challenge a payment dispute by providing reason and evidence
`simulate_escalate_payment_dispute`	Simulate escalating dispute to next stage
`simulate_resolve_payment_dispute`	Simulate issuing bank's final decision

Issuing

Name	Description
`list_cardholders`	List all cardholders
`create_cardholder`	Create a cardholder
`list_cards`	List all issued cards
`create_card`	Create a card with authorization controls and spending limits
`list_issuing_transactions`	List all card transactions
`simulate_create_issuing_transaction`	Simulate a card transaction
`simulate_capture_issuing_transaction`	Simulate capturing a pending authorization transaction
`simulate_reverse_issuing_transaction`	Simulate reversing a pending authorization transaction
`simulate_refund_issuing_transaction`	Simulate refunding a captured card transaction

Billing tools

Available on: local server only.

All data retrieved and actions performed with the tools below are in the authenticated sandbox account.

Name	Description
`list_billing_products`	List available billing products
`list_billing_prices`	List available billing prices
`create_billing_product`	Create a new billing product
`create_billing_price`	Create a new billing price
`create_billing_checkout`	Create a new hosted billing checkout page

Troubleshoot common issues

If you encounter problems connecting or authenticating, use the guidance below to diagnose and resolve them.

Sandbox API credentials are not working

Confirm you are using credentials from the sandbox environment, not production.
In local mode, verify that the AIRWALLEX_SANDBOX_CLIENT_ID and AIRWALLEX_SANDBOX_API_KEY values in your MCP config are correct and have not been truncated.

This error occurs when the OAuth token used by the /developer endpoint has expired or was not completed.

Re-run the one-click installation or OAuth flow for your tool.
Complete the authorization within a few minutes of starting the flow — tokens expire quickly.
Confirm you are authorizing with the sandbox account you intend to use.

Troubleshoot an API error

Paste the error message directly into your AI coding assistant and ask it to help diagnose the issue. For example:

Using Airwallex MCP, I got this error when creating a payment intent: [error message]. Please help me troubleshoot.

The assistant will use Airwallex documentation and the request context to provide troubleshooting steps.

Was this page helpful?