Upgrading from one-time to recurring

You can either upgrade from one-time to recurring during checkout by changing the Checkout Session chargePermissionType or create a recurring Charge Permission after checkout is complete by sending the buyer to an Amazon Pay hosted page to confirm the upgrade.


Upgrading during checkout

Use Update Checkout Session to upgrade from one-time to recurring checkout. Set chargePermissionType to Recurring and provide recurringMetadata.frequency. Note that Amazon Pay only uses the value of recurringMetadata.frequency to calculate Charge Permission expiration data and in buyer communication. You are still responsible for calling Create Charge to charge the buyer for each billing cycle.

Implement Step 5. Verify & complete checkout in the Recurring integration guide once the Checkout Session has been updated and the buyer is ready to complete checkout.

Request

Request body

{
    "chargePermissionType": "Recurring",   
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    }
}

Upgrading after checkout

You will redirect the buyer to an Amazon Pay hosted page to confirm upgrade of a one-time Charge Permission after checkout. You must provide a web page to initiate the redirect. The web page can be the “Thank you” page shown after a successful checkout or a separate page for buyers who return to your site after checkout. To upgrade the Charge Permission, you need to:

  1. Add the Amazon Pay script to your web page
  2. Generate the bindUpgradeAction payload
  3. Sign the payload
  4. Use amazon.Pay.bindUpgradeAction() to bind a click event to a HTML element
  5. Implement Step 5. Verify & complete checkout in the Recurring guide

Step 1. Add the Amazon Pay script

Add the Amazon Pay script to your web page. Be sure you select the correct region.

<script src="https://static-na.payments-amazon.com/checkout.js"></script>
<script src="https://static-eu.payments-amazon.com/checkout.js"></script>
<script src="https://static-fe.payments-amazon.com/checkout.js"></script>

Step 2. Generate the bindUpgradeAction payload

You will need to provide a payload that Amazon Pay will use to set up the upgrade experience.

Instructions for generating bindUpgradeAction payload:

  • Set chargePermissionType to Recurring
  • Set chargePermissionId with the identifier of the one-time Charge Permission used to create the recurring Charge Permission
  • Set checkoutResultReturnUrl to the URL that the buyer is redirected to after they confirm the upgrade. The Checkout Session ID will be appended as a query parameter to the provided URL.
  • Set productType to PayAndShip for physical transactions that require shipping address. The shipping address returned will be the address associated to the one-time Charge Permission. Set productType to PayOnly for digital transactions.
  • Set chargeAmount to the value that should be processed using the paymentIntent during the upgrade. Set paymentIntent to Confirm if you are not requesting any payment during the upgrade.
  • Set recurringMetadata.frequency to increase buyer confidence. Note that Amazon Pay only uses the values provided to calculate the Charge Permission expiration date and in buyer communication. You are still responsible for calling Create Charge to charge the buyer for each billing cycle.
  • Specify the buyer information you need to complete the upgrade using the scopes parameter. If you do not set this value, all buyer information will be requested.

Payload example

{  
    "merchantId":"merchant_id",
    "storeId":"amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "ledgerCurrency": "USD",
    "chargePermissionType": "Recurring", 
    "chargePermissionId":"charge_permission_id",
    "webCheckoutDetails": {
        "checkoutResultReturnUrl":"https://a.com/merchant-result-page"
    },
    "productType": "PayAndShip",
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "chargeAmount": {
            "amount": "10",
            "currencyCode": "USD"
        },
        "presentmentCurrency":"USD"
    },
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    },
    "scopes": ["name", "email", "phoneNumber", "billingAddress"]
}   

Parameter
Description
merchantId
(required)

Type: string
Amazon Pay merchant account identifier
storeId
(required)

Type: string
Amazon Pay store ID. Retrieve this value from Amazon Pay Integration Central: US, EU, JP
ledgerCurrency
(required)

Type: string
Ledger currency provided during registration for the given merchant identifier

Supported values:
  • US merchants - 'USD'
  • EU merchants - 'EUR'
  • UK merchants - 'GBP'
  • JP merchants - 'JPY'
chargePermissionType
(required)

Type: string
The type of Charge Permission to be created

Supported values:
'Recurring' - The Charge Permission can be used for recurring orders


chargePermissionId
(required)

Type: string
Identifier of the one-time Charge Permission used to create the recurring Charge Permission
recurringMetadata
(required)

Type: recurringMetadata
Metadata about how the recurring Charge Permission will be used. Amazon Pay only uses this information to calculate the Charge Permission expiration date and in buyer communication

Note that it is still your responsibility to call Create Charge to charge the buyer for each billing cycle


webCheckoutDetails
(required)

Type: webCheckoutDetails
The URL that the buyer is redirected to after they confirm the upgrade. The URL must use HTTPS protocol
productType
(required)

Type: string
Product type selected for the upgrade

Support values:
'PayAndShip' - Offer checkout using the buyer's Amazon wallet and address book. Select this product type if you need the buyer's shipping details
'PayOnly' - Offer checkout using only the buyer's Amazon wallet. Select this product type if you do not need the buyer's shipping details

Default value: 'PayAndShip'

paymentDetails
(required)

Type: paymentDetails
Payment details specified by the merchant, such as the amount and method for charging the buyer
checkoutLanguage

Type: string
Language used to render the text on Amazon Pay hosted pages. Please note that supported language(s) is dependent on the region that your Amazon Pay account was registered for.

Supported values:
US merchants - 'en_US'
EU/UK merchants - 'en_GB', de_DE', 'fr_FR', 'it_IT', 'es_ES'
JP merchants - 'ja_JP'
scopes

Type: list<scope>
The buyer details that you're requesting access to. Specify whether you need shipping address using productType.

Supported values:
'name' - buyer name
'email' - buyer email address
'phoneNumber' - buyer default billing address phone number
'billingAddress' - buyer default billing address

Default value: all buyer information is requested if the scopes parameter is not set

Step 3. Sign the payload

You must secure the payload using a signature. The payload does not include a timestamp so you can re-use the signature as long as the payload does not change.

Option 1 (recommended): Generate a signature using the helper function provided in the Amazon Pay SDKs.

<?php
    include 'vendor/autoload.php';

    $amazonpay_config = array(
        'public_key_id' => 'MY_PUBLIC_KEY_ID',
        'private_key'   => 'keys/private.pem',
        'region'        => 'US',
        'sandbox'       => true
    );

    $client = new Amazon\Pay\API\Client($amazonpay_config);
    $payload = '{"merchantId":"merchant_id","storeId":"amzn1.application-oa2-client.xxxxx","ledgerCurrency":"USD","webCheckoutDetails":{"checkoutResultReturnUrl":"https://example.com/result.html"},"chargePermissionType":"Recurring","chargePermissionId":"P01-1111111-1111111","productType":"PayAndShip","paymentDetails":{"paymentIntent":"AuthorizeWithCapture","chargeAmount":{"amount":"10","currencyCode":"USD"},"presentmentCurrency":"USD"},"recurringMetadata":{"frequency":{"unit":"Month","value":"1"},"amount":{"amount":"30","currencyCode":"USD"}},"scopes":["name","email","phoneNumber","billingAddress"]}';
    $signature = $client->generateButtonSignature($payload);
    echo $signature . "\n";
?>

Source code

var payConfiguration = new ApiConfiguration
(
    region: Region.Europe,
    environment: Environment.Sandbox,
    publicKeyId: "MY_PUBLIC_KEY_ID",
    privateKey: "PATH_OR_CONTENT_OF_MY_PRIVATE_KEY"
);

var client = new WebStoreClient(payConfiguration);

var payload = "{'merchantId':'merchant_id','storeId':'amzn1.application-oa2-client.xxxxx','ledgerCurrency':'USD','webCheckoutDetails':{'checkoutResultReturnUrl':'https://example.com/review.html'},'chargePermissionType':'Recurring','chargePermissionId':'P01-1111111-1111111','productType':'PayAndShip','paymentDetails':{'paymentIntent':'AuthorizeWithCapture','chargeAmount':{'amount':'10','currencyCode':'USD'},'presentmentCurrency':'USD'},'recurringMetadata':{'frequency':{'unit':'Month','value':'1'},'amount':{'amount':'30','currencyCode':'USD'}},'scopes':['name','email','phoneNumber','billingAddress']}";

// generate the button signature
var signature = client.GenerateButtonSignature(payload);

Source code

PayConfiguration payConfiguration = null;
try {
    payConfiguration = new PayConfiguration()
                .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
                .setRegion(Region.YOUR_REGION_CODE)
                .setPrivateKey("YOUR_PRIVATE_KEY_STRING")
                .setEnvironment(Environment.SANDBOX);
}catch (AmazonPayClientException e) {
    e.printStackTrace();
}

AmazonPayClient client = new AmazonPayClient(payConfiguration);

String payload = "{\"merchantId\":\"merchant_id\",\"storeId\":\"amzn1.application-oa2-client.xxxxxx\",\"ledgerCurrency\":\"USD\",\"webCheckoutDetails\":{\"checkoutResultReturnUrl\":\"https://example.com/result.html\"},\"chargePermissionType\":\"Recurring\",\"chargePermissionId\":\"P01-1111111-1111111\",\"productType\":\"PayAndShip\",\"paymentDetails\":{\"paymentIntent\":\"AuthorizeWithCapture\",\"chargeAmount\":{\"amount\":\"10\",\"currencyCode\": \"USD\"},\"presentmentCurrency\":\"USD\"},\"recurringMetadata\":{\"frequency\":{\"unit\":\"Month\",\"value\":\"1\"},\"amount\":{\"amount\":\"30\",\"currencyCode\":\"USD\"}},\"scopes\": [\"name\",\"email\",\"phoneNumber\",\"billingAddress\"]}";
String signature = client.generateButtonSignature(payload);


Source code

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

const config = {
    publicKeyId: 'ABC123DEF456XYZ',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'us',
    sandbox: true
};

const testPayClient = new Client.AmazonPayClient(config);
const payload = {
    "merchantId": "merchant_id",
    "webCheckoutDetails": {
        "checkoutResultReturnUrl": "https://example.com/result.html"
    },
    "storeId": "amzn1.application-oa2-client.xxxxx",
    "ledgerCurrency":"USD",
    "chargePermissionType": "Recurring",   
    "chargePermissionId": "P01-1111111-1111111",
    "productType": "PayAndShip",
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "chargeAmount": {
            "amount": "10",
            "currencyCode": "USD"
        },
        "presentmentCurrency":"USD"
    },
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    },
    "scopes": ["name", "email", "phoneNumber", "billingAddress"]
};
const signature = testPayClient.generateButtonSignature(payload);

Source code

Option 2: Build the signature manually by following steps 2 and 3 of the signing requests guide.

Step 4. Use amazon.Pay.bindUpgradeAction() to bind a click event to a HTML element

Use the values from the previous two steps to bind a click event to a HTML element. When the buyer clicks on the HTML element, they will be redirected to an Amazon Pay hosted page to confirm the upgrade.

<script type="text/javascript" charset="utf-8">
  amazon.Pay.bindUpgradeAction('#changeButton1', {
    payloadJSON: 'payload', // string generated in step 2
    signature: 'xxxx', // signature generated in step 3 
    publicKeyId: 'xxxxxxxxxx',
    upgradeAction: 'recurringUpgrade'
  });
</script>

Step 5. Implement Step 5. Verify & complete checkout in the Recurring guide

The buyer will be redirected to checkoutResultReturnUrl after they confirm the upgrade. You must follow Step 5. Verify & complete checkout in the Recurring integration guide to complete the upgrade.