Verify & complete checkout

[Step 5 of 8] The buyer is redirected to the checkoutResultReturnUrl, which you specified on the Checkout Session after the transaction was finalized. The Amazon Pay checkout session ID will be included as a query parameter. Use the Checkout Session ID to verify that checkout was successful.

If checkout was successful, you can use the Charge ID in Get Checkout Session response to capture the payment immediately. If you do not plan to capture payment immediately, store the Charge Permission ID and/or Charge ID for processing future transactions. The Charge Permission ID can be used to create a Charge for deferred payment authorization. The Charge ID can be used for deferred payment capture. See deferred transactions for more info.


1. Verify Checkout Session state

Get Checkout Session to verify that the Checkout Session is in the Completed state. See ‘Checkout Session state explanation’ table below for more info.

Checkout Session state explanation

Checkout Session State
Description
Completed
Payment intent was successful. You can follow the instructions in the next step to capture payment immediately. For all other payment scenarios, store the Charge Permission ID and/or Charge ID for future processing. See deferred transactions for more info.
Canceled
Checkout was not successful. The buyer either canceled checkout or was unable to provide a valid payment instrument. See Checkout Session canceled state reason code for more info.

The buyer can no longer complete checkout using the same Checkout Session ID. You should:

1. Redirect the buyer to the start of checkout.
2. Display a message such as: "Your payment was not successful. Please try another payment method.“
3. Create a new Checkout Session if the buyer clicks on the Amazon Pay button again.

Request

curl "https://pay-api.amazon.com/:environment/:version/checkoutSessions/:checkoutSessionId"
-X GET
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

Request parameters

Name
Location
Description
CheckoutSessionId
(required)

Type: string
Path Parameter
Checkout session identifier

Response

{
    "checkoutSessionId": "bd504926-f659-4ad7-a1a9-9a747aaf5275",
    "webCheckoutDetail": null,  // null in Completed state, Get Charge Permission to retrieve transaction details
    "productType": null,
    "paymentDetail": null,
    "merchantMetadata": null,
    "supplementaryData": null, // Amazon Pay system data
    "buyer": null,
    "paymentPreferences": null,
    "statusDetail":{
      "state": "Completed",
      "reasonCode": null,
      "reasonDescription": null,
      "lastUpdatedTimestamp": "20191015T210556Z"
    },
    "shippingAddress": null,
    "platformId": null,
    "chargePermissionId": "S01-5105180-3221187",
    "chargeId": "S01-5105180-3221187-C056351",
    "constraints": null,
    "creationTimestamp": "20191015T204313Z",
    "expirationTimestamp": null,
    "storeId": null,
    "deliverySpecifications": null,
    "providerMetadata": null,
    "checkoutButtonText": null,
    "releaseEnvironment": null
}

2. Complete checkout

Use Capture Charge to capture payment immediately. If you do not plan to capture payment immediately, store the Charge Permission ID and/or Charge ID for processing future transactions. The Charge Permission ID can be used to create a Charge for deferred payment authorization. The Charge ID can be used for deferred payment capture. See deferred transactions for more info.

Best practice: After a successful checkout, you can continue to retrieve buyer and transaction info for up to 30 days using Get Charge Permission. Store the data to persist the information beyond 30 days.

Request

curl "https://pay-api.amazon.com/:environment/:version/charges/:chargeId/capture" \
-X POST
-H "x-amz-pay-idempotency-key: AVLo5tI10BHgEk2jEXAMPLEKEY"
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body

Request body

{
    "captureAmount": {
        "amount": "14.00",
        "currencyCode": "USD"
    },
    "softDescriptor": "Descriptor"
}

Request parameters

Name
Location
Description
x-amz-pay-idempotency-key
(required)

Type: string
Header
Idempotency key to safely retry requests
chargeId
(required)

Type: string
Path Parameter
Charge identifier
captureAmount
(required)

Type: price
Body
Amount to capture
softDescriptor

Type: string
Body
Description shown to the buyer on their payment instrument statement

The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>"

Max length: 16 characters

Response

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "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",
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetail":{
         "state": "Captured",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z"
}

3. Add shipment tracking info

Note: This section is only applicable if you ship packages using a supported carrier.

Send shipment tracking information to Amazon Pay using the Delivery Tracker API. Amazon Pay will notify your buyers on their Alexa device when their package is shipped and when their package is delivered. See setting up delivery notifications for more info.