Accedi

Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

Multi-currency integration

Note: The multi-currency feature is only available for merchants who have registered for an account with EUR or GBP ledger currency. Click here for the list of supported countries.

By default, you can only charge your buyer using the currency in which you receive your disbursements from Amazon Pay. 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.

Integration steps
Common integration errors
Buyer checkout experience
Supported currencies

Integration steps

There are three steps for enabling multi-currency checkout:

Set presentmentCurrency at the start of checkout
Set payment currencyCode
Set Create Charge, Capture, and Refund currencyCode

1. Set presentmentCurrency at the start of checkout

Set the presentmentCurrency value in the button createCheckoutSessionConfig.payload. This will prevent the buyer from selecting a payment instrument that wasn’t issued by either Visa or Mastercard. See Buyer checkout experience: Scenario #1 for more info.

Payload example

{
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl":"https://a.com/merchant-review-page"
    },
    "storeId":"amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "paymentDetails": {
        "presentmentCurrency":"CHF"
    }
}

2. Set payment currencyCode

Set the chargeAmount.currencyCode parameter when you Update Checkout Session 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, it will also automatically update the presentmentCurrency parameter you passed while calling Create Checkout Session and prevent the buyer from completing checkout with an unsupported payment instrument. See Buyer checkout experience: Scenario #2 for more info. Do not attempt to update the presentmentCurrency parameter directly as doing so will result in an error.

Request

curl "https://pay-api.amazon.eu/:version/checkoutSessions/:checkoutSessionId" \
-X PATCH
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-d @request_body

Request body

{
    "webCheckoutDetails": {
        "checkoutResultReturnUrl":"https://a.com/merchant-confirm-page"
    },
    "paymentDetails": {
        "paymentIntent":"Authorize",
        "canHandlePendingAuthorization":false,
        "chargeAmount": {
            "amount":"1",
            "currencyCode":"CHF"
        }
     },
    "merchantMetadata": {
        "merchantReferenceId":"Merchant reference ID",
        "merchantStoreName":"Merchant store name",
        "noteToBuyer":"Note to buyer",
        "customInformation":"Custom information"
    },
    "platformId":"SPId"
}

Sample Code

<?php

    include 'vendor/autoload.php';

    $amazonpay_config = array(
        'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
        'private_key'   => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
        'region'        => 'eu', 
        'algorithm'     => 'AMZN-PAY-RSASSA-PSS-V2'
    );
        
    $payload = array(
        'webCheckoutDetails' => array(
            'checkoutResultReturnUrl' => 'https://a.com/merchant-confirm-page'
        ),
        'paymentDetails' => array(
            'paymentIntent' => 'Authorize',
            'canHandlePendingAuthorization' => false,
            'chargeAmount' => array(
                'amount' => '1',
                'currencyCode' => 'CHF'
            )
        ),
        'merchantMetadata' => array(
            'merchantReferenceId' => 'Merchant reference ID',
            'merchantStoreName' => 'Merchant store name',
            'noteToBuyer' => 'Note to buyer',
            'customInformation' => 'Custom information'
        ),
        'platformId' => 'SPId'
    );

    try {
        $client = new Amazon\Pay\API\Client($amazonpay_config);

        $result = $client->updateCheckoutSession('ada3f397-7d4b-4a55-abac-786685c02d8b', $payload);

        if ($result['status'] === 201) {
            
            $response = json_decode($result['response'], true);
            $checkoutSessionId = $response['checkoutSessionId'];

        } else {
            // check the error
            echo 'status=' . $result['status'] . '; response=' . $result['response'];
        }
    } catch (Exception $e) {
        // handle the exception
        echo $e;
    }
?>

using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore.CheckoutSession;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;

public class Sample
{
    public WebStoreClient InitiateClient()
    {
        // set up config
        var payConfiguration = new ApiConfiguration
        (
            region: Region.Europe,
            publicKeyId: "YOUR_PUBLIC_KEY_ID",
            privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
            algorithm: AmazonSignatureAlgorithm.V2
        );

        // init API client
        var client = new WebStoreClient(payConfiguration);

        return client;
    }

    public CheckoutSessionResponse UpdateCheckoutSession(string checkoutSessionId)
    {
        // prepare the request
        var request = new UpdateCheckoutSessionRequest()
        {
            WebCheckoutDetails = {
                CheckoutResultReturnUrl = "https://a.com/merchant-confirm-page"
            },
            PaymentDetails = {
                ChargeAmount = {
                    Amount = 1.00M,
                    CurrencyCode = Currency.CHF
                },
                CanHandlePendingAuthorization = false,
                PaymentIntent = PaymentIntent.Authorize
            },
            MerchantMetadata = { 
                MerchantReferenceId = "Merchant reference ID", 
                MerchantStoreName = "Merchant store name", 
                NoteToBuyer = "Note to buyer",
                CustomInformation = "Custom information"
            },
            PlatformId = "SPId"
        };

        // send the request
        var result = client.UpdateCheckoutSession(checkoutSessionId, request);

        // check if API call was successful
        if (!result.Success)
        {
            // do something, e.g. throw an error
        }

        return result;
    }
}

import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Region;

import org.json.JSONObject;

public void sample() {
    PayConfiguration payConfiguration = null;
    try {
        payConfiguration = new PayConfiguration()
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
            .setRegion(Region.EU)
            .setPrivateKey("YOUR_PRIVATE_KEY")
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = null;
        String checkoutSessionId = "ada3f397-7d4b-4a55-abac-786685c02d8b";

        JSONObject payload = new JSONObject();
        JSONObject updateWebCheckoutDetails = new JSONObject();
        updateWebCheckoutDetails.put("checkoutResultReturnUrl", "https://a.com/merchant-confirm-page");
        payload.put("webCheckoutDetails", updateWebCheckoutDetails);

        JSONObject paymentDetails = new JSONObject();
        paymentDetails.put("paymentIntent" , "Authorize");
        paymentDetails.put("canHandlePendingAuthorization", false);

        JSONObject chargeAmount = new JSONObject();
        chargeAmount.put("amount", "1");
        chargeAmount.put("currencyCode", "CHF");
        paymentDetails.put("chargeAmount", chargeAmount);

        payload.put("paymentDetails", paymentDetails);

        JSONObject merchantMetadata = new JSONObject();
        merchantMetadata.put("merchantReferenceId", "Merchant reference ID");
        merchantMetadata.put("merchantStoreName", "Merchant store name");
        merchantMetadata.put("noteToBuyer", "Note to buyer");
        merchantMetadata.put("customInformation", "Custom information");
        payload.put("platformId", "SPId");
        payload.put("merchantMetadata", merchantMetadata);

        response = webstoreClient.updateCheckoutSession(checkoutSessionId, payload);
    } catch (AmazonPayClientException e) {
            e.printStackTrace();
    }
}

const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');

const config = {
    publicKeyId: 'YOUR_PUBLIC_KEY_ID',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'eu',
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2' 
};    
                
const payload = {
    webCheckoutDetails: {
        checkoutResultReturnUrl: "https://a.com/merchant-confirm-page"
    },
    paymentDetails: {
        paymentIntent: "Authorize",
        canHandlePendingAuthorization: false,
        chargeAmount: {
            amount: "1",
            currencyCode: "CHF"
        }
    },
    merchantMetadata: {
        merchantReferenceId: "Merchant reference ID",
        merchantStoreName: "Merchant store name",
        noteToBuyer: "Note to buyer",
        customInformation: "Custom information"
    },
    platformId: "SPId"
};
                        
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateCheckoutSession('ada3f397-7d4b-4a55-abac-786685c02d8b', payload);

response.then(function (result) {
    console.log(result.data);
}).catch(err => {
    console.log(err);
});

<?php

    include 'vendor/autoload.php';

    $amazonpay_config = array(
        'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
        'private_key'   => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
        'region'        => 'eu', 
        'sandbox'       => true,
        'algorithm'     => 'AMZN-PAY-RSASSA-PSS-V2'
    );
        
    $payload = array(
        'webCheckoutDetails' => array(
            'checkoutResultReturnUrl' => 'https://a.com/merchant-confirm-page'
        ),
        'paymentDetails' => array(
            'paymentIntent' => 'Authorize',
            'canHandlePendingAuthorization' => false,
            'chargeAmount' => array(
                'amount' => '1',
                'currencyCode' => 'CHF'
            )
        ),
        'merchantMetadata' => array(
            'merchantReferenceId' => 'Merchant reference ID',
            'merchantStoreName' => 'Merchant store name',
            'noteToBuyer' => 'Note to buyer',
            'customInformation' => 'Custom information'
        ),
        'platformId' => 'SPId'
    );

    try {
        $client = new Amazon\Pay\API\Client($amazonpay_config);

        $result = $client->updateCheckoutSession('ada3f397-7d4b-4a55-abac-786685c02d8b', $payload);

        if ($result['status'] === 201) {
            
            $response = json_decode($result['response'], true);
            $checkoutSessionId = $response['checkoutSessionId'];

        } else {
            // check the error
            echo 'status=' . $result['status'] . '; response=' . $result['response'];
        }
    } catch (Exception $e) {
        // handle the exception
        echo $e;
    }
?>

using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore.CheckoutSession;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;

public class Sample
{
    public WebStoreClient InitiateClient()
    {
        // set up config
        var payConfiguration = new ApiConfiguration
        (
            region: Region.Europe,
            environment: Environment.Sandbox,
            publicKeyId: "YOUR_PUBLIC_KEY_ID",
            privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
            algorithm: AmazonSignatureAlgorithm.V2
        );

        // init API client
        var client = new WebStoreClient(payConfiguration);

        return client;
    }

    public CheckoutSessionResponse UpdateCheckoutSession(string checkoutSessionId)
    {
        // prepare the request
        var request = new UpdateCheckoutSessionRequest()
        {
            WebCheckoutDetails = {
                CheckoutResultReturnUrl = "https://a.com/merchant-confirm-page"
            },
            PaymentDetails = {
                ChargeAmount = {
                    Amount = 1.00M,
                    CurrencyCode = Currency.CHF
                },
                CanHandlePendingAuthorization = false,
                PaymentIntent = PaymentIntent.Authorize
            },
            MerchantMetadata = { 
                MerchantReferenceId = "Merchant reference ID", 
                MerchantStoreName = "Merchant store name", 
                NoteToBuyer = "Note to buyer",
                CustomInformation = "Custom information"
            },
            PlatformId = "SPId"
        };

        // send the request
        var result = client.UpdateCheckoutSession(checkoutSessionId, request);

        // check if API call was successful
        if (!result.Success)
        {
            // do something, e.g. throw an error
        }

        return result;
    }
}

import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Environment;
import com.amazon.pay.api.types.Region;

import org.json.JSONObject;

public void sample() {
    PayConfiguration payConfiguration = null;
    try {
        payConfiguration = new PayConfiguration()
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
            .setRegion(Region.EU)
            .setPrivateKey("YOUR_PRIVATE_KEY")
            .setEnvironment(Environment.SANDBOX)
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = null;
        String checkoutSessionId = "ada3f397-7d4b-4a55-abac-786685c02d8b";

        JSONObject payload = new JSONObject();
        JSONObject updateWebCheckoutDetails = new JSONObject();
        updateWebCheckoutDetails.put("checkoutResultReturnUrl", "https://a.com/merchant-confirm-page");
        payload.put("webCheckoutDetails", updateWebCheckoutDetails);

        JSONObject paymentDetails = new JSONObject();
        paymentDetails.put("paymentIntent" , "Authorize");
        paymentDetails.put("canHandlePendingAuthorization", false);

        JSONObject chargeAmount = new JSONObject();
        chargeAmount.put("amount", "1");
        chargeAmount.put("currencyCode", "CHF");
        paymentDetails.put("chargeAmount", chargeAmount);

        payload.put("paymentDetails", paymentDetails);

        JSONObject merchantMetadata = new JSONObject();
        merchantMetadata.put("merchantReferenceId", "Merchant reference ID");
        merchantMetadata.put("merchantStoreName", "Merchant store name");
        merchantMetadata.put("noteToBuyer", "Note to buyer");
        merchantMetadata.put("customInformation", "Custom information");
        payload.put("platformId", "SPId");
        payload.put("merchantMetadata", merchantMetadata);

        response = webstoreClient.updateCheckoutSession(checkoutSessionId, payload);
    } catch (AmazonPayClientException e) {
            e.printStackTrace();
    }
}

const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');

const config = {
    publicKeyId: 'YOUR_PUBLIC_KEY_ID',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'eu',
    sandbox: true,
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2' 
};    
                
const payload = {
    webCheckoutDetails: {
        checkoutResultReturnUrl: "https://a.com/merchant-confirm-page"
    },
    paymentDetails: {
        paymentIntent: "Authorize",
        canHandlePendingAuthorization: false,
        chargeAmount: {
            amount: "1",
            currencyCode: "CHF"
        }
    },
    merchantMetadata: {
        merchantReferenceId: "Merchant reference ID",
        merchantStoreName: "Merchant store name",
        noteToBuyer: "Note to buyer",
        customInformation: "Custom information"
    },
    platformId: "SPId"
};
                        
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateCheckoutSession('ada3f397-7d4b-4a55-abac-786685c02d8b', payload);

response.then(function (result) {
    console.log(result.data);
}).catch(err => {
    console.log(err);
});

3. Set Create Charge, Capture, and Refund currencyCode

Set the respective currencyCode parameter when you Create Charge, Capture payments, and issue Refunds to match the chargeAmount.currencyCode value set during checkout. You cannot Capture or Refund in a different currency.

Common integration errors

The following errors return a HTTP 400 (Bad Request) status code and indicate that there’s an integration error.

Setting presentmentCurrency to an unsupported value

Review the supported currencies table. You will get the following error if you Create Checkout Session with an unsupported presentmentCurrency, or if you Update Checkout Session with an unsupported chargeAmount.currencyCode:

{
    "reasonCode": "InvalidParameterValue",
    "message": "The value 'RMB' provided for 'presentmentCurrency' is invalid. It is not supported."
}

Attempting to update presentmentCurrency with Update Checkout Session

Once the Checkout Session object has been created, you must use the chargeAmount.currencyCode parameter to update presentmentCurrency. You will get the following error if you attempt to update the presentmentCurrency parameter directly:

{
    "reasonCode": "InvalidParameterValue",
    "message": "presentmentCurrency cannot be updated in updateCheckoutSession request, please update ChargeAmount instead."
}

Capturing payment or issuing a refund with the wrong currency

You must Create Charge, Capture payments, and issue Refunds using the same chargeAmount.currencyCode value set during checkout. You will get the following error if you attempt to Create Charge, Capture, or Refund in a different currency:

{
    "reasonCode": "CurrencyMismatch",
    "message": "Currency code provided in [Charge/Refund] does not match the currency set during checkout"
}

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.

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