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.