Call finalizeCheckoutSession API
To confirm the buyer has returned to your website, use finalizeCheckoutSession. AmazonPay will append CheckoutSessionId as a parameter to your Universal link or App link checkoutResultReturnUrl. In your delegate function (where you handle Universal link/App link), you’ll need to handle checkoutResultReturnUrl and retrieve CSId. Then call finalizeCheckoutSession API to validate button params & get CPId, buyer details, paymentDescriptor and billingAddress.
Note: Amazon Pay will finalize the paymentIntent after you confirm checkout with finalizeCheckoutSession. Any checkout session that isn’t confirmed within 24 hours will be cancelled. If payment authorization was requested it will also be cancelled.
Sample code to retrieve the checkout-session id:
Android
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Get the Intent that started this activity and extract the data
val data: Uri? = intent?.data
data?.let { uri ->
when (uri.host) {
"[your url of checkoutResultReturnUrl]" -> {
// 1. retrieve CheckoutSessionId
// 2. pass CheckoutSessionId to your backend service,
// and call finalizeCheckoutSession API with CSId in backend
}
"[your url of checkoutCancelUrl]" -> {
// redirect buyer to your App's page for cancel flow
}
else -> {
// redirect buyer to your App's page for error flow
}
}
}
}
iOS
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
guard let url = userActivity.webpageURL else {
return false
}
// Handle checkoutResultReturnUrl for happy path
if url.host == "[your url of checkoutResultReturnUrl]" {
// 1. retrieve CheckoutSessionId
// 2. pass CheckoutSessionId to your backend service,
// and call finalizeCheckoutSession API with CSId in backend
} else if url.host == "[your url of checkoutCancelUrl]" {
// redirect buyer to your App's page for cancel flow
} else {
// redirect buyer to your App's page for error flow
}
return true
}
Finalize Checkout Session Request
Request
curl "https://pay-api.amazon.com/:version/checkoutSessions/:checkoutSessionId/finalize" \
-X POST
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-d @request_body
Request body
{
"paymentIntent": "AuthorizeWithCapture",
"canHandlePendingAuthorization": "false"
}
Request parameters
| Name
|
Location
|
Description
|
| checkoutSessionId (required) Type: string |
Path parameter
|
Checkout Session identifier
|
| paymentIntent (required) Type: string |
Body
|
Payment flow for charging the buyer
|
| canHandlePendingAuthorization Type: boolean |
Body
|
Boolean that indicates whether merchant can handle pending response See asynchronous processing for more info |
| supplementaryData Type: string |
Body
|
Supplementary data about your order |
Finalize Checkout Session Response
Returns HTTP 200 status response code if paymentIntent was successful. Returns HTTP 202 status response code if authorization is still pending.
{
"checkoutSessionId": "9445e971-13ef-4842-b57f-5cd882e330d1",
"webCheckoutDetails": {
"checkoutReviewReturnUrl": null,
"checkoutResultReturnUrl": "https://www.testMerchant.com/return",
"amazonPayRedirectUrl": null,
"authorizeResultReturnUrl": null,
"signInReturnUrl": null,
"signInCancelUrl": null,
"checkoutErrorUrl": null,
"signInErrorUrl": null,
"checkoutCancelUrl": "https://www.testMerchant.com/cancel"
},
"productType": "PayOnly",
"paymentDetails": {
"paymentIntent": "Confirm",
"canHandlePendingAuthorization": false,
"chargeAmount": null,
"totalOrderAmount": null,
"softDescriptor": null,
"presentmentCurrency": null,
"allowOvercharge": null,
"extendExpiration": null
},
"chargePermissionType": "PaymentMethodOnFile",
"orderType": null,
"recurringMetadata": null,
"paymentMethodOnFileMetadata": {
"setupOnly": true
},
"processorSpecifications": null,
"merchantDetails": null,
"merchantMetadata": {
"merchantReferenceId": null,
"merchantStoreName": null,
"noteToBuyer": null,
"customInformation": null
},
"supplementaryData": null,
"buyer": {
"buyerId": "buyerId",
"name": "name-1",
"email": "name@amazon.com",
"phoneNumber": "800-000-0000"
},
"billingAddress": {
"name": "name-1"",
"addressLine1": "440 Terry Ave",
"addressLine2": "",
"addressLine3": "",
"city": "Seattle",
"county": "King",
"district": "Seattle",
"stateOrRegion": "WA",
"postalCode": "98121",
"countryCode": "US",
"phoneNumber": "800-000-0000"
},
"paymentPreferences": [
{
"paymentDescriptor": "Amazon Pay Visa (1111)"
}
],
"statusDetails": {
"state": "Completed",
"reasonCode": null,
"reasonDescription": null,
"lastUpdatedTimestamp": "20240905T185802Z"
},
"shippingAddress": null,
"platformId": null,
"chargePermissionId": "B01-2272709-5176927",
"chargeId": null,
"constraints": [],
"creationTimestamp": "20240905T185532Z",
"expirationTimestamp": "20240906T185532Z",
"storeId": "amzn1.application-oa2-client.456a4c3b15d24aae96256d2f82afdd73",
"providerMetadata": {
"providerReferenceId": null
},
"releaseEnvironment": "Live",
"checkoutButtonText": null,
"deliverySpecifications": null,
"tokens": null,
"disbursementDetails": null,
"channelType": "MOBILE_SDK"
}