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"
}
}
}
Sample Code
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:
|
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";
?>
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);
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);
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);
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.