Console

Settings

Sign out

Notifications

Alexa

Amazon Appstore

Ring

AWS

Documentation

Support

My Cases

Console

Fire OS Developer Docs

Home

Develop

Test

Publish

Monetize

Engage users

Device specifications

Resources

Provide Event Handlers

1. Initialize checkout
2. Shipping address update
3. Delivery option update
4. Gift wrap option selection
5. Complete checkout
6. Cancel checkout
7. Handling errors

[Step 3 of 8] The Amazon Pay button requires event handlers to manage the checkout flow. These event handlers exchange cart-level data between your system and Amazon Pay, which renders the information on the checkout page.

The following event handlers are available:

onInitCheckout - Initializes the checkout session (required)
onShippingAddressSelection - Responds to shipping address changes (optional)
onDeliveryOptionSelection - Responds to delivery option changes (optional)
onGiftWrapOptionSelection - Responds to gift wrap option changes (optional, for gifting integration)
onCompleteCheckout - Finalizes the checkout session (required)
onCancel - Handles checkout cancellation (required)
onError - Handles error conditions (required)

1. Initialize checkout

When the buyer selects Amazon Pay as the payment method, Amazon Pay authenticates the buyer and collects consent. The buyer's default shipping address and payment method are pre-selected. After this onInitCheckout event handler/javascript callback function is invoked.

In this callback, Amazon Pay provides buyer details based on the requested scopes. Your system must return cart information including amounts, tax, delivery options, and line item details. For a complete list of supported elements, see CartDetails Response. The data you provide will be displayed on the Amazon Pay checkout page.

For gifting integration, include the giftDetails object in your response to enable gift-specific functionality. You must also include "GIFT" in the addOnFeatures array and set the appropriate addressDisplayType.

/** Invokes when initiated checkout and authenticated **/
onInitCheckout: async function (event) {
  try {
    // Perform your server-side request to fetch details
    const cartDetails = await fetch("/your-server/initCheckout", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      data: JSON.stringify({
        shippingAddress: event.shippingAddress,
        scopes: event.scopes,
        checkoutLanguage: event.checkoutLanguage,
      }),
    });

    return {
      totalBaseAmount: cartDetails.totalBaseAmount,
      totalTaxAmount: cartDetails.totalTaxAmount,
      totalShippingAmount: cartDetails.totalShippingAmount,
      totalChargeAmount: cartDetails.totalChargeAmount,
      totalOrderAmount: cartDetails.totalOrderAmount,
      totalDiscountAmount: cartDetails.totalDiscountAmount,
      lineItems: cartDetails.lineItems,
      deliveryOptions: cartDetails.deliveryOptions,
      checkboxes: cartDetails.checkboxes,
      freeForm: cartDetails.freeForm,
      addOnFeatures: cartDetails.addOnFeatures,
      addressDisplayType: cartDetails.addressDisplayType,
      giftDetails: cartDetails.giftDetails
    };
  } catch (err) {
    // something went wrong with your server call
    console.err(err);
    return {
      status: "error",
      reasonCode: "unknownError",
    };
  }
};

onInitCheckout event input

Parameter	Description
scopes Type: Scopes	Details about the buyer, such as their unique identifier, name, and email that are shared based on scope requested
checkoutLanguage Type: string	Buyer selected checkout language.
shippingAddress Type: Address	Buyer selected shipping address.

{
    "buyer": { // shared based on scope requested
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000"
    },
    "billingAddress": { // shared based on scope requested
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    }, 
    "shippingAddress": {  // Null for PayOnly product type
        "name": "Susie Smith",
        "addressLine1": "10 Ditka Ave",
        "addressLine2": "Suite 2500",
        "addressLine3": null,
        "city": "Chicago",
        "county": null,
        "district": null,
        "stateOrRegion": "IL",
        "postalCode": "60602",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    }
}

onInitCheckout handler output

Attribute	Type	Description	Required	Default
lineItems	LineItem	Details for each item in cart	No	N/A
deliveryOptions	List<DeliveryOption>	Available delivery options	Yes for PayAndShip No for PayOnly	N/A
totalShippingAmount	Price	Total amount for shipping	Yes	N/A
totalBaseAmount	Price	Total amount for items in cart	Yes	N/A
totalTaxAmount	Price	Total amount for tax	Yes	N/A
totalDiscountAmount	Price	Total sum of discounts - sum of line item discount, cart level discount and coupon code discount	No	N/A
totalChargeAmount	Price	Total amount for this transaction	Yes	N/A
totalOrderAmount	Price	Total order amount for the transaction. This field should be set when merchant wants to perform multiple authorization.	No	N/A
checkboxes	Checkbox (onInit response)	Checkboxes details	No	N/A
freeForm	FreeForm (onInit response)	Freeform details	No	N/A
giftDetails	giftDetails	Details related to gift like giftType, giftMessage, wrapping cost etc	No	null
addressDisplayType	AddressDisplayType [Enum]	Determines if senderAddress/shipFrom address needs to be shown on BuyNow page	No	null
addOnFeatures	addOnFeatures Type: List<AddOnFeatureType[Enum]>	List of add on features, merchant wants to enable on AmazonPay Checkout	No	Empty

GiftDetails

Attribute	Type	Description	Required	Default
giftType	GiftType[Enum]	Defines different types of gift that can be supported. For now, we will only support STANDARD. Later, we can also extend other giftingTypes: GROUP_GIFTING, CORPORATE_GIFTING, DIGITAL_GIFTING etc.	No	null
giftMessage	GiftMessage	Denotes gift message associated with the gift transaction	No	null
giftWrapDetails	GiftWrapDetails	Denotes giftWrap option selected for the gift	No	null

GiftType [Enum]

Attribute	Description
STANDARD	To represent standard gifting type

GiftMessage

Attribute	Type	Description	Required	Default
text	String	Text message to show to buyer as gift message, can be edited on BuyNow page. It can be empty in case merchant wants it to be entered on BuyNow page itself	Yes	N/A
limit	Integer	Limit for gift message field length. Max limit allowed is 200 characters.	No	200

Note : Character count in gift message input field is calculated based on UTF-16 encoding. The number of characters remaining may vary depending on the input type:

Standard text (letters, numbers, basic punctuation): 1 character each
Single Unicode code point emojis: 2 characters each, eg: 😀(smiley face), 👍(thumbs up), 🎁(gift)
Complex emojis (multi-code point sequences including skin tone modifiers, flags, and combined variants) count as 3 or more characters based on their grapheme cluster length. These are formed by combining multiple emojis.

Examples:

Hello! = 6 characters
Hello 😊 = 8 characters (6 text + 2 for emoji)
Hello 👨‍👩‍👧 = 14 characters (6 text + 8 for family emoji)

GiftWrapDetails

Attribute	Type	Description	Required	Default
availableGiftWrapOptions	List<GiftWrapOption>	Represents gift wrap options list passed by merchant. Up to 10 giftWrapOptions max are allowed	Yes	N/A
selectedGiftWrapId	String	Represents giftWrapId selected by the buyer	No	N/A

GiftWrapOption

Attribute	Type	Description	Required	Default
id	String	Id for this particular GiftWrap	Yes	N/A
name	String	Name of the gift wrapper to be displayed on APay checkout page	Yes	N/A
imageUrl	String	Url for gift wrap images to be displayed on APay checkout page	Yes	N/A
giftWrapAmount	Price	Total amount for gift wrap	Yes	N/A

AddressDisplayType [Enum]

Attribute	Description
SENDER_ADDRESS	Denotes if sender address needs to be shown on BuyNow page for gifting usecase.For non-gifting usecase, it denotes Order From address

AddOnFeatureType [Enum]

Value	Description
GIFT	Represents gifting feature

{
    "lineItems":[
        {
            "id": "id-of-the-item",
            "title":"item-title-1",
            "variantTitle":"variant-title",
            "quantity":"2",
            "listPrice": {
                "amount":"10",
                "currencyCode":"JPY"
            },
            "totalListPrice":{
                "amount":"20",
                "currencyCode":"JPY"
            }
        }
    ],
    "deliveryOptions":[{
        "id":"abc_shipping-02-25.11",
        "price":{
            "amount":"5",
            "currencyCode":"JPY"
        },
        "shippingMethod":{
            "shippingMethodName":"shipping-method-name",
            "shippingMethodCode":"shipping-method-code"
        },
        "shippingEstimate":[{
            "timeUnit":"HOUR",
            "value":2
        }],
        "isDefault":true
    }],
    "totalShippingAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "totalBaseAmount":{
        "amount":"20",
        "currencyCode":"JPY"
    },
    "totalTaxAmount":{
        "amount":"0.5",
        "currencyCode":"JPY"
    },
    "totalOrderAmount":{
        "amount":"25.5",
        "currencyCode":"JPY"
    },
    "totalChargeAmount":{
        "amount":"25.5",
        "currencyCode":"JPY"
    },
    "totalDiscountAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "addOnFeatures": ["GIFT"] , 
    "addressDisplayType": "SENDER_ADDRESS",
    
    // Gift related information
    "giftDetails": {
        "giftType": "STANDARD",
        "giftMessage": {
            "text": "Enjoy your gift!",
            "limit": 120
        },
        "giftWrapDetails": {
            "availableGiftWrapOptions": [
                {
                    "id": "wrap-1",
                    "name": "Gift Wrap 1",
                    "imageUrl": "https://example.com",
                    "giftWrapAmount":{
                        "amount":"5",
                        "currencyCode":"JPY"
                    }
                },
                {
                    "id": "wrap-2",
                    "name": "Gift Wrap 2",
                    "imageUrl": "https://example.com",
                    "giftWrapAmount":{
                        "amount":"5",
                        "currencyCode":"JPY"
                    }
                }
            ], 
            "selectedGiftWrapId": "wrap-2" 
       }
    },
    "checkboxes": [{
            "type": "MERCHANT_MULTIPLE_DISCLOSURES",
            "attributes": {
                "isPrechecked": true, //optional
                "primaryPolicyName": "policy1",
                "primaryPolicyUrl": "https://amazon.com/terms/index.html",
                "secondaryPolicyName": "policy2",
                "secondaryPolicyUrl": "https://amazon.com/terms/index.html",
                "tertiaryPolicyName": "policy3",
                "tertiaryPolicyUrl": "https://amazon.com/terms/index.html"
            }
        },
        {
            "type": "RIGHT_OF_WITHDRAWL",
            "attributes": {
                "isPrechecked": false,
                "termsAndConditionsUrl": "https://amazon.com/terms/index.html"
            }
        },
        {
            "type": "MERCHANT_DISCLOSURE",
            "attributes": {
                "termsAndConditionsUrl": "https://amazon.com/terms/index.html",
                "privacyPolicyUrl": "https://amazon.com/terms/index.html"
            }
        },
     ],
    "freeForm": { // optional (if not present then exclude this feature)
        "placeholderText": "Please add delivery instructions", // required
        "limit": 150, // optional
        "isMandatory": true
    }
}

See the CartDetails type for a full definition.

onInitCheckout handler errors

In case you can't fullfil the order based on the data supplied to you, please return an error response to Amazon Pay.

{
    "status": "error",
    "reasonCode": "shippingAddressInvalid"
}

ReasonCode	Description
shippingAddressInvalid	The supplied shipping address can't be accepted by you. The buyer will be requested to select a different address.
unknownError	For any other error. The buyer will see a generic error message and requested to return to your shop.

2. Shipping address update

When the buyer selects or changes the preferred shipping address, Amazon Pay will invoke this event handler.

Note for gifting transactions: This callback is triggered only when the buyer changes the shipping address (recipient's address). Changes to the sender address will not trigger this event handler.

/** Invokes when customer has selected different shipping address **/
onShippingAddressSelection: async function (event) {
  try {
    // Perform your server-side request to fetch details
    const cartDetails = await fetch("/your-server/addressUpdate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      data: JSON.stringify({
        shippingAddress: event.shippingAddress,
      }),
    });

    return {
      totalBaseAmount: cartDetails.totalBaseAmount,
      totalTaxAmount: cartDetails.totalTaxAmount,
      totalShippingAmount: cartDetails.totalShippingAmount,
      totalChargeAmount: cartDetails.totalChargeAmount,
      totalOrderAmount: cartDetails.totalOrderAmount,
      totalDiscountAmount: cartDetails.totalDiscountAmount,
      lineItems: cartDetails.lineItems,
      deliveryOptions: cartDetails.deliveryOptions,
    };
  } catch (err) {
    // something went wrong with your server call
    console.err(err);
    return {
      status: "error",
      reasonCode: "unknownError",
    };
  }
};

onShippingAddressSelection event input

Parameter	Description
shippingAddress Type: Address	Buyer selected shipping address.

{
    "shippingAddress": {
        "name": "Susie Smith",
        "addressLine1": "10 Ditka Ave",
        "addressLine2": "Suite 2500",
        "addressLine3": null,
        "city": "Chicago",
        "county": null,
        "district": null,
        "stateOrRegion": "IL",
        "postalCode": "60602",
        "countryCode": "US"
    }
}

onShippingAddressSelection handler output

{
    "totalBaseAmount":{
        "amount":"120",
        "currencyCode":"JPY"
    },
    "totalShippingAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "totalTaxAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "totalOrderAmount":{
        "amount":"125",
        "currencyCode":"JPY"
    },
    "totalChargeAmount":{
        "amount":"125",
        "currencyCode":"JPY"
    },
    "totalDiscountAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "lineItems":[
        {
            "id": "id-of-the-item",
            "title":"item-title-1",
            "variantTitle":"variant-title",
            "quantity":"2",
            "listPrice": {
                "amount":"10",
                "currencyCode":"JPY"
            },
            "totalListPrice":{
                "amount":"20",
                "currencyCode":"JPY"
            }
        }
    ],
    "deliveryOptions":[{
        "id":"abc_shipping-02-25.11",
        "price":{
            "amount":"5",
            "currencyCode":"JPY"
        },
        "shippingMethod":{
            "shippingMethodName":"shipping-method-name",
            "shippingMethodCode":"shipping-method-code"
        },
        "shippingEstimate":[{
            "timeUnit":"HOUR",
            "value":2
        }],
        "isDefault":true
    }]
}

See the CartDetails type for a full definition.

onShippingAddressSelection handler errors

In case you can't fullfil the order based on the data supplied to you, please return an error response to Amazon Pay.

{
    "status": "error",
    "reasonCode": "shippingAddressInvalid"
}

ReasonCode	Description
shippingAddressInvalid	The supplied shipping address can't be accepted by you. The buyer will be requested to select a different address.
unknownError	For any other error. The buyer will see a generic error message and requested to return to your shop.

3. Delivery option update

When the buyer selects or changes the preferred shipping option, Amazon Pay will invoke this event handler.

/** Invokes when customer has selected different shipping address **/
onDeliveryOptionSelection: async function (event) {
  try {
    // Perform your server-side request to fetch details
    const cartDetails = await fetch("/your-server/deliveryOptionUpdate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      data: JSON.stringify({
        selectedDeliveryOption: {
          id: event.deliveryOptions.id,
          amount: event.deliveryOptions.amount,
          displayName: event.deliveryOptions.displayName,
        },
      }),
    });

    return {
      totalBaseAmount: cartDetails.totalBaseAmount,
      totalTaxAmount: cartDetails.totalTaxAmount,
      totalShippingAmount: cartDetails.totalShippingAmount,
      totalChargeAmount: cartDetails.totalChargeAmount,
      totalOrderAmount: cartDetails.totalOrderAmount,
      totalDiscountAmount: cartDetails.totalDiscountAmount,
      lineItems: cartDetails.lineItems, // optional
      deliveryOptions: cartDetails.deliveryOptions, // optional
    };
  } catch (err) {
    // something went wrong with your server call
    console.err(err);
    return {
      status: "error",
      reasonCode: "unknownError",
    };
  }
};

onDeliveryOptionSelection event input

Parameter	Description
deliveryOptions Type: DeliveryOption (Event input)	Buyer selected delivery option.

{
    "deliveryOptions": {
        "id": "do-2",
        "displayName": "Option 2",
        "amount": "5"
    }
}

onDeliveryOptionSelection handler output

You can re-calculate the cart details based on the delivery option selected by the buyer. Please return anything that changed based on the delivery option selection. At a minimum the required amount fields need to be returned.

{
    "totalBaseAmount":{
        "amount":"120",
        "currencyCode":"JPY"
    },
    "totalShippingAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "totalTaxAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "totalOrderAmount":{
        "amount":"125",
        "currencyCode":"JPY"
    },
    "totalChargeAmount":{
        "amount":"125",
        "currencyCode":"JPY"
    },
    "totalDiscountAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    }
}

See the CartDetails type for a full definition.

onDeliveryOptionSelection handler errors

In case you can't fullfil the order based on the data supplied to you, please return an error response to Amazon Pay.

{
    "status": "error", 
    "reasonCode": "deliveryOptionInvalid"
}

ReasonCode	Description
deliveryOptionInvalid	The supplied delivery option can't be accepted by you. The buyer will be requested to select a different shipping option.
unknownError	For any other error. The buyer will see a generic error message and requested to return to your shop.

4. Gift wrap option selection

When the buyer selects or changes a gift wrap option, Amazon Pay will invoke this event handler. This callback notifies merchants about the selected gift wrap, allowing them to recalculate order totals and adjust any applied discounts or points accordingly.

Important: The value provided in the request overrides any existing gift wrap selection at the merchant side. If the giftWrapOption is set to null, it indicates the buyer has chosen not to use any gift wrap option.

/** Invokes when customer has selected or changed gift wrap option **/
onGiftWrapOptionSelection: async function (event) {
  try {
    // Perform your server-side request to fetch details
    const cartDetails = await fetch("/your-server/giftWrapUpdate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      data: JSON.stringify({
        selectedGiftWrapOption: {
          id: event.giftWrapOption.id,
          amount: event.giftWrapOption.amount,
          displayName: event.giftWrapOption.displayName,
        },
      }),
    });

    return {
      totalBaseAmount: cartDetails.totalBaseAmount,
      totalTaxAmount: cartDetails.totalTaxAmount,
      totalShippingAmount: cartDetails.totalShippingAmount,
      totalChargeAmount: cartDetails.totalChargeAmount,
      totalOrderAmount: cartDetails.totalOrderAmount,
      totalDiscountAmount: cartDetails.totalDiscountAmount,
      giftDetails: cartDetails.giftDetails, //optional
      // If points and promoCode were applied before, return recalculated values
      points: cartDetails.points, // optional
      promoCodes: cartDetails.promoCodes //optional
    };
  } catch (err) {
    // something went wrong with your server call
    console.err(err);
    return {
      status: "error",
      reasonCode: "unknownError",
    };
  }
};

onGiftWrapOptionSelection event input

Parameter	Description
giftWrapOption Type: GiftWrapOption (Event input)	Buyer selected gift wrap option.

{
    "giftWrapOption": {
        "id": "wrap-1",
        "amount": "20",
        "displayName": "Gift Wrap 1"
    }
}

GiftWrapOption (Event input)

Attribute	Type	Description	Required	Default
id	String	Identifier for the selected gift wrap	Yes	N/A
displayName	String	Name of the selected gift wrap	Yes	N/A
amount	String	Amount of the selected gift wrap	Yes	N/A

onGiftWrapOptionSelection handler output

You must recalculate the order totals based on the selected gift wrap option. If the buyer previously applied promo codes or redeemed points, adjust these values to reflect the updated order total.

Handling Points and Promo Codes:

If you do not include points or promoCodes in the response, Amazon Pay will remove the buyer's selections from the checkout page and recalculate the total charge excluding these discounts. This ensures consistency between your system and the buyer experience.
If you do include points or promoCodes in the response, Amazon Pay will display the updated values you provide, allowing you to adjust discounts based on the new order total.

{
    "totalShippingAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "totalBaseAmount":{
        "amount":"20",
        "currencyCode":"JPY"
    },
    "totalTaxAmount":{
        "amount":"0.5",
        "currencyCode":"JPY"
    },
    "totalOrderAmount":{
        "amount":"5.5",
        "currencyCode":"JPY"
    },
    "totalChargeAmount":{
        "amount":"5.5",
        "currencyCode":"JPY"
    },
    "totalDiscountAmount":{
        "amount":"5",
        "currencyCode":"JPY"
    },
    "points": {
        "pointsEarned": "10", // earned points could change based on redeemedPoints
        "pointsAvailable":"150" // total points available without subtracting redeemedPoints
        
        "redeemedPoints":{
            "points": "10",
            "amount": {
                "amount":"10",  // merchant can adjust applied points based on updated total order amount
                "currencyCode":"JPY"
            }
        },
    }
    "promoCodes" : {
        "redeemedPromoCodes": [{
            "promoCode": "<promo-code>", // should be same as promo code applied before
            "amount":{
                "amount":"10", // merchant can adjust promo code discount amount based on updated total order
                "currencyCode":"JPY"
            }
        }]
    },
    "giftDetails": {
        "giftType": "STANDARD",
        "giftMessage": {
            "text": "Enjoy your gift!",
            "limit": 120
        },
        "giftWrapDetails": {
            "availableGiftWrapOptions": [
            {
                "id": "wrap-1",
                "name": "GiftWrap 1",
                "imageUrl": "https://example.com",
                "giftWrapAmount":{
                    "amount":"5",
                    "currencyCode":"JPY"
                }
            }
            ],
            "selectedGiftWrapId": "wrap-1"
        },
    }
}

Total Charge Validation

Amazon Pay validates the following calculation. If it doesn't match, an InvalidParameterError will be displayed with the message: "Total order amount does not match the sum of individual amounts."

Total Charge = Base + Tax + Shipping + GiftWrap - Discount - Points - Promo Code

Note: You must use the giftWrapOption provided in the event request to recalculate the totalChargeAmount based on the selected gift wrap. Additionally, adjust any previously applied promo code discounts and redeemed points values to reflect the updated order total, ensuring customer-applied discounts remain intact and are returned in the event response with their recalculated values.

See the CartDetails type for a full definition.

onGiftWrapOptionSelection handler errors

In case you can't fulfill the order based on the data supplied to you, return an error response to Amazon Pay.

{
    "status": "error",
    "reasonCode": "giftWrapOptionInvalid"
}

ReasonCode	Description
giftWrapOptionInvalid	The supplied gift wrap option cannot be recognized or accepted. The buyer will see an error message and be prompted to select a different gift wrap option.
unknownError	For any other error. The buyer will see a generic error message and be prompted to return to your shop.

5. Complete checkout

When the buyer clicks the purchase button to complete checkout, Amazon Pay invokes this event handler. Use the data from this callback to call the Finalize Checkout Session API on your backend to complete the transaction.

Display a processing page or spinner on the frontend while the API call is in progress. Upon successful API response, redirect the buyer to your thank you page.

/** Invokes when customer has selected different shipping address **/
onCompleteCheckout: async function (event) {
  try {
    // Perform your server-side request to fetch details
    const result = await fetch("/your-server/finalizeCheckout", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      data: JSON.stringify({
        checkoutSessionId: event.amazonCheckoutSessionId,
        billingAddress: event.billingAddress,
        paymentDescriptor: event.paymentDescriptor,
        checkboxes: event.checkboxes,
        freeform: event.freeform,
        senderAddress: event.senderAddress,
        isGiftPurchase: event.isGiftPurchase,
        giftWrapDetails: event.giftWrapDetails,
        giftMessage: event.giftMessage
        
      }),
    });
  } catch (err) {
    // something went wrong with your server call
    console.err(err);
    return {
      status: "error",
      reasonCode: "unknownError",
    };
  }
};

onCompleteCheckout event input

As part of this callback, we share the final billingAddress and paymentDescriptor which can be used to update your database. This billing address may be different from the one shared as part of onInitCheckout callback in cases where buyer changes PI.

The input to this function is checkoutSessionId. You should take this session id and use it on your backend to call FinalizeCheckoutSession API. On the front-end, you should show a processing page / spinner. Successful response of this API merchant should render thank you page.

For gifting transactions, this callback includes additional fields: senderAddress, isGiftPurchase, giftWrapDetails, and giftMessage. Store these values for order fulfillment and customer service purposes.

Attribute	Type	Description	Required	Default
amazonCheckoutSessionId	String	AmazonPay's checkoutSessionId	Yes	N/A
billingAddress	Address	AmazonPay's billingAddress	No	N/A
paymentDescriptor	String	Amazon Pay-provided description for buyer-selected payment instrument Max length: 64 characters/bytes	No	N/A
buyerAddtionalInfo	BuyerAddtionalInfo	Additional buyer info that collected on SPC page	Yes if merchant requested	EU only
checkboxes	Checkbox (onComplete input)	Checkboxes checked/unchecked by buyer	Yes if merchant requested	NA
freeform	String	Freeform entered by buyer	Yes if merchant requested	NA
senderAddress	Address	Gift sender's address	Yes, if it is a gift order and merchant chooses to displaySenderAddress	null
isGiftPurchase	Boolean	If order is marked as gift on BuyNow page	No	FALSE
giftWrapDetails	GiftWrapSelection	Denotes giftWrap option selected for the gift	No	null
giftMessage	GiftMessage	Gift message entered by buyer on BuyNow page	No	null

GiftWrapSelection

Attribute	Type	Description	Required	Default
selectedGiftWrapId	String	Represents giftWrapId selected by the buyer	No	N/A
selectedGiftWrapAmount	Price	Represents selected gift wrap amount	No	null

{
    "amazonCheckoutSessionId": "d0966c90-f8f6-4835-9129-1f743cf525bc",
    "billingAddress": { // shared based on scope requested
                "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": "Visa ****1111 (Amazon Pay)",
    "senderAddress": {
                "name": "Work",
                "addressLine1": "440 Terry Ave",
                "addressLine2": "",
                "addressLine3": "",
                "city": "Seattle",
                "county": "King",
                "district": "Seattle",
                "stateOrRegion": "WA",
                "postalCode": "98121",
                "countryCode": "US",
                "phoneNumber": "800-000-0000"
          },
    "isGiftPurchase": true,
    "giftWrapDetails": {
              "selectedGiftWrapId": "gift-wrap-1"
          },
    "giftMessage": {
              "text": "Enjoy your gift!"
          },
    "freeForm": "free form customer inputted text",
    "checkboxes": [
        {
        "template": "MERCHANT_DISCLOSURE",
        "isChecked": true
        },
        {
        "template": "MERCHANT_MULTIPLE_DISCLOSURES",
        "isChecked": true
        }
    ]
}

onCompleteCheckout handler output

No output for this callback. Successful response of this API merchant should render thank you page

6. Cancel checkout

When the buyer clicks Cancel and return to merchant hyperlink, Amazon Pay will invoke this event handler. onCancel callback is used to close the amazon pay checkout popup window, buyer returns back to merchant page. If onCancel is received after successful authorization of merchant points and promo code then merchants are required to release them back to the customer account.

onCancel: function (event) {
    // Takes buyer back to cart page or product details automatically
}

onCancel event input

No input required for this callback

onCancel event output

No output required for this callback

7. Handling errors

onError callback is used to communicate to merchant if any error occurred and merchant may take any action. We don't close the amazon pay window in this case. If onError is received after successful authorization of merchant points and promo code then merchants are required to release them back to the customer account.

onError: function (event) {
    console.err(event);
}

onError event input

Attribute	Type	Description
message	String	Error message

onError event output

No output required for this callback