Manage recurring payments

[Step 6 of 9] After the buyer has successfully completed checkout, the Complete Checkout Session response will include a ChargePermissionId for a recurring Charge Permission object that you can use to charge the subscriber and manage cancellations.

At the end of this step, you will be able to charge the buyer at a recurring cadence and manage cancellations.

1. Recurring charges and handling declines
2. Managing cancellations

1. Recurring charges and handling declines

Call Create Charge each time you need to charge the subscriber. Set CaptureNow to true to capture payment immediately, set it to false to capture later. Note that Amazon Pay limits how much you can charge the buyer for each calendar month, see monthly recurring charge limits for more info.

If Create Charge returns a 201 response, authorization was either successfully completed or successfully initiated depending on whether canHandlePendingAuthorization was set to true. If Create Charge returns a different HTTP status code, check the request response reasonCode to determine if you should retry Create Charge or ask your buyer to use a different payment method:

If reasonCode is SoftDeclined or ProcessingFailure:
1. Call Get Charge Permission to confirm that the Charge Permission is in a Chargeable state
2. Call Create Charge to charge the buyer
If reasonCode is HardDeclined, ask the buyer to update their payment instrument using the following link: https://payments.amazon.com/jr/your-account/ba/{ChargePermissionId}. Replace {ChargePermissionId} with the buyer's Charge Permission Id. Set up IPNs to receive a notification once the payment instrument has been updated and then:
1. Call Get Charge Permission to confirm that the Charge Permission is in a Chargeable state
2. Call Create Charge to charge the buyer
For all other reasonCode, reengage the buyer and ask them to go through checkout again with a different payment method

Request


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

-X POST

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

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

-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"

-d @request_body


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

-X POST

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

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

-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"

-d @request_body

Request body

{
    "chargePermissionId": "P21-1111111-1111111",
    "chargeAmount": {
        "amount": "14.00",
        "currencyCode": "USD"
    },
    "captureNow": true, // default is false
    "softDescriptor": "Descriptor",
    "canHandlePendingAuthorization": false //default is false
}

Request parameters

Name	Location	Description
x-amz-pay-idempotency-key (required) Type: string	Header	Idempotency key to safely retry requests
chargePermissionId (required) Type: string	Body	Charge Permission identifier
chargeAmount (required) Type: price	Body	Transaction amount
captureNow Type: boolean	Body	Boolean that indicates whether or not Charge should be captured immediately after a successful authorization Default: false
softDescriptor Type: string	Body	Description shown on the buyer payment instrument statement. You can only use this parameter if `CaptureNow` is set to true Do not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>" Default: "AMZ*<SELLER_NAME> pay.amazon.com" Max length: 16 characters
canHandlePendingAuthorization Type: boolean	Body	Boolean that indicates whether or not merchant can handle pending response If set to false, you will receive a response within a maximum of 15 seconds in US, EU, and UK regions or 30 seconds in JP region. If set to true, Amazon Pay will process the authorization asynchronously and you will receive a response within 24 hours. See asynchronous processing for more info
merchantMetadata Type: merchantMetadata	Body	Merchant-provided order details
providerMetadata Type: providerMetadata	Body	Payment service provider (PSP)-provided order details Only PSPs should use these fields

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(
        'chargePermissionId' => 'S01-5105180-3221187',
        'chargeAmount' => array(
            'amount' => '14.00',
            'currencyCode' => 'USD'
        ),
        'captureNow' => true,
        'softDescriptor' => 'Descriptor',
        'canHandlePendingAuthorization' => false 
    );

    $headers = array('x-amz-pay-Idempotency-Key' => uniqid());

    try {
        $client = new Amazon\Pay\API\Client($amazonpay_config);
        $result = $client->createCharge($payload, $headers);
        
        if ($result['status'] === 201) {
            $response = json_decode($result['response'], true);
            $chargeState = $response['statusDetails']['state'];
            $chargeId = $response['chargeId'];

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

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

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 void CreateCharge(string chargePermissionId)
    {
        // prepare the request
        var request = new CreateChargeRequest(chargePermissionId, 14.00M, Currency.USD)
        {
            CaptureNow = true,
            SoftDescriptor = "Descriptor", // This is the information shown on buyer payment instrument statement
            CanHandlePendingAuthorization = false
        };

        // init Headers
        var myHeaderKey = "x-amz-pay-idempotency-key";
        var myHeaderValue = Guid.NewGuid().ToString();
        var headers = new Dictionary<string, string> { { myHeaderKey,  myHeaderValue } };

        // send the request
        ChargeResponse result = client.CreateCharge(request, headers);

        // check if API call was successful
        if (!result.Success)
        {
            // handle the API error (use Status field to get the numeric error code)
        } else {
            // do something with the result, for instance:
            string chargeId = result.ChargeId;
            DateTime chargeCreationTimestamp = result.CreationTimestamp;
            DateTime chargeExpiryTimestamp = result.ExpirationTimestamp;
        }
    }
}

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;

// for generating an idempotency key
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
 
public void sample() {
    PayConfiguration payConfiguration = null;
    try {
        payConfiguration = new PayConfiguration()
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
            .setRegion(Region.YOUR_REGION_CODE)
            .setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = null;

        JSONObject payload = new JSONObject();
        JSONObject chargeAmount = new JSONObject();
        chargeAmount.put("amount", "14.00");
        chargeAmount.put("currencyCode", "USD");

        payload.put("chargePermissionId", "S01-5105180-3221187");
        payload.put("chargeAmount", chargeAmount);
        payload.put("captureNow", true);
        payload.put("softDescriptor", "Descriptor");
        payload.put("canHandlePendingAuthorization", false);

        Map<String, String> header = new HashMap<String, String>();
        header.put("x-amz-pay-idempotency-key", UUID.randomUUID().toString().replace("-", ""));

        response = webstoreClient.createCharge(payload, header);
    } catch (AmazonPayClientException e) {
            e.printStackTrace();
    }
}

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

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 = {
    chargePermissionId: "S01-5105180-3221187",
    chargeAmount: {
        amount: "14.00",
        currencyCode: "USD"
    },
    captureNow: true,
    softDescriptor: "Descriptor",
    canHandlePendingAuthorization: false
};
                        
const headers = {
    'x-amz-pay-idempotency-key': uuidv4().toString().replace(/-/g, '')
};
                
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.createCharge(payload, headers);

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(
        'chargePermissionId' => 'S01-5105180-3221187',
        'chargeAmount' => array(
            'amount' => '14.00',
            'currencyCode' => 'USD'
        ),
        'captureNow' => true,
        'softDescriptor' => 'Descriptor',
        'canHandlePendingAuthorization' => false 
    );

    $headers = array('x-amz-pay-Idempotency-Key' => uniqid());

    try {
        $client = new Amazon\Pay\API\Client($amazonpay_config);
        $result = $client->createCharge($payload, $headers);
        
        if ($result['status'] === 201) {
            $response = json_decode($result['response'], true);
            $chargeState = $response['statusDetails']['state'];
            $chargeId = $response['chargeId'];

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

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

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 void CreateCharge(string chargePermissionId)
    {
        // prepare the request
        var request = new CreateChargeRequest(chargePermissionId, 14.00M, Currency.USD)
        {
            CaptureNow = true,
            SoftDescriptor = "Descriptor", // This is the information shown on buyer payment instrument statement
            CanHandlePendingAuthorization = false
        };

        // init Headers
        var myHeaderKey = "x-amz-pay-idempotency-key";
        var myHeaderValue = Guid.NewGuid().ToString();
        var headers = new Dictionary<string, string> { { myHeaderKey,  myHeaderValue } };

        // send the request
        ChargeResponse result = client.CreateCharge(request, headers);

        // check if API call was successful
        if (!result.Success)
        {
            // handle the API error (use Status field to get the numeric error code)
        } else {
            // do something with the result, for instance:
            string chargeId = result.ChargeId;
            DateTime chargeCreationTimestamp = result.CreationTimestamp;
            DateTime chargeExpiryTimestamp = result.ExpirationTimestamp;
        }
    }
}

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;

// for generating an idempotency key
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
 
public void sample() {
    PayConfiguration payConfiguration = null;
    try {
        payConfiguration = new PayConfiguration()
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
            .setRegion(Region.YOUR_REGION_CODE)
            .setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
            .setEnvironment(Environment.SANDBOX)
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = null;

        JSONObject payload = new JSONObject();
        JSONObject chargeAmount = new JSONObject();
        chargeAmount.put("amount", "14.00");
        chargeAmount.put("currencyCode", "USD");

        payload.put("chargePermissionId", "S01-5105180-3221187");
        payload.put("chargeAmount", chargeAmount);
        payload.put("captureNow", true);
        payload.put("softDescriptor", "Descriptor");
        payload.put("canHandlePendingAuthorization", false);

        Map<String, String> header = new HashMap<String, String>();
        header.put("x-amz-pay-idempotency-key", UUID.randomUUID().toString().replace("-", ""));

        response = webstoreClient.createCharge(payload, header);
    } catch (AmazonPayClientException e) {
            e.printStackTrace();
    }
}

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

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 = {
    chargePermissionId: "S01-5105180-3221187",
    chargeAmount: {
        amount: "14.00",
        currencyCode: "USD"
    },
    captureNow: true,
    softDescriptor: "Descriptor",
    canHandlePendingAuthorization: false
};
                        
const headers = {
    'x-amz-pay-idempotency-key': uuidv4().toString().replace(/-/g, '')
};
                
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.createCharge(payload, headers);

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

Response

{
     "chargeId": "S01-5105180-3221187-C056351",
     "chargePermissionId": "S01-5105180-3221187",
     "chargeAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "Descriptor",
     "merchantMetadata": null,
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetails":{
         "state": "Captured",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z",
     "releaseEnvironment": "Sandbox"
}

2. Managing cancellations

Use Close Charge Permission to inform Amazon Pay if a subscriber cancels their subscription. You will no longer be able to charge a subscriber unless they complete Amazon Pay checkout again once you close the Charge Permission.

Subscribers can also close Charge Permissions by signing in to https://pay.amazon.com. Set up IPNs to receive notifications whenever a Charge Permission is closed. To minimize churn, we recommend that you proactively reach out to the subscriber for a new payment method before the next billing cycle.