Adding multi-currency functionality to an existing integration

This section offers guidance for merchants that are already using Amazon Pay and want to add multi-currency functionality.


Table of contents


Introduction to multi-currency payments

Prerequisites

Please note the following prerequisites for using Amazon Pay with the multi-currency payments feature:

  • You must be able to determine the buyer's preferred presentmentCurrency.
  • You must be able to quote an item's price in the buyer's preferred presentmentCurrency.

Depending on limitations, you can determine what the buyer's preferred presentmentCurrency will be by doing one of the following:

  • Display a currency code picker and allow your buyers to select a currency.
  • Detect where the buyer is located, for example by using their device GPS info or IP address, and quote the price in the currency of the country in which the buyer resides.

Changes in the integration flow

When you add the multi-currency payments feature, there are a few changes to the integration flow:

  • You must pass the presentmentCurrency parameter when rendering the Wallet widget in order to suppress ineligible payment methods.
  • The OrderTotal.CurrencyCode passed in a SetOrderReferenceDetails API request must match the presentmentCurrency. Otherwise, a CurrencyMismatchConstraint violation appears.
  • In the Authorize, Capture, and Refund operations that follow, the CurrencyCode in the amount (AuthorizationAmount, CaptureAmount, or RefundAmount) must match the OrderTotal.CurrencyCode. Otherwise, a CurrencyMismatch error will appear.

We recommend the following best practices:

  • After the presentmentCurrency is finalized (usually after the buyer places the order), call the SetOrderReferenceDetails API with the same OrderTotal.CurrencyCode prior to calling ConfirmOrderReference.
  • Provide transparency to your international buyers by indicating where your business is set up.

Note:

  • If you need to update the presentmentCurrency of an order, you must change the presentmentCurrency in the Wallet widget by re-rendering the Wallet widget. You also must send a SetOrderReferenceDetails API call with the new OrderTotal, which matches the presentmentCurrency in the Wallet widget.
  • After confirming an order, you cannot change the presentmentCurrency.

Making changes to your integration to enable multi-currency payments

Rendering the Wallet widget with presentmentCurrency

When the buyer has signed in with his or her Amazon credentials, and has (optionally) selected a shipping address, you are ready to render the Wallet widget to provide the buyer with options for selecting a payment method.

If you are using the multi-currency payments feature, you must pass the presentmentCurrency parameter when rendering the Wallet widget in order for the buyer to check out with a preferred currency.

Element name Description
presentmentCurrency The currency that the buyer will be charged in.

Allowed values: ISO- 4217 Currency Code for the supported currency

Type: xs:string

The following code sample shows the rendering of the Wallet widget with presentmentCurrency set to EUR.


<!-- Place this code in your HTML where you want the wallet widget to appear. -->
<div id="walletWidgetDiv"></div>

<script>
window.onAmazonLoginReady = function() {amazon.Login.setClientId('YOUR-CLIENT-ID'); };
window.onAmazonPaymentsReady = function() {
  walletWidget = new OffAmazonPayments.Widgets.Wallet({
    sellerId: 'YOUR_SELLER_ID_HERE',
    scope: 'SCOPE',	
       amazonOrderReferenceId: 'ORDER_REFERENCE_ID', //the one you created before, most likely in the AddressBook widget
    onPaymentSelect: function(orderReference) {
      // Replace this code with the action that you want to perform
      // after the payment method is selected.

      // Ideally this would enable the next action for the buyer
      // including either a "Continue" or "Place Order" button.
    },
    design: {
      designMode: 'responsive'
    },
    onError: function(error) {
      // Your error handling code.
      // During development you can use the following
      // code to view error messages:
      // console.log(error.getErrorCode() + ': ' + error.getErrorMessage());
      // See "Handling Errors" for more information.
    }
  });
walletWidget.setPresentmentCurrency("EUR"); // ISO-4217 currency code, merchant is expected to enter valid list of currency supported by Amazon Pay.
walletWidget.bind("walletWidgetDiv");
};
</script>

<script async="async" 
	src='https://static-eu.payments-amazon.com/OffAmazonPayments/eur/sandbox/lpa/js/Widgets.js'>
</script>
    

You can find additional documentation describing how to integrate with the Wallet widget in the "Add the AddressBook and Wallet widgets" section of the Amazon Pay and Login with Amazon integration guide.

Backward compatibility

If you do not pass in a presentmentCurrency, the presentmentCurrency will default to your ledger currency.

Ledger currency Where the Amazon Payments merchant account is registered
GBP
  • pay.amazon.com/uk
EUR
  • pay.amazon.com/at
  • pay.amazon.com/de
  • pay.amazon.com/es
  • pay.amazon.com/fr
  • pay.amazon.com/it

Buyer with no eligible payment method

If you pass the presentmentCurrency into the Wallet widget, and the buyer does not have an eligible payment method for the specified currency, Amazon Pay will give the buyer the option to add new payment methods that are eligible.

Re-rendering the Wallet widget with a different presentmentCurrency

You must re-render the Wallet widget whenever a buyer decides to change the presentmentCurrency. This may happen in cases where your site design allows buyers to switch their preferred currency on the page where the Wallet widget is rendered. (Note that you can change the presentmentCurrency only when an order is in a Draft state.)

Setting a new presentmentCurrency with a Wallet widget variable

After initial render, you can set a new presentmentCurrency by calling the setPresentmentCurrency() function from the Wallet widget variable. After you successfully set presentmentCurrency, you must re-render the new Wallet widget, using the bind() function.

The following code sample shows re-rendering the Wallet widget with presentmentCurrency set to DKK (Danish Krone).

 
<script>
  // re-render the wallet widget after saving new currencyCode.
  walletWidget.setPresentmentCurrency("DKK").bind("walletWidgetDiv");
</script>

Error messages

When rendering the Wallet widget with an unsupported presentmentCurrency

The multi-currency payments feature supports the currencies listed in the Appendix. If you render the Wallet widget with an unsupported currency, the buyer will see an error message in the Wallet widget.

The following code sample shows the error message in the Wallet widget onError() function:

 
{
   "Error":{ 
      "Code":"CurrencyUnsupported",
      "Message":"The Value 'CNY' is unsupported currency for presentmentCurrency",
      "Type":"Sender"
   },
   "RequestId":"20da5fbd-665e-11e6-8244-ebeb998a83ae"
}

Changes in the API caused by enabling multi-currency payments

There are no input interface changes for order related APIs (SetOrderReferenceDetails, GetOrderReferenceDetails, ConfirmOrderReference, CloseOrderReference, and CancelOrderReference).

However, the OrderTotal.CurrencyCode passed into a SetOrderReferenceDetails API request must match the presentmentCurrency that is passed to the Wallet widget.

The following code sample shows a valid SetOrderReferenceDetails request (passing EUR in the request):

 
POST /OffAmazonPayments/2013-01-01 HTTP/1.1   
Content-Type: x-www-form-urlencoded   
Host: mws.amazonservices.com   
User-Agent: <Your User Agent Header>    

AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE     
&Action=SetOrderReferenceDetails
&AmazonOrderReferenceId=P01-1234567-1234567   
&OrderReferenceAttributes.OrderTotal.Amount=106   
&OrderReferenceAttributes.OrderTotal.CurrencyCode=EUR   
&OrderReferenceAttributes.PlatformId=PLATFORM_ID_HERE   
&OrderReferenceAttributes.SellerNote=Lorem%20ipsum   
&OrderReferenceAttributes.SellerOrderAttributes.SellerOrderId=5678-23   
&OrderReferenceAttributes.SellerOrderAttributes.StoreName=YOUR_STORE_NAME    
&SellerId=YOUR_SELLER_ID   
&SignatureMethod=HmacSHA256   
&SignatureVersion=2   
&Timestamp=2012-11-05T19%3A01%3A11Z   
&Version=2013-01-01   
&Signature=2RPzkOgQmDybUjk0dA54maCEXAMPLE 
    

Note that if OrderTotal.CurrencyCode does not match the presentmentCurrency passed in the Wallet widget, the merchant will get a CurrencyMismatchConstraint violation.

 
"constraints": [
   {
    "constraintID": "CurrencyMismatch",
    "description": " The currency code set in the OrderTotal (USD) doesn't match presentmentCurrency pass into wallet widget (EUR)."
   }
]

The CurrencyCode in the amount (AuthorizationAmount, CaptureAmount, or RefundAmount) for Authorize, Capture, and Refund API calls should match the OrderTotal.CurrencyCode.

The following code sample shows a valid Authorize request, with an AuthorizationAmount.CurrencyCode set to EUR:

 
POST /OffAmazonPayments/2013-01-01 HTTP/1.1   
Content-Type: x-www-form-urlencoded   
Host: mws.amazonservices.com   
User-Agent: <Your User Agent Header>    

AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE   
&Action=Authorize   
&AmazonOrderReferenceId=P01-1234567-1234567   
&AuthorizationAmount.Amount=94.50   
&AuthorizationAmount.CurrencyCode=EUR   
&AuthorizationReferenceId=test_authorize_1   
&SellerAuthorizationNote=Lorem ipsum   
&SellerId=YOUR_SELLER_ID_HERE   
&SignatureMethod=HmacSHA256   
&SignatureVersion=2   

&Timestamp=2012-10-03T19:01:11Z   

&TransactionTimeout=60   
&Version=2013-01-01   
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE

If the CurrencyCode in the amount (AuthorizationAmount, CaptureAmount, or RefundAmount) does not match the OrderTotal.CurrencyCode, you will see a 400 Bad Request error:

 
{
   "Error":{ 
      "Code":"CurrencyMismatch",
      "Message":" The currency code (GBP) passed into the request doesn't match the currency code in the OrderTotal (EUR)",
      "Type":"Sender"
   },
   "RequestId":"20da5fbd-665e-11e6-8244-ebeb998a83ae"
}
    

The new fields ConvertedAmount and ConversionRate will appear in the GetCaptureDetails and GetRefundDetails API responses when the information is ready. For details, please see the definitions for CaptureDetails and RefundDetails.

Note: The ConvertedAmount and ConversionRate will not show up in the original Capture or Refund API response. You can listen to IPN notifications (CaptureNotification or RefundNotification) instead, or poll the GetCaptureDetails or GetRefundDetails APIs for ConvertedAmount and ConversionRate.

See also