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.