Sign In
Sign In

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.

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"
}