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 and it’s corresponding amazonPayToken to capture up to the total order amount while the Charge Permission is in a Chargeable state. You should review the reason code 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 a successful Charge capture, if it’s canceled, or it expires after 180 days.

You can use a recurring Charge Permission and its corresponding amazonPayToken to charge the buyer on a recurring basis while the Charge Permission is in a Chargeable state. You should review the reason code determine why you can’t charge th 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 order shipping address. Note that you can only retrieve checkout details for 30 days after the time that the Charge Permission was created.

Supported operations:

  • Get Charge Permission - GET https://pay-api.amazon.com/:version/chargePermissions/:chargePermissionId
  • Update Charge Permission - PATCH https://pay-api.amazon.com/:version/chargePermissions/:chargePermissionId
  • Close Charge Permission - DELETE https://pay-api.amazon.com/:version/chargePermissions/:chargePermissionId/close
  • Get Charge Permission - GET https://pay-api.amazon.eu/:version/chargePermissions/:chargePermissionId
  • Update Charge Permission - PATCH https://pay-api.amazon.eu/:version/chargePermissions/:chargePermissionId
  • Close Charge Permission - DELETE https://pay-api.amazon.eu/:version/chargePermissions/:chargePermissionId/close

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 charge the buyer for each billing cycle
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 buyer-selected payment instrument. Billing address is only available in EU or for PayOnly product type
paymentPreferences

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

Type: merchantMetadata
Merchant-provided order details
platformId

Type: string
Merchant identifier 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

The Charge Permission will expire 180 days after it's confirmed
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: 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
name

Type: string
Buyer name
email

Type: string
Buyer email address

Type: paymentPreferences

Parameter
Description
paymentDescriptor

Type: string
Amazon Pay-provided description for payment instrument selected by the buyer
billingAddress

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

Type: address

Parameter
Description
name

Type: string
Address name

Max length: 50 characters
addressLine1

Type: string
The first line of the address

Max length: 180 characters
addressLine2

Type: string
The second line of the address

Max length: 60 characters
addressLine3

Type: string
The third line of the address

Max length: 60 characters
city

Type: string
City of the address

Max length: 50 characters
county

Type: string
County of the address

Max length: 50 characters
district

Type: string
District of the address

Max length: 50 characters
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

Max length: 50 characters
postalCode

Type: string
Postal code of the address

Max length: 20 characters
countryCode

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

Max length: 3 characters
phoneNumber

Type: string
Phone number

Max length: 20 characters

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
merchantStoreName

Type: string
Merchant store name. Setting this parameter will override the default value configured in Seller Central (the account management tool for merchants). The store name is shared in buyer communication and in the buyer transaction history on the Amazon Pay website

Max length: 50 characters
noteToBuyer

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

You should not store sensitive data about the buyer or the transaction in this field

Max length: 255 characters
customInformation

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

You should not store sensitive data about the buyer or the transaction in this field

Max length: 4,096 characters

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
Number of frequency units per billing cycle. For example, to specify a weekly cycle set unit to Week and value to 1

Type: frequency

Parameter
Description
unit

Type: string
Frequency unit for each billing cycle

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

Type: statusDetails

Parameter
Description
state

Type: string
Current object state
reasons

Type: reasons
List of reasons for current state
lastUpdatedTimestamp

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

Type: reasons

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. Ask the buyer to update the 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

ChargeInProgress - A charge is already in progress. You cannot initiate a new charge unless previous charge is canceled

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
MerchantClosed - You closed the Charge Permission by calling Close Charge Permission operation

BuyerCanceled -
 The buyer closed the Charge Permission

AmazonCanceled
- Amazon closed the Charge Permission

AmazonClosed - Amazon closed the Charge Permission since the Charge was Completed

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

curl "https://pay-api.amazon.com/:version/chargePermissions/:chargePermissionId"
-X GET
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

Request parameters

Name
Location
Description
chargePermissionId
(required)

Type: string
Path Parameter
Charge Permission identifer

Response

Returns HTTP 200 status if the operation was successful.

{
    "chargePermissionId":"chargePermission-1",
    "chargePermissionReferenceId":null,
    "chargePermissionType": "Recurring",   
    "recurringMetadata": {
        "frequency": {
            "unit": "Month",
            "value": "1"
        },
        "amount": {
            "amount": "25",
            "currencyCode": "USD"
        }
    },
    "buyer":{
        "buyerId":"buyerId",
        "name":"name-1",
        "email":"name@amazon.com"
    },
    "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":{  // Only available in EU or 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"
    },
    "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": null,
        "amountBalance": null
    },
    "presentmentCurrency": "USD"
}

Error codes

Generic errors can be found here.

Update Charge Permission

Update the Charge Permission with your order metadata. Some of the values may be shared with the buyer. See buyer communication for more info.

Request

curl "https://pay-api.amazon.com/:version/chargePermissions/:chargePermissionId" \
-X PATCH
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body

Request body

{
    "merchantMetadata": {
        "merchantReferenceId":"32-41-323141-32",
        "merchantStoreName":"AmazonTestStoreFront",
        "noteToBuyer":"Some Note to buyer",
        "customInformation":""    
     },
     "recurringMetadata": {
        "frequency": {
            "unit": "Month",
            "value": "1"
        },
        "amount": {
            "amount": "30",
            "currencyCode": "USD"
        }
    }  
}

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 charge the buyer for each billing cycle
merchantMetadata

Type: merchantMetadata
Body
Merchant-provided order details

Modifiable: Once

Response

Returns HTTP 200 status if the operation was successful.

{
    "chargePermissionId":"chargePermission-1",
    "chargePermissionReferenceId":null,
    "chargePermissionType": "Recurring",
    "recurringMetadata": {
        "frequency": {
            "unit": "Month",
            "value": "1"
        },
        "amount": {
            "amount": "25",
            "currencyCode": "USD"
        }
    },
    "buyer":{
        "buyerId":"buyerId",
        "name":"name-1",
        "email":"name@amazon.com"
    },
    "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":{  // Only available in EU or 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"
     },
    "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",
    "presentmentCurrency": "USD"
}

Error codes

HTTP status code
Reason code
Error description
422 UNPROCESSABLE_ENTITY
ChargePermissionNotModifiable
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 and no future charges can be made on it.

Request

curl "https://pay-api.amazon.com/:version/chargePermissions/:chargePermissionId/close" \
-X DELETE
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body

Request body

{
    "closureReason":"No more charges required"
}

Request parameters

Name
Location
Description
chargePermissionId
(required)

Type: string
Path Parameter
Charge Permission identifier
closureReason
(required)

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

Max length: 255 characters

Response

Returns HTTP 200 status if the operation was successful.

{
    "chargePermissionId":"chargePermission-1",
    "chargePermissionReferenceId":null,
    "chargePermissionType": "Recurring",
    "recurringMetadata": {
        "frequency": {
            "unit": "Month",
            "value": "1"
        },
        "amount": {
            "amount": "25",
            "currencyCode": "USD"
        }
    },
    "buyer":{
        "buyerId":"buyerDirectedId",
        "name":"name-1",
        "email":"name@amazon.com"
    },
    "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":{  // Only available in EU or 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"
     },
    "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",
    "presentmentCurrency": "USD"
}

Error codes

HTTP status code
Reason code
Error description
422 UNPROCESSABLE_ENTITY
InvalidChargePermissionStatus
You tried to call an operation on a Charge Permission that is in a state where that operation is not allowed

Generic errors can be found here.