@airwallex/developer-mcp/dist/integration-best-practices.md

MCP server for AI agents that assist developers integrating with the Airwallex platform

# Airwallex Integration Best Practices

## General

- Check how to authenticate with the API and obtain a bearer token for API authorization using the `search_public_docs` MCP tool with a suitable `source` parameter. DO NOT hallucinate or assume.
- Check how to initialise the Airwallex.js SDK using the `search_public_docs` MCP tool with a suitable `source` parameter. DO NOT hallucinate or assume.
- Unless requested explicitly by the user, always use the most recent version of the API

## Payments

- In the Airwallex APIs & SDKs, request fields related to money are NOT represented in minor units by default unless explicitly specified
- For the Javascript browser library, if the user prefers a direct integration with a CDN, use `https://static.airwallex.com/components/sdk/v1/index.js` and NOT `https://checkout.airwallex.com/assets/elements.bundle.min.js` unless explicitly requested by the user. The latter is a legacy library that is considered deprecated. When the user explicitly asks for it, advise them to consider migrating.
- For the Javascript browser library, if the user prefers to use a package from the `npm` registry with `npm`, `yarn` or the `pnpm` CLI tools, use `@airwallex/components-sdk` instead of `airwallex-payment-elements` unless explicitly requested by the user. The latter is a legacy package that is considered deprecated. When the user explicitly asks for it, advise them to consider migrating.
- For a robust and complete payments integration, always consider supporting setting up webhooks.
- If the payment integration involves redirect-style payment methods, remember to configure a return URL in your payment intent and set up a URL handler on the server for the same. In the URL handler, retrieve the payment intent and check its status. If the status is non-terminal, repeat until a terminal status is observed and decide what to do next based on that. For Drop-in element integrations, you can consider doing this by default since multiple payment methods can be accepted through that integration.