Adding multi-currency functionality to an existing automatic payments 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

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 in automatic payments, 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.
  • In AuthorizeOnBillingAgreement and CreateOrderReferenceForId operations that follow, the CurrencyCode in the amount (AuthorizationAmount/OrderAmount) must match the billing agreement presentmentCurrency. Otherwise, a CurrencyMismatch error appears.

We recommend the following best practices:

  • After the presentmentCurrency is finalized for a subscription (usually after the buyer confirms the subscription), we recommend that you save the the user_id-presentmentCurrency-billing agreement combination as any future charges on the subscription for a particular buyer can be made only in selected presentmentCurrency.
  • Provide transparency to your international buyers by indicating where your business is set up.

Notes:

  • If you need to update the presentmentCurrency of a subscription, you must change the presentmentCurrency in the Wallet widget by re-rendering the Wallet widget.
  • After confirming a subscription, you cannot change the presentmentCurrency.
  • If a card issuer already charges a foreign transaction fee to buyers who use cards issued in a different country, that foreign transaction fee might continue to apply. Such fees are independent of the currency of the transaction and vary based on the specific card's terms and conditions, as agreed between card issuer and cardholder.

Making changes to your integration to enable multi-currency payments

Rendering the Wallet widget with presentmentCurrency

After the buyer signs in with their Amazon credentials and (optionally) chooses a shipping address, you are ready to render the Wallet widget to provide the buyer with options for choosing a payment method.

If you use the multi-currency payments feature to let the buyer check out with a preferred currency, you must pass the presentmentCurrency parameter when rendering the Wallet widget .

Element name Description
presentmentCurrency
(optional) 		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 GBP.


<!--- please put the style below inside your CSS file -->
<style type="text/css">
   #walletWidgetDiv{width: 400px; height: 228px;}
</style>

<div id="walletWidgetDiv">
</div>

<script>
  walletWidget = new OffAmazonPayments.Widgets.Wallet({
    sellerId: 'YOUR_SELLER_ID_HERE',
    // amazonBillingAgreementId obtained from the AddressBook widget
    amazonBillingAgreementId: amazonBillingAgreementId,
    onPaymentSelect: function(billingAgreement) {
      // Replace this code with the action that you want to perform
      // after the payment method is selected.
    },
    design: {
      designMode: 'responsive'
    },
    onError: function(error) {
      // your error handling code
    }
  });
  walletWidget.setPresentmentCurrency("GBP"); // ISO-4217 currency code, merchant is expected to enter valid list of currency supported by Amazon Pay.
  walletWidget.bind("walletWidgetDiv");
</script>

For more details about integrating the Wallet widget, see Step 2: Add the AddressBook and Wallet widgets.

Backward compatibility

If you do not pass in a presentmentCurrency, the presentmentCurrency defaults 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/ie
  • 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 gives 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 lets buyers 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

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"
}

For a list of the currencies that the multi-currency feature supports, see Supported currencies.

Changes in the API caused by enabling multi-currency payments

There are no input interface changes for order related APIs (SetBillingAgreementDetails, GetBillingAgreementDetails, ConfirmBillingAgreement, AuthorizeOnBillingAgreement, CreateOrderReferenceForId, CloseBillingAgreement and ValidateBillingAgreement).

Output interface changes

For MCP requests, BillingAgreementLimits structure in BillingAgreementDetails response for SetBillingAgreementDetails/GetBillingAgreementDetails API will show the limit values in billing agreement presentmentCurrency.

The following code sample shows the BillingAgreementLimits structure in BillingAgreementDetails response for SetBillingAgreementDetails, GetBillingAgreementDetails API for a billing agreement with presentmentCurrency as "EUR":

 
{
  "billingAgreementDetails": { …
    "billingAgreementLimits": {
       "timePeriodEndDate": 1525132800000, 
       "amountLimitPerTimePeriod": { 
         "amount": "500", 
         "currencyCode": "EUR" }, 
       "currentRemainingBalance": { 
         "amount": "500.00", 
         "currencyCode": "EUR" } 
}

The CurrencyCode in the amount (AuthorizationAmount or OrderAmount) for AuthorizeOnBilling, and CreateOrderReferenceForId calls must match the presentmentCurrency.

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

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

AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE  
&Action=AuthorizeOnBillingAgreement  
&AmazonBillingAgreementId=B02-1234567-1234567  
&AuthorizationAmount.Amount=10  
&AuthorizationAmount.CurrencyCode=EUR  
&AuthorizationReferenceId=test_authorize_1  
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE &SellerId=YOUR_SELLER_ID_HERE 
&SellerAuthorizationNote=ForNovemberOrder  &SellerOrderAttributes.SellerOrderId=testSellerOrderId  &SellerOrderAttributes.StoreName=testStore  &SellerOrderAttributes.CustomInformation=ExampleInformation  &InheritShippingAddress=true  
&SignatureMethod=HmacSHA256  
&SignatureVersion=2  
&Timestamp=2012-10-03T19%3A01%3A11Z  
&TransactionTimeout=60  
&Version=2013-01-01  
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE

If the CurrencyCode in the amount (AuthorizationAmount or OrderAmount) does not match the presentmentCurrency that is passed to the Wallet widget, you 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 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 do 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.

BillingAgreement monthly limit

The BillingAgreement monthly limit is computed and validated based on billing agreement presentmentCurrency for AuthorizeOnBillingAgreement and CreateOrderReferenceForId. For more details about monthly limits for billing agreements, see Supported currencies and monthly limits for billing agreements.

See also