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:

• US
• EU / UK
• JP

• Charge Permission object
• States and reason codes
• Get Charge Permission
• Update Charge Permission
• Close Charge Permission
• Related topics

Charge Permission object

Type: price

Type: buyer

Type: paymentPreferences

Type: address

Type: merchantMetadata

Type: statusDetail

Type: reason

States and reason codes

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

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

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.

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

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

Generic errors can be found here.

Related topics

• Checkout session object
• Charge object