Multi-Currency Integration
By default, you can only charge your buyer using the main currency of the Amazon Pay merchant account you registered. You must enable the multi-currency feature to charge your buyer using a different supported currency.
Prerequisites:
- You must have registered your Amazon Pay account in the EU or UK.
- You must be able to determine which currency should be used to charge the buyer (presentmentCurrency).
- Amazon Pay does not provide any currency conversion functionality, you must be able to calculate the order total in the currency that the buyer will be charged in.
- 1. Integration Steps
- 2. Common integration errors
- 3. Buyer checkout experience
- 4. Supported currencies
1. Integration Steps
There are three steps for enabling multi-currency checkout:
- Set
presentmentCurrency
at the start of checkout - Update the order
presentmentCurrency
during checkout - Process payment with your acquirer in the right currency
1.1. Set presentmentCurrency at the start of checkout
Set the presentmentCurrency
value in the createCheckoutSessionConfig
parameter of the button rendering code. See Buyer checkout experience: Scenario #1 for more info.
Request
curl "https://pay-api.amazon.eu/:version/checkoutSessions/" \
-X POST
-H "x-amz-pay-idempotency-key: AVLo5tI10BHgEk2jEXAMPLEKEY"
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body
Request Body
{
"webCheckoutDetail": {
"checkoutReviewReturnUrl":"https://a.com/merchant-review-page"
},
"storeId":"amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
"paymentDetails": {
"presentmentCurrency":"CHF"
}
}
1.2. Update the order presentment currency during checkout
Set the paymentDetails.presentmentCurrency
parameter when you call Update Checkout Session (http://pay.amazon.com/) with payment details. This parameter determines the currency that will be used to charge the customer. If the currency value is different from the presentmentCurrency
previously set on button render, the API call will override the previous value. See Buyer checkout experience: Scenario #2 for more info. Do not pass a paymentDetails.totalOrderAmount
or paymentDetails.chargeAmount
with a new currency without updating the paymentDetails.presentmentCurrency
parameter.
Request
curl "https://pay-api.amazon.eu/:version/checkoutSessions/:checkoutSessionId" \
-X PATCH
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body
Request Body
{
"webCheckoutDetail": {
"checkoutResultReturnUrl":"https://a.com/merchant-confirm-page"
},
"paymentDetail": {
"paymentIntent":"Confirm",
"presentmentCurrency":"CHF",
"totalOrderAmount": {
"amount":"1",
"currencyCode":"CHF"
}
"chargeAmount": {
"amount":"1",
"currencyCode":"CHF"
}
},
"merchantMetadata": {
"merchantReferenceId":"Merchant reference ID",
"merchantStoreName":"Merchant store name",
"noteToBuyer":"Note to buyer",
"customInformation":"Custom information"
},
"platformId":"SPId"
}
1.3. Process payment with your acquirer in the right currency
When calling your acquirer to process the payment (authorization, capture and refund operations), make sure to pass the transaction amount in the same currency you passed to our API as presentmentCurrency. In case a different currency is passed to the acquirer facing API, a currency mismatch error will be returned from Amazon Pay.
2. Common integration errors
The following errors return a HTTP 400 (Bad Request) status code (https://restfulapi.net/http-status-codes/) and indicate that there’s an integration error.
2.1. Setting presentmentCurrency to an unsupported value
Review the supported currencies table at the bottom of this page. You will get the following error if you try to pass an unsupported presentmentCurrency in the button definition or the Update Checkout session API:
{
"reasonCode": "InvalidParameterValue",
"message": "The value 'RMB' provided for 'presentmentCurrency' is invalid. It is not supported."
}
2.2. Capturing payment or issuing a refund with the wrong currency
When calling your acquirer to process the payment (authorization, capture and refund operations), you must pass the transaction amount in the same currency you passed to our API as presentmentCurrency
. You will get the following error if you attempt to Authorize, Capture, or Refund in a different currency:
{
"reasonCode": "CurrencyMismatch",
"message": "Currency code provided in [Charge/Refund] does not match the currency set during checkout"
}
3. Buyer checkout experience
If a non-default checkout currency is specified as the presentmentCurrency, the buyer will only be able to successfully checkout using a payment instrument issued by either Visa or Mastercard. Amazon Pay will handle scenarios involving unsupported payment instruments in the following ways:
- Scenario #1: You auto-detect the buyer’s currency preference based on location or give buyers the ability to choose their preferred currency before they start checkout. In this scenario, a non-default currency is set at the start of checkout before the buyer has selected a payment instrument. The buyer will only be able to select either a Visa or Mastercard from their Amazon wallet.
- Scenario #2: You offer the buyer the ability to choose their preferred currency right before they complete their order. In this scenario, a non-default currency is set only after the buyer has already selected an unsupported payment instrument. Amazon Pay will prompt the buyer to select either a Visa or Master from their Amazon wallet before they can complete checkout.
- Scenario #3: If a non-default currency is set and the buyer doesn’t have a Visa or Master in their Amazon wallet, they will be given the option to add one on an Amazon Pay hosted page.
4. Supported currencies
The following is a table of supported currencies and their corresponding currency codes:
Currency
|
Currency Code
|
Australian Dollar
|
AUD
|
British Pound
|
GBP
|
Danish Krone
|
DKK
|
Euro
|
EUR
|
Hong Kong Dollar
|
HKD
|
Japanese Yen
|
JPY
|
New Zealand Dollar
|
NZD
|
Norwegian Krone
|
NOK
|
South African Rand
|
ZAR
|
Swedish Krone
|
SEK
|
Swiss Franc
|
CHF
|
United States Dollar
|
USD
|