Step4 Operation after Amazon Pay button click
Buyer experience after Amazon Pay button click
Please ignore "shipping" part in below description if you implement productType=PayOnly
１. When buyer clicks Amazon Pay button that you rendered in Step3, buyer is redireted to Amazon hosted page, and signs in with Amazon.
２. Once buyer signs in, a buyer clicks "Continue" button (meaning continue checkout with Amazon Pay) on the next page.
※ About the page
- In case of chargePermissionType=OneTime, productType=PayAndShip: A buyer sees either a simple page with "Continue as [buyer name]" button OR a page with shipping address/payment instrument selection option. Merchant cannot conrol which page to show to which buyer in principle.
- In case of chargePermissionType=OneTime, productType=PayOnly: A buyer always sees a page with payment instrument selection option.
- In case of chargePermissionType=Recurring, productType=PayAndShip and PayOnly: A buyer always sees a page with shipping address/payment instrument selection option. Also a buyer sees a [recurring] link which shows [recurringMetadata.frequency] (that is set in Amazon Pay button rendering script) in a popup when clicked.
３. After buyer click "Continue" button, a buyer is redirected to merchant's order review page.
I. Merchant operation occurs at this timing
４. A buyer sees shipping address and payment instrument provided by Amazon on merchant's order review page.
５. A buyer can revisit Amazon hosted page to choose different shipping address or payment instrument by clicking on "Change" button located to shipping address and payment instrument on merchant's order review page.
６. A buyer clicks "Place Order" button on merchant's order review page.
II. Merchant operation occurs at this timing
７. Merchant executes payment with Amazon Pay, and a buyer is redirected to Amazon hosted page and waits till payment is ready.
８. Once ready, a buyer is redireted to merchant's result page.
III. Merchant operation occurs at this timing
９. Merchant shows sucess or failure page depending on payment result.
See General flow if you want to review in a diagram.
I. Merchant operation
(Between #3 and #4 above)
1. Call Get Checkout Session API
Amazon Pay redirect buyer to checkoutReviewReturnUrl provided in Amazon Pay button rendering script.
When redirecting, Amazon Pay adds checkoutSessionId as URL parameter.
例) https://anyurl.com/review/ ?amazonCheckoutSessionId=26be7331-7dc2-4722-be22-f7e75582d3ef
When redirected, you get checkoutSessionId from URL parameter, (in sample case, it's "26be7331-7dc2-4722-be22-f7e75582d3ef") and use it as parameter to call Get Checkout Session API to get buyer's information such as payment instrument to use on your site.
- Get Checkout Session API
- If you are using SDK, you can find function by name like getCheckoutSession.
API response sample in case of chargePermissionType=OneTime, productType=PayAndShip
- shippingAddress is null for productType=PayOnly.
- In addition, in case of productType=PayOnly AND a buyer only has Amazon Gift Card on their Amazon account, billingAddress is also null. See FAQ - Things to know about Amazon Gift Card.
{
checkoutSessionId: '26be7331-7dc2-4722-be22-f7e75582d3ef',
webCheckoutDetails: {
checkoutReviewReturnUrl: 'http://localhost:3000/review/',
checkoutResultReturnUrl: null,
amazonPayRedirectUrl: null,
checkoutCancelUrl: 'http://localhost:3000/cancel/'
},
productType: 'PayAndShip',
paymentDetails: {
paymentIntent: null,
canHandlePendingAuthorization: false,
chargeAmount: null,
totalOrderAmount: null,
softDescriptor: null,
presentmentCurrency: null,
allowOvercharge: null,
extendExpiration: null
},
chargePermissionType: 'OneTime',
orderType: null,
recurringMetadata: null,
paymentMethodOnFileMetadata: null,
merchantMetadata: {
merchantReferenceId: null,
merchantStoreName: null,
noteToBuyer: null,
customInformation: null
},
supplementaryData: null,
buyer: {
name: 'Pay Tester',
email: 'jp-amazonpay-tester@amazon.co.jp',
buyerId: 'amzn1.account.AFxxxxxx',
primeMembershipTypes: null,
phoneNumber: '0312345678'
},
billingAddress: null,
paymentPreferences: [ { paymentDescriptor: 'Visa ****1111 (Amazon Pay)' } ],
statusDetails: {
state: 'Open',
reasonCode: null,
reasonDescription: null,
lastUpdatedTimestamp: '20230829T102329Z'
},
shippingAddress: {
name: '七姓 名',
addressLine1: '目黒区下目黒1－8－1 メゾン・コート 101号',
addressLine2: null,
addressLine3: null,
city: null,
county: null,
district: null,
stateOrRegion: '東京都',
postalCode: '153-0064',
countryCode: 'JP',
phoneNumber: '09011112222'
},
platformId: null,
chargePermissionId: null,
chargeId: null,
constraints: [
{
constraintId: 'ChargeAmountNotSet',
description: 'chargeAmount is not set.'
},
{
constraintId: 'CheckoutResultReturnUrlNotSet',
description: 'checkoutResultReturnUrl is not set.'
},
{
constraintId: 'PaymentIntentNotSet',
description: 'paymentIntent is not set.'
}
],
creationTimestamp: '20230829T102316Z',
expirationTimestamp: '20230830T102316Z',
storeId: 'amzn1.application-oa2-client.czzzzzzzzzz ',
providerMetadata: { providerReferenceId: null },
releaseEnvironment: 'Sandbox',
checkoutButtonText: null,
deliverySpecifications: null,
tokens: null
}
2. Show shipping address and payment instrument on your order review page
Using Get Checkout Session API response, show information on your order review page.
- buyer: Amazon accountholder's information
- shippingAddress: Shipping address information
- paymentDescriptor: Payment instrument information
- billingAddress: Address linked to selected payment instrument
Some data may be null or there are difference between sandbox and live. See Address and Payment instrument Detail.
3. Add "Change" button for shipping address and payment instrument respectively
Add "Change" button for shipping address and payment instrument respectively, and implement bindChangeAction to each button. See Integration Guide - Enable shipping and payment updates for how-to implement bindChangeAction.
By implementing this, a buyer can revisit Amazon hosted page to change shipping address and payment instrument to whichever they have on Amazon account. After they changed, they will click on "Continue" button on Amazon hosted page, and Amazon redirects buyer again to checkoutReviewReturnUrl. So you call Get Checkout Session API again to get updated shipping address and payment instrument to show on your order review page. (Please note checkoutSessionId is same (no change) even after this operation.)
Why bindChangeAction needs to be implemented?
→ As explained in #2 in "Buyer experience after Amazon Pay button click" above, a buyer doesn't always see a page with shipping address/payment instrument selection option. When a buyer sees a simple page with "Continue as [buyer name]" button, Amazon Pay returns default shipping address and payment instrument in Get Checkout Session API response without buyer choice. A buyer may want to use different shipping address/payment instrument this time, so you need to implement bindChangeAction to enable buyer change shipping address/payment instrument to whichever they prefer on Amazon account.
II. Merchant operation
(Between #6 and #7 above)
1. Call Update Checkout Session API
Wnen a buyer clicks "Place Order" button on order review page, call Update Checkout Session API.
Purpose of Update Checkout Session is to inform Amazon the final checkout amount and your preference on captureing payment. Without these information, you cannot proceed to complete checkout.
Update Checkout Session request body sample as below.
{
"webCheckoutDetails": {
"checkoutResultReturnUrl": "http://localhost:3000/result/"
},
"paymentDetails": {
"paymentIntent": "Authorize",
"canHandlePendingAuthorization":false,
"chargeAmount": {
"amount": "1000",
"currencyCode": "JPY"
}
},
"merchantMetadata": {
"merchantReferenceId": "Merchant reference ID",
"merchantStoreName": "Merchant store name",
"noteToBuyer": "Note to buyer",
"customInformation": "Custom information"
}
}
chekoutResultReturnUrl: Set URL where Amazon Pay redirects buyer when Amazon payment preparation is ready.
paymentDetails
See merchantMetadata
Some of value set in merchantMetadata are used in emails sent from Amazon to a buyer. See FAQ - I want to know what information is shown on email from Amazon to a buyer.
If you are using SDK, you can find function by name like updateCheckoutSession.
2.Redirect to amazonPayRedirectUrl
When all necessary information is sent to Amazon by Update Checkout Session API, you will receive URL in API response: webCheckoutDetails.amazonPayRedirectUrl
When you receive this, redirect to URL provided in webCheckoutDetails.amazonPayRedirectUrl. When redirected, buyer will be in #7 state.
III. Merchant operation
(Between #8 and #9 above)
Call Complete Checkout Session API
After you redirect to URL (in webCheckoutDetails.amazonPayRedirectUrl), Amazon Pay will start final step for payments, and once ready, Amazon Pay redirects buyer to checkoutResultReturnUrl provided in Update Checkout Session API.
When redirecting, checkoutSessionId is added as URL parameter.
i.e. https://anyurl.com/result/ ?amazonCheckoutSessionId=26be7331-7dc2-4722-be22-f7e75582d3ef
When redirected, get checkoutSessionId from URL parameter, (in sample case, it's "26be7331-7dc2-4722-be22-f7e75582d3ef") and use it as parameter to call Complete Checkout Session API to complete payment.
Complete Checkout Session API request body sample as below.
{
"chargeAmount": {
"amount": "1000",
"currencyCode": "JPY"
}
}
- See chargeAmount
- See Complete Checkout Session API
- If you are using SDK, you can find function by name like completeCheckoutSession.
In case API response was success （HTTP status code: 200 or 202)
You will find chargePermissionId and chargeId in API resopnse, so save these Ids with your order data.
chargeId isn't returned in API response if paymentDetails.paymentIntent is set to Confirm in Update Checkout Session API (because Amazon Pay doesn't obtain Authorization when paymentIntent=Confirm）
- See chargePermissionId
- See chargeId
HTTP status code: 200
When process is complete, shows order confirmation page.
HTTP status code: 202
Wnen canHandlePendingAuthorization is set to true, and charge is in AuthorizationInitiated state, Amazon Pay returns HTTP status code 202.
In this case, Authorization is performed asynchronously. It takes up to 24 hours to obtain Authorization, so you need to call Get Charge API at a certain interval to get final authorization status.
When you receive HTTP status code 202, it means respective order is not fully accepted yet, so please show appropriate information to a buyer on order confirmation page.
In case API response was error
Handle errors appropriately. See Integration Guide - Manage Errors
- When Complete Checkout Session was not succesfully performed regardless of sucessfull completion of Update Checkout Session or redirect, it means respective payment was failed. Make sure to create order on your end upon successful completion of Complete Checkout Session API.
- Checkout Session represents a single active session (or engagement) for the buyer on your website. So once checkout session is finished (regardless of success or error), Checkout Session finishes its job and is deleted after a certain period. When checkout is completed successfully, information held by Checkout Session is replicated to Charge Permission object. So if you need to get buyer or payment information after checkout, call Get Charge Permission API instead of Get Checkout Session API.
- You can only get details from Charge Permission for 30 days after the time that the Charge Permission was created.