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
Upgrading after checkout

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


curl "https://pay-api.amazon.com/:version/checkoutSessions/:checkoutSessionId" \

-X PATCH

-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

-H "x-amz-pay-date:20201012T235046Z"

-d @request_body


curl "https://pay-api.amazon.com/:environment/:version/checkoutSessions/:checkoutSessionId" \

-X PATCH

-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

-H "x-amz-pay-date:20201012T235046Z"

-d @request_body

Request body

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

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'        => 'YOUR_REGION_CODE',
        'algorithm'     => 'AMZN-PAY-RSASSA-PSS-V2'
    );
        
    $payload = array(
        'chargePermissionType' => 'Recurring',
        'recurringMetadata' => array(
            'frequency' => array(
                'unit' => 'Month',
                'value' => '1'
            ),
            'amount' => array(
                'amount' => '30',
                'currencyCode' => 'USD'
            )
        )
    );

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

        $result = $client->updateCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275', $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.YOUR_REGION_CODE,
            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()
        {
            ChargePermissionType = ChargePermissionType.Recurring,
            RecurringMetadata = {
                Frequency = {
                    Unit = FrequencyUnit.Month,
                    Value = 1
                }
                Amount = {
                    Amount = 30,
                    CurrencyCode = Currency.USD
                }
            }
        };

        // 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.YOUR_REGION_CODE)
            .setPrivateKey("YOUR_PRIVATE_KEY")
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = null;
        String checkoutSessionId = "bd504926-f659-4ad7-a1a9-9a747aaf5275";

        JSONObject payload = new JSONObject();
        payload.put("chargePermissionType", "Recurring");

        JSONObject recurringMetadata = new JSONObject();

        JSONObject frequency = new JSONObject();
        frequency.put("unit","Month");
        frequency.put("value","1");
        recurringMetadata.put("frequency", frequency);

        JSONObject amount = new JSONObject();
        amount.put("amount","30");
        amount.put("currencyCode","USD");
        recurringMetadata.put("amount", amount);

        payload.put("recurringMetadata", recurringMetadata);

        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: 'YOUR_REGION_CODE',
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2' 
};    
                
const payload = {
    chargePermissionType: "Recurring",
    recurringMetadata: {
        frequency: {
            unit: "Month",
            value: "1"
        },
        amount: {
            amount: "30",
            currencyCode: "USD"
        }
    }
};
                        
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275', 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'        => 'YOUR_REGION_CODE',
        'sandbox'       => true,
        'algorithm'     => 'AMZN-PAY-RSASSA-PSS-V2'
    );
        
    $payload = array(
        'chargePermissionType' => 'Recurring',
        'recurringMetadata' => array(
            'frequency' => array(
                'unit' => 'Month',
                'value' => '1'
            ),
            'amount' => array(
                'amount' => '30',
                'currencyCode' => 'USD'
            )
        )
    );

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

        $result = $client->updateCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275', $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.YOUR_REGION_CODE,
            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()
        {
            ChargePermissionType = ChargePermissionType.Recurring,
            RecurringMetadata = {
                Frequency = {
                    Unit = FrequencyUnit.Month,
                    Value = 1
                }
                Amount = {
                    Amount = 30,
                    CurrencyCode = Currency.USD
                }
            }
        };

        // 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.YOUR_REGION_CODE)
            .setPrivateKey("YOUR_PRIVATE_KEY")
            .setEnvironment(Environment.SANDBOX)
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = null;
        String checkoutSessionId = "bd504926-f659-4ad7-a1a9-9a747aaf5275";

        JSONObject payload = new JSONObject();
        payload.put("chargePermissionType", "Recurring");

        JSONObject recurringMetadata = new JSONObject();

        JSONObject frequency = new JSONObject();
        frequency.put("unit","Month");
        frequency.put("value","1");
        recurringMetadata.put("frequency", frequency);

        JSONObject amount = new JSONObject();
        amount.put("amount","30");
        amount.put("currencyCode","USD");
        recurringMetadata.put("amount", amount);

        payload.put("recurringMetadata", recurringMetadata);

        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: 'YOUR_REGION_CODE',
    sandbox: true,
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2' 
};    
                
const payload = {
    chargePermissionType: "Recurring",
    recurringMetadata: {
        frequency: {
            unit: "Month",
            value: "1"
        },
        amount: {
            amount: "30",
            currencyCode: "USD"
        }
    }
};
                        
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275', payload);

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

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:

Add the Amazon Pay script to your web page
Generate the bindUpgradeAction payload
Sign the payload
Use amazon.Pay.bindUpgradeAction() to bind a click event to a HTML element
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 except billing address 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 phone number. You must also request `billingAddress` scope or use `payAndShip` productType to retrieve the billing address or shipping address phone number. 'billingAddress' - buyer default billing address Default value: all buyer information except billing address 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,
        'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
    );

    $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",
    algorithm: AmazonSignatureAlgorithm.V2
);

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)
                .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
}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,
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};

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.