Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

Provide Event Handlers

[Step 3 of 7] Five event handlers can be defined and registered in the button JavaScript code. The event handlers receive cart-level details from and communicate to Amazon Pay, which will be rendered on the checkout page:


1. Initialize checkout

The Buyer starts checkout by selecting Amazon Pay as the payment method. Amazon Pay authenticates the buyer, collects their consent and defaults to their choice of shipping address and payment method. After this onInitCheckout event handler/javascript callback function is invoked.

Amazon Pay will provide you with buyer details, based on the scopes requested. Amazon Pay expects cart information (e.g. amounts, tax, delivery options, item level details). Please find a list of supported elements in CartDetails Response. The information you share with Amazon Pay will be rendered on the Amazon Pay Checkout page.

/** 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,
    };
  } 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

{
    "totalShippingAmount":{
        "amount":"5",
        "currencyCode":"USD"
    },
    "totalBaseAmount":{
        "amount":"20",
        "currencyCode":"USD"
    },
    "totalTaxAmount":{
        "amount":"0.5",
        "currencyCode":"USD"
    },
    "totalOrderAmount":{
        "amount":"20.5",
        "currencyCode":"USD"
    },
    "totalChargeAmount":{
        "amount":"20.5",
        "currencyCode":"USD"
    },
    "totalDiscountAmount":{
        "amount":"5",
        "currencyCode":"USD"
    },
    "lineItems":[
        {
            "id": "id-of-the-item",
            "title":"item-title-1",
            "variantTitle":"variant-title",
            "quantity":"2",
            "listPrice": {
                "amount":"10",
                "currencyCode":"USD"
            },
            "totalListPrice":{
                "amount":"20",
                "currencyCode":"USD"
            }
        }
    ],
    "deliveryOptions":[{
        "id":"abc_shipping-02-25.11",
        "price":{
            "amount":"5",
            "currencyCode":"USD"
        },
        "shippingMethod":{
            "shippingMethodName":"shipping-method-name",
            "shippingMethodCode":"shipping-method-code"
        },
        "shippingEstimate":[{
            "timeUnit":"HOUR",
            "value":2
        }],
        "isDefault":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.

/** 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

{
    "totalShippingAmount":{
        "amount":"5",
        "currencyCode":"USD"
    },
    "totalBaseAmount":{
        "amount":"20",
        "currencyCode":"USD"
    },
    "totalTaxAmount":{
        "amount":"0.5",
        "currencyCode":"USD"
    },
    "totalOrderAmount":{
        "amount":"20.5",
        "currencyCode":"USD"
    },
    "totalChargeAmount":{
        "amount":"20.5",
        "currencyCode":"USD"
    },
    "totalDiscountAmount":{
        "amount":"5",
        "currencyCode":"USD"
    },
    "lineItems":[
        {
            "id": "id-of-the-item",
            "title":"item-title-1",
            "variantTitle":"variant-title",
            "quantity":"2",
            "listPrice": {
                "amount":"10",
                "currencyCode":"USD"
            },
            "totalListPrice":{
                "amount":"20",
                "currencyCode":"USD"
            }
        }
    ],
    "deliveryOptions":[{
        "id":"abc_shipping-02-25.11",
        "price":{
            "amount":"5",
            "currencyCode":"USD"
        },
        "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.

{
    "totalShippingAmount":{
        "amount":"5",
        "currencyCode":"USD"
    },
    "totalBaseAmount":{
        "amount":"20",
        "currencyCode":"USD"
    },
    "totalTaxAmount":{
        "amount":"0.5",
        "currencyCode":"USD"
    },
    "totalOrderAmount":{
        "amount":"20.5",
        "currencyCode":"USD"
    },
    "totalChargeAmount":{
        "amount":"20.5",
        "currencyCode":"USD"
    },
    "totalDiscountAmount":{
        "amount":"5",
        "currencyCode":"USD"
    }
}

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. Complete checkout

When the buyer clicks purchase to complete checkout, Amazon Pay will invoke this event handler. You need to take the data from the event and perform a Finalize Checkout Session API call to complete the checkout.

/** 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,
      }),
    });
  } catch (err) {
    // something went wrong with your server call
    console.err(err);
    return {
      status: "error",
      reasonCode: "unknownError",
    };
  }
};

onCompleteCheckout event input

Parameter
Description
amazonCheckoutSessionId

Type: string
AmazonPay's checkoutSessionId
billingAddress

Type: Address
Buyer selected billing address
paymentDescriptor

Type: string
Amazon Pay-provided description for buyer-selected payment instrument
buyerAdditionalInfo

Type: BuyerAdditionalInfo
Additional buyer info collected on the Buy Now page (EU only)
{
    "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": "Amazon Pay Visa (1111)"
}

onCompleteCheckout handler output

No output required for this callback. Redirect the buyer to your confirmation page, when the Finalize Checkout Session API was successful.