Multi-Currency Pricing API
Improve checkout conversion by letting customers view prices and pay in their preferred currency
The Multi-Currency Pricing API (MCP API) enables you to display prices and enable payment in your shoppers’ preferred currencies, while also letting your shoppers pay using local payment methods that wouldn’t otherwise be available in your default currency. This improves your shoppers’ experience, making them more likely to buy from you.
Supported Integration Methods
Use the MCP API if you accept payments through one of the following integration methods:
- Native API
- Drop-in Element
- Card Element
- Split Card Element
Merchants integrating via Hosted Payments Page or other methods supported by Automatic Currency Conversion should instead use Automatic Currency Conversion for their use cases.
Supported Payments
All of Airwallex’s supported settlement currencies can be used as source currencies with the MCP API.
The MCP API is applicable to all payment types supported by Airwallex, with the following exceptions:
- Subscriptions
- Payments for platforms
- Merchant-initiated transactions
Pricing and Settlement
No additional fees will be charged to your account when using the MCP API for currency conversion. Instead, a conversion fee is applied to your shoppers and is included in the FX rate when prices are displayed. During onboarding, Airwallex sets the conversion fee charged to your shoppers, typically 2-4% on top of the exchange rate.
Airwallex settles you in the original payment currency (if it’s a configured settlement currency on your account). If the original currency is not a configured settlement currency, settlement occurs in your default settlement currency, with applicable conversion fees. For more information, see settlement currencies .
For Airwallex's settlement guarantees to hold, each payment must be captured within 12 hours of the payment attempt being created. If a payment is captured after 12 hours, Airwallex may adjust the final settled amount based on the latest exchange rate.
Supported Currencies
We support 30+ shopper currencies across 40+ countries.
High Level Flow Diagram
Before going through the MCP API integration guide, review this flow diagram to understand how a full MCP API integration would work.
Integration Guide
Step 1: Query convertible shopper currencies
To give your shoppers flexibility, you can allow them to choose the currency in which they view prices and make payments. To enable this, first retrieve the list of convertible shopper currencies and display these currencies to your shoppers so they can select their preferred currency. Alternatively, you may auto-select a currency for them using criteria such as IP address or billing address. Use the API call below to get the list of supported currencies.
Request:
Response:
Step 2: Create a conversion quote
After determining the currency in which the shopper will view prices and make payments, obtain the corresponding exchange rate to display prices in that currency. The exchange rate used for customer pricing includes a margin to ensure rate certainty. Retrieve this rate using the create quote API call.
Request:
Response:
Step 3: Apply quote to payment intent
When the shopper chooses to pay in their preferred currency, follow these steps: Create a payment intent using your default currency, as you would when not using MCP. Update the payment intent to link it to the FX quote for the shopper’s selected currency. Complete the payment process as usual.
Call Update Payment Intent API to associate the payment intent with a conversion quote.
Request:
Response:
Depending on the currency selected, the available payment methods you can offer to your shoppers may change. After applying a quote to a payment intent, query the available payment methods for the target currency using Payment Method Types API to confirm which payment methods you can offer. This ensures that only available payment options are presented to your shoppers.
After you apply the quote to your payment intent and verify that only valid payment methods are displayed, you can finalize the payment using Confirm Payment Intent API. The shopper will then be charged in their preferred currency based on the conversion rate specified in the quote.
Quote invalidation and refresh
A quote can be reused by multiple payment intents, as long as it is within its validity period. We use the expires_at timestamp to mark the quote’s expiration time. Merchants need to call create quote API to refresh and replace the quote before it expires. This can be done either in real time during shopper interactions or periodically via scheduled tasks. Each quote is valid for 1 hour from the time it is created. Support for longer validity periods may be added in the future.
Whenever feasible, we encourage you to reuse an existing valid quote that matches the source and target currency for a particular payment. This will minimize latency for your shoppers.
Reset payment intent to original currency
To dissociate a quote from a payment intent and revert the payment intent to its original currency, make the following API call to update the quote with a null quote ID.
Request:
Response:
Retrieve a conversion quote
After creating a quote, you can retrieve its details anytime using Retrieve Quote. Simply provide the relevant quote ID to access the quote information.
Request:
Response:
Instructions for Drop-in Element
To use the MCP API with Drop-in Element, follow the below instructions.
Step 1: Create a quote as usual, following the instructions at Create a conversion quote .
Step 2: Create a payment intent with your default currency, and do not update the payment intent with a conversion quote.
Step 3: Create a Drop-in Element using Create Drop-in Element JS. In the options, set “quote_id” to the quote ID of the conversion quote you’d like to use to convert from your default currency to the shopper’s preferred currency. See the code sample below.
The Drop-in Element will automatically update your payment intent to apply your Quote ID. You do not need to do this separately.
Step 4: If you ever need to change the currency displayed to the shopper, simply call the Update function specifying the updated quote_id as follows.
Step 5: Proceed with checkout as usual.
Instructions for Card Element and Split Card Element
When using the MCP API with Card Element and Split Card Element, no special handling is required. The primary difference when using MCP is that, when you call the element.confirm() function, the payment intent ID you pass in as an argument should be of a payment intent that has already been associated with a conversion quote.
Calculating prices and totals
When using the MCP API, you will need to use the FX quote returned by the API to calculate and show prices to shoppers in their preferred currency. It is very important that such calculations be performed correctly and with the correct precision so that the prices shoppers see accurately reflect what they will need to pay.
To calculate the local price for a single item, follow the below steps:
- Multiply the original amount by the conversion_rate of the quote.
- Round the result using half-to-even (bankers’ rounding) to match the shopper currency’s standard number of decimal places.
To calculate prices for multiple items (i.e. when showing the total price for all items in a shopper’s cart), follow the below steps:
- Calculate the total amount using the equation round_half_even(total amount in original currency × conversion rate) to ensure consistency with AWX settlement.
- If a mismatch arises due to rounding, show a small disclaimer near the total price, explaining minor rounding differences.
See below for an edge case where a disclaimer would be helpful:
Assume FX rate = 1 USD = 1.3662 SGD, where USD is the original currency, and SGD is the shopper’s preferred currency. Then see the below example of how to correctly calculate the total value to display in SGD to the shopper:
| Shopping Cart | Price in Original Currency (USD) | Price in Target Currency (SGD) | Rounded Display (SGD) |
|---|---|---|---|
| Item A | 10.00 | 13.662 | 13.66 |
| Item B | 5.00 | 6.831 | 6.83 |
| Item C | 2.00 | 2.7324 | 2.73 |
| Total | 17.00 | 23.2254 | 23.23 |
In the above example, the correct total to display is: 17 * 1.3662 = 23.23 (rounded).
It would be incorrect to simply sum the rounded values (13.66 + 6.83 + 2.73 = 23.22), since the shopper will actually be charged 23.23.
To manage shopper expectations on this, you may want to share with your shoppers that occasional 1-cent discrepancies may appear due to rounding when paying with an alternate currency.
Refunds and chargebacks
Refunds and chargebacks are performed in the currency that the customer paid in. The MCP API does not guarantee the same exchange rate for refunds and chargebacks as was applied at the time of payment. Because the latest exchange rate is applied when issuing refunds and chargebacks, you may gain or lose revenue depending on how exchange rates have changed.
Reporting
Ensure that your reports and other system integrations can handle the change to local currency in the payment intents.
In the web app, you can view the original currency and payment amount that you submitted on a transaction level and across a range of transactions when you export your payment activity.
Regulatory and Legal Considerations
Depending upon where you conduct business, you may be subject to regulations that require you to take certain measures, such as transparently displaying the exchange rate and markup to shoppers prior to currency conversion. It is the merchant’s responsibility to be aware of such regulations and follow them. Airwallex will not review such regulations on behalf of the merchant, nor will Airwallex assume any liability for a merchant’s failure to comply with such regulations.