Charge Permission
A Charge Permission is a contract between you (the merchant) and the buyer. It represents the buyer consent to be charged. The Charge Permission is used to facilitate deferred transactions. For simple payment use cases, such as immediate Authorization and Capture, you may not need to use the Charge Permission object at all.
You can also use the Charge Permission to retrieve the relevant checkout details needed to complete the order 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.
Successful completion of a Checkout Session returns a reference to a Charge Permission. You can use the Charge Permission for one successful Charge capture if 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 Charge Permission will move to a Closed state after a successful Charge capture, if it’s canceled, or it expires after 180 days.
Supported operations:
- Get Charge Permission - GET https://pay-api.amazon.com/:environment/:version/chargePermissions/:chargePermissionId
- Update Charge Permission - PATCH https://pay-api.amazon.com/:environment/:version/chargePermissions/:chargePermissionId
- Close Charge Permission - DELETE https://pay-api.amazon.com/:environment/:version/chargePermissions/:chargePermissionId/close
- Get Charge Permission - GET https://pay-api.amazon.eu/:environment/:version/chargePermissions/:chargePermissionId
- Update Charge Permission - PATCH https://pay-api.amazon.eu/:environment/:version/chargePermissions/:chargePermissionId
- Close Charge Permission - DELETE https://pay-api.amazon.eu/:environment/:version/chargePermissions/:chargePermissionId/close
- Get Charge Permission - GET https://pay-api.amazon.jp/:environment/:version/chargePermissions/:chargePermissionId
- Update Charge Permission - PATCH https://pay-api.amazon.jp/:environment/:version/chargePermissions/:chargePermissionId
- Close Charge Permission - DELETE https://pay-api.amazon.jp/:environment/:version/chargePermissions/:chargePermissionId/close
- Charge Permission object
- States and reason codes
- Get Charge Permission
- Update Charge Permission
- Close Charge Permission
- Related topics
Charge Permission object
Parameter
|
Description
|
chargePermissionId Type: string |
Charge Permission identifier This value is returned at the end of a completed Checkout Session |
Type: price |
Total amount that can be charged using this ChargePermission Max length: 16 characters |
releaseEnvironment Type: string |
Amazon Pay environment Possible values: live, sandbox |
buyer Type: buyer |
Details about the buyer, such as their unique identifier, name, and email
|
shippingAddress Type: address |
Shipping address selected by the buyer
|
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 |
statusDetail Type: statusDetail |
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 identifier
|
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. Billing address is only available in EU or for PayOnly product type
|
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:
|
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 identifier. The merchant order identifier 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: statusDetail
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. 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 StopShipmentAtypicalAuth - There are signs of unusual activity that indicate you shouldn’t proceed with fulfilment. |
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/:environment/:version/chargePermissions/:chargePermissionId"
-X GET
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
Request parameters
Name
|
Location
|
Description
|
chargePermissionId (required) Type: string |
Path Parameter
|
Charge Permission identifier
|
Response
Returns HTTP 200 (OK) status if the operation was successful.
{
"chargePermissionId": "chargePermission-1",
"chargePermissionReferenceId": null,
"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"
},
"paymentPreferences": [{
"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"
},
"paymentDescriptor": null
}],
"statusDetail": {
"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",
"chargeAmountLimit": {
"amount": "14.00",
"currencyCode": "USD"
},
"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/:environment/: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": ""
}
}
Request parameters
Name
|
Location
|
Description
|
chargePermissionId (required) Type: string |
Path Parameter
|
Charge Permission identifier
|
merchantMetadata Type: merchantMetadata |
Body
|
Merchant-provided order details Modifiable: Once |
Response
Returns HTTP 200 (OK) status if the operation was successful.
{
"chargePermissionId": "chargePermission-1",
"chargePermissionReferenceId": null,
"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"
},
"paymentPreferences": [
{
"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"
},
"paymentDescriptor": null
}],
"statusDetail": {
"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",
"chargeAmountLimit": {
"amount": "14.00",
"currencyCode": "USD"
},
"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. No future charges can be made and pending charges will be canceled if you set cancelPendingCharges to true.
Request
curl "https://pay-api.amazon.com/:environment/:version/chargePermissions/:chargePermissionId/close" \
-X DELETE
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body
Request body
{
"closureReason": "No more charges required",
"cancelPendingCharges": false
}
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
|
cancelPendingCharges Type: boolean |
Body
|
If set to True:
|
Response
Returns HTTP 200 (OK) status if the operation was successful.
{
"chargePermissionId": "chargePermission-1",
"chargePermissionReferenceId": null,
"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"
},
"paymentPreferences": [
{
"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"
},
"paymentDescriptor": null
}],
"statusDetail": {
"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",
"chargeAmountLimit": {
"amount": "14.00",
"currencyCode": "USD"
},
"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.