Charge Permission

A Charge Permission object represents buyer consent to be charged. You can either request a one-time or a recurring Charge Permission object.

You can use a one-time Charge Permission to capture up to the total order amount while the Charge Permission is in a Chargeable state. You should review the reason code to determine why you can’t charge the buyer if the Charge Permission is in a Non-Chargeable state. The one-time Charge Permission will move to a Closed state after the total order amount has been captured, if it’s canceled, or it expires after 180 days.

You can use a recurring Charge Permission to charge the buyer on a recurring basis while the Charge Permission is in a Chargeable state. You should review the reason code to determine why you can’t charge the buyer if the Charge Permission is in a Non-Chargeable state. The recurring Charge Permission will move to a Closed state after if it’s canceled or after the expiration date.

You can use either Charge Permission types to retrieve relevant checkout details needed to complete the order(s) such as buyer name, buyer email, and shipping address. Note that for one-time Charge Permissions, you can only retrieve buyer details in the first 30 days after the time the Charge Permission was created. For recurring Charge Permissions, you can retrieve buyer details while the Charge Permission is in an Open State or for up to 30 days after the Charge Permission is closed.

Supported operations:


Charge Permission object

Parameter
Description
chargePermissionId

Type: string
Charge Permission identifer

This value is returned at the end of a completed Checkout Session
chargePermissionType

Type: string
The type of Charge Permission requested

Supported values:
  • 'OneTime' - The Charge Permission can only be used for a single order
  • 'Recurring' - The Charge Permission can be used for recurring orders
Default value: 'OneTime"
recurringMetadata

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
limits

Type: limits
Charge Permission transaction limits
releaseEnvironment

Type: string
Amazon Pay environment

Possible values: live, sandbox
buyer

Type: buyer
Details about the buyer, such as their unique identifer, name, and email
shippingAddress

Type: address
Shipping address selected by the buyer
billingAddress

Type: address
Billing address for payment instrument selected by the buyer
paymentPreferences

Type: list<paymentPreference>
List of payment instruments selected by the buyer
merchantMetadata

Type: merchantMetadata
Merchant-provided order details
platformId

Type: string
Merchant identifer of the Solution Provider (SP)

Only SPs should use this field
creationTimestamp

Type: dateTime
UTC date and time when the Charge Permssion was created in ISO 8601 format
expirationTimestamp

Type: dateTime
UTC date and time when the Charge Permission will expire in ISO 8601 format

One-time Charge Permissions expire 180 days after they are confirmed

By default, recurring Charge Permissions expire 13 months after they are confirmed. Creating a charge will reset the expiration date to 13 months. If recurringMetadata.Frequency is set to a billing cycle longer than 13 months, the expiration date will be extended to the value of recurringMetadata.Frequency plus one month
statusDetails

Type: statusDetails
State of the Charge Permission object
presentmentCurrency

Type: string
The currency that the buyer will be charged in ISO 4217 format. Example: USD

See multi-currency integration for more info

Type: limits

Parameter
Description
amountLimit

Type: price
Total amount that can be charged using this Charge Permission. For recurring Charge Permission objects, this value is the total amount that can be charged during the current month
amountBalance

Type: price
Remaining balance that can be charged using this Charge Permission. For recurring Charge Permission objects, this is the remaining amount that can be charged during the current month

Type: recurringMetadata

Parameter
Description
frequency

Type: frequency
Frequency at which the buyer will be charged using a recurring Charge Permission. You should specify a frequency even if you expect ad hoc charges

Possible combinations:
  • Year: 1-3
  • Month: 1-36
  • Week: 1-57
  • Day: 1-1095
amount

Type: price
Amount the buyer will be charged for each recurring cycle. Set to null if amount varies

Type: frequency

Parameter
Description
unit

Type: string
Frequency unit for each billing cycle. For multiple subscriptions, specify the frequency unit for the shortest billing cycle. Only use Variable if you charge the buyer on an irregular cadence, see handling variable cadence

Supported values: 'Year', 'Month', 'Week', 'Day', 'Variable'
value

Type: string
Number of frequency units per billing cycle. For example, to specify a weekly cycle set unit to Week and value to 1. You must set value to 0 if you're using variable unit

Type: price

Parameter
Description
amount

Type: string
Transaction amount
currencyCode

Type: string
Transaction currency code in ISO 4217 format

Example: USD

Type: buyer

Parameter
Description
buyerId

Type: string
Unique Amazon Pay buyer identifer

Max length: 42 characters/bytes
name

Type: string
Buyer name

Max length: 50 characters/bytes
email

Type: string
Buyer email address

Max length: 64 characters/bytes
phoneNumber

Type: string
Buyer default billing address phone number

Max length: 20 characters/bytes
primeMembershipTypes

Type: string
List of buyer Prime memberships. This data is not available for general use

Type: paymentPreference

Parameter
Description
paymentDescriptor

Type: string
Amazon Pay-provided description for payment instrument selected by the buyer. This value is currently always null

Type: address

Parameter
Description
name

Type: string
Address name

Max length: 50 characters/bytes
addressLine1

Type: string
The first line of the address

Max length: 180 characters/bytes
addressLine2

Type: string
The second line of the address

Max length: 60 characters/bytes
addressLine3

Type: string
The third line of the address

Max length: 60 characters/bytes
city

Type: string
City of the address

Max length: 50 characters/bytes
county

Type: string
County of the address

Max length: 50 characters/bytes
district

Type: string
District of the address

Max length: 50 characters/bytes
stateOrRegion

Type: string
The state or region:
  • US and CA addresses - Response will always be a 2-character code
  • All other countries - This element is free text and can be either a 2-character code, fully spelled out, or abbreviated
Max length: 50 characters/bytes
postalCode

Type: string
Postal code of the address

Max length: 20 characters/bytes
countryCode

Type: string
Country code of the address in ISO 3166 format

Max length: 3 characters/bytes
phoneNumber

Type: string
Phone number

Max length: 20 characters/bytes

Type: merchantMetadata

Parameter
Description
merchantReferenceId

Type: string
External merchant order identifer. The merchant order identifer is shared in buyer communication and in the buyer transaction history on the Amazon Pay website

Max length: 256 characters/bytes
merchantStoreName

Type: string
Merchant store name. Setting this parameter will override the default value configured in Seller Central (US, EU, JP). The store name is shared in buyer communication and in the buyer transaction history on the Amazon Pay website

Max length: 50 characters/bytes
noteToBuyer

Type: string
Description of the order that is shared in buyer communication

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

Max length: 255 characters/bytes
customInformation

Type: string
Custom information for the order. This data is not shared in any buyer communication

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

Max length: 4,096 characters/bytes

Type: statusDetails

Parameter
Description
state

Type: string
Current object state
reasons

Type: list<reason>
List of reasons for current state
lastUpdatedTimestamp

Type: dateTime
UTC date and time when the state was last updated in ISO 8601 format

Type: reason

Parameter
Description
reasonCode

Type: string
Reason code for current state
reasonDescription

Type: string
An optional description of the Charge Permission state

States and reason codes

State
Description
Reason code
Chargeable
State in which there are no constraints on the Charge Permission and it can be used to charge the buyer

Allowed operation(s):
GET Charge Permission
UPDATE Charge Permission
DELETE Charge Permission
-
NonChargeable
State in which there are constraints on the Charge Permission and it can't be used to charge the buyer

Allowed operation(s):
GET Charge Permission
UPDATE Charge Permission
DELETE Charge Permission
PaymentMethodInvalid - The previous charge was declined. For Recurring Charge Permissions, follow the steps for handling declines. For one-time Charge Permissions, ask the buyer to select a different payment method

PaymentMethodDeleted - The buyer has deleted the selected payment method

BillingAddressDeleted
- The buyer has deleted the billing address of the selected payment method

PaymentMethodExpired - The selected payment method has expired

PaymentMethodNotAllowed - The payment method selected by the buyer is not allowed for this Charge Permission

PaymentMethodNotSet - There is no payment method associated with charge permission

TransactionAmountExceeded - The amount limit for this Charge Permission has been reached or exceeded

TransactionCountExceeded - The transaction count limit for this Charge Permission has been reached or exceeded

MFAFailed - Buyer did not verify the transaction. Charge cannot be initiated unless buyer verifies the amount on the transaction
Closed
Charge Permission was closed or has expired

Allowed operation(s):
GET Charge Permission
UPDATE Charge Permission (if chargePermissionType is OneTime)
DELETE Charge Permission
MerchantClosed - You closed the Charge Permission by calling Cancel ChargePermission operation or the Charge Permission was closed because you did not call Complete Checkout Session

BuyerClosed -
 The buyer closed the Charge Permission

AmazonCanceled
- Amazon closed the Charge Permission

AmazonClosed - Amazon closed the Charge Permission because there is no amountBalance remaining

Expired - The Charge Permission expired after 180 days

Operations

Get Charge Permission

Get Charge Permission to determine if this Charge Permission can be used to charge the buyer. You can also use this operation to retrieve buyer details and their shipping address after a successful checkout. You can only retrieve details for 30 days after the time that the Charge Permission was created.

Request

Request parameters

Name
Location
Description
chargePermissionId
(required)

Type: string
Path Parameter
Charge Permission identifier

Response

Returns HTTP 200 status response code if the operation was successful.

{
    "chargePermissionId": "chargePermission-1",
    "chargePermissionReferenceId": null,
    "buyer": {
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000",
        "primeMembershipTypes": null
    },
    "releaseEnvironment": "Live",
    "shippingAddress":{  // Null for PayOnly product type
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "billingAddress":{  
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "paymentPreferences":[{
        "paymentDescriptor": null
    }],
    "statusDetails":{
        "state": "Chargeable",
        "reasons":null,
        "lastUpdatedTimestamp": "20190714T155300Z"
    },
    "creationTimestamp": "20190714T155300Z",
    "expirationTimestamp": "20190715T155300Z",
    "merchantMetadata":{
        "merchantReferenceId": "123-77-876", 
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "merchantNoteForBuyer",
        "customInformation": "This is custom information"
    },
    "platformId": "SPId",
    "limits": {
        "amountLimit": {
            "amount": "14.00",
            "currencyCode": "USD"
        },
        "amountBalance": {
            "amount": "14.00",
            "currencyCode": "USD"
        }
    },
    "presentmentCurrency": "USD"
}

Error codes

Generic errors can be found here.

Update Charge Permission

Update the Charge Permission with your external order metadata or the recurringMetadata if subscription details change. See update info post-checkout for limitations. Some of the values may be shared with the buyer. See buyer communication for more info.

Request

Request body

{
    "merchantMetadata": {
        "merchantReferenceId": "32-41-323141-32",
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "Some Note to buyer",
        "customInformation": ""    
     }  
}

Request parameters

Name
Location
Description
chargePermissionId
(required)

Type: string
Path Parameter
Charge Permission identifer
recurringMetadata

Type: recurringMetadata
Body
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
merchantMetadata

Type: merchantMetadata
Body
Merchant-provided order details

See update info post-checkout for limits to how many times this value can be modified

Response

Returns HTTP 200 status response code if the operation was successful.

{
    "chargePermissionId": "chargePermission-1",
    "chargePermissionReferenceId": null,
    "buyer": {
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000",
        "primeMembershipTypes": null
    },
    "releaseEnvironment": "Live",
    "shippingAddress": {  // Null for PayOnly product type
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "billingAddress": {
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "paymentPreferences": [
    {
        "paymentDescriptor": null
    }],
    "statusDetails": {
        "state": "Chargeable",
        "reasons": null,
        "lastUpdatedTimestamp": "20190714T155300Z"
    },
    "creationTimestamp": "20190714T155300Z",
    "expirationTimestamp": "20190715T155300Z",
    "merchantMetadata": {
        "merchantReferenceId": "123-77-876", 
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "merchantNoteForBuyer",
        "customInformation": "This is custom information"  
    },
    "platformId": "SPId",
    "limits": {
        "amountLimit": {
            "amount": "14.00",
            "currencyCode": "USD"
        },
        "amountBalance": {
            "amount": "14.00",
            "currencyCode": "USD"
        }
    },
    "presentmentCurrency": "USD"
}

Error codes

HTTP status code
Reason code
Error description
422 UNPROCESSABLE_ENTITY
InvalidChargePermissionStatus
You have tried to modify a Charge Permission that is in a state where it can't be modified

Generic errors can be found here.

Close Charge Permission

Moves the Charge Permission to a Closed state. No future charges can be made and pending charges will be canceled if you set cancelPendingCharges to true.

Request

Request body

{
    "closureReason": "No more charges required",
    "cancelPendingCharges": false
}

Request parameters

Name
Location
Description
chargePermissionId
(required)

Type: string
Path Parameter
Charge Permission identifier
closureReason

Type: string
Body
Merchant-provided reason for closing Charge Permission

Max length: 255 characters/bytes
cancelPendingCharges

Type: boolean
Body
If set to True:
  • Child Charge objects not in a Captured state are canceled
  • The Amazon Pay confirmation email is suppressed if the request is made within five minutes of Charge Permission creation
Default: False

Response

Returns HTTP 200 status response code if the operation was successful. This request is idempotent, subsequent requests will return the same response.

{
    "chargePermissionId": "chargePermission-1",
    "chargePermissionReferenceId": null,
    "buyer": {
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000",
        "primeMembershipTypes": null
    },
    "releaseEnvironment": "Live",
    "shippingAddress": {  // Null for PayOnly product type
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "billingAddress": { 
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "paymentPreferences": [
    {
        "paymentDescriptor": null
    }],
    "statusDetails": {
        "state": "Closed",
        "reasons":
        [{
            "reasonCode": null,
            "reasonDescription": null
        }],
        "lastUpdatedTimestamp": "20190714T155300Z"
    },
    "creationTimestamp": "20190714T155300Z",
    "expirationTimestamp": "20190715T155300Z",
    "merchantMetadata":{
        "merchantReferenceId": "123-77-876", 
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "merchantNoteForBuyer",
        "customInformation": "This is custom information" 
    },
    "platformId": "SPId",
    "limits": {
        "amountLimit": {
            "amount": "14.00",
            "currencyCode": "USD"
        },
        "amountBalance": {
            "amount": "14.00",
            "currencyCode": "USD"
        }
    },
    "presentmentCurrency": "USD"
}

Error codes

Generic errors can be found here.