General flow

Flow diagram

Below diagram shows website page transitioning together with merchant and Amazon Pay processes involved. Diagram is horizontal, and flows from left to right. Scroll the diagram to the right to see all flow.

OneTime Amazon Pay flow

Merchant site

Amazon Pay Hosted page in general

Amazon Pay Hosted page redirect to merchant site

Merchant processing after buyer signs in with Amazon

Merchant site after Get Checkout Session

Merchant processing after "Place Order"

Amazon Pay Hosted page

Merchant processing

Merchant site

Merchant adds Amazon Pay button rendering script to show Amazon Pay button on merchant site.
The buyer clicks Amazon Pay button.

● ● ●

Cart page

▶︎

The buyer is redirected to Amazon Pay Hosted page, and sign-in with Amazon ID and Password.

▶︎

After sign-in is complete, buyer is redirected to either "a page where buyer can select shipping address+payment instrument" OR "a consent page", and click "Continue to checkout" button.

Merchant cannot control which page to show to buyers in principle.

Hosted Page for shipping address/payment instrument selection
For productType="PayAndShip"

Merchant

Shipping address

Change

Test Taro 153-0064 Shimomeguro 1-8-1, Meguro, Tokyo0

Payment instrument

Change

VISA xxxx1111

Cancel Amazon Pay, and return to xxx >

For productType="PayOnly"

Merchant

Payment instrument

Change

VISA xxxx1111

Cancel Amazon Pay, and return to xxx >

When the buyer clicks "Change" button

Please select shipping address

◉ Test Seimei

1530064

Shimomeguro 1-8-1, Meguro, Tokyo

Japan

○ Test Meispace

153-0064

Shimomeguro 1-8-1, Meguro, Tokyo

Japan

+ Add new address

Please select payment instrument

◉ VISA xxxx1111

xxx

Expiry 05/2023

○ American Express xxxx0005

xxxx

Expiry 05/2023

Hosted Page with consent
For productType=PayAndShip

✔️

Signed in with Amazon account

Cancel Amazon Pay, and return to xxx >

▶︎

When the buyer clicks "Continue to checkout" button, Amazon Pay redirects buyer to checkoutReviewReturnUrl set in createCheckoutSessionConfig.payloadJSON by merchant. Amazon Pay adds amazonCheckoutSessionId as a URL parameter.

i.e. https://anyurl.com/review/? amazonCheckoutSessionId=26be7331-7dc2-4722-be22-f7e75582d3ef

▶︎

Merchant then call Get Checkout Session API with amazonCheckoutSessionId.
Merchant receives shipping address, payment instruments as API response

Ref: Get Checkout Session response

▶︎

Merchant shows information received in API response (shipping address, payment instrument and etc) on merchant order review page

● ● ●

Order review page

Shipping address

Change

〒153-0064

Shimomeguro 1-8-1, Meguro, Tokyo

Amazon Taro

Payment instrument

Change

VISA 1111xxxx (Amazon Pay)

Order detail

Item

Proce

Quant.

Total

Coffee beans

¥2,000

Coffee cup

¥500

Total

¥2,500

About shipping address and name
In case of productType=PayAndShip, Merchant uses "shippingAddress" provided by Amazon Pay to render shipping address on the site.

Note
- "shippingAddress" is included in Get Checkout Session API response.
There are some fields not used in Japan, so please be careful. For detail, please check Address and Payment instrument Detail
- In addition, name and address may NOT be in the form as merchant prefers (such as first-name and last-name are not split, city and detail address are not split).
- Moreover, there is no "furigana" provided from Amazon Pay.

In order to support merchants to deal with such challenges, Amazon Pay provides sample code to split name (into first name and last name) and address (into general Japanese address format). There is a sample code to generate "furigana" from kanji name as well.
Please find sample code from below;
・ amazonpay-divider: This sample code divides name and address in preferred format
・ furigana generator: This sample code divides name and generates "furigana" through prediction conversion from Kanji name.

About payment instrument
Merchant uses "paymentPreferences > paymentDescriptor" provided by Amazon Pay to render payment instrument on the site.

Note
"paymentPreferences > paymentDescriptor" is included in Get Checkout Session API response.
Value is returned in one string;

"paymentDescriptor": "Visa ****1111 (Amazon Pay)"

so you show it on the site as is.

In case Amazon Gift Card is selected as a payment instrument by the buyer, Amazon Pay returns paymentDescriptor like

"paymentDescriptor": "Amazon Gift Card and Visa ****6069 (Amazon Pay)"

Please refer to Basics - Object - Address and Payment Instrument Detail for detail of Gift Card

For buyer to change shipping address or payment instrument on your order review page, merchant put "change" button on the site, and implement bindChangeAction to "change" button.
With this, the buyer will be redirected to Amazon Pay Hosted page again to change them, and comes back to your site again.
Please see Integration Guide - Enable shipping and payment updates for more detil.

Some merchants ask us how to use this "Change" button for buyer to change to other payment methods (other than Amazon Pay). 
The order review page like the screen shown as an example below is the page where buyer sees AFTER they sign-in with Amazon Pay, and the buyer already chose Amazon Pay as a payment method for this checkout when they arrive on this page. Thus, please use this "Change" button to enable buyer change their payment instrument to another one on Amazon hosted page.

● ● ●

Order review page

Shipping address

Change

〒153-0064

Shimomeguro 1-8-1, Meguro, Tokyo

Amazon Taro

Payment instrument

Change

VISA 1111xxxx (Amazon Pay)

Order detail

Item

Price

Quant.

Total

Coffee beans

¥2,000

Coffee cup

¥500

Total

¥2,500

When the buyer clicks "Change" button, the buyer is redirected to Amazon Pay Hosted page where they can change shipping address and payment instrument.
For productType="PayAndShip"

Merchant

Shipping address

Change

Test Seimei 153-0064 Shimomeguro 1-8-1, Meguro, Tokyo

Payment instrument

Change

VISA xxxx1111

Cancel Amazon Pay, and return to xxx >

For productType="PayOnly"

Merchant

Payment instrument

Change

VISA xxxx1111

Cancel Amazon Pay, and return to xxx >

When the buyer clicks "Change" button

Please select shipping address

◉ Test Seimei

1530064

Shimomeguro 1-8-1, Meguro, Tokyo

Japan

○ Test Meispace

153-0064

Shimomeguro 1-8-1, Meguro, Tokyo

Japan

+ Add new address

Please select payment instrument

◉ VISA xxxx1111

xxx

Expiry 05/2023

○ American Express xxxx0005

xxxx

Expiry 05/2023

▶︎

The buyer clicks "Place Order" button.

● ● ●

Order review page

Shipping address

Change

〒153-0064

Shimomeguro 1-8-1, Meguro, Tokyo

Amazon Taro

Payment instrument

Change

VISA 1111xxxx (Amazon Pay)

Order detail

Item

Price

Quant.

Total

Coffee beans

¥2,000

Coffee cup

¥500

Total

¥2,500

▶︎

Merchant calls Update Checkout Session API to update final order amount and paymentIntent to respective CheckoutSession using amazonCheckoutSessionId.

Please note there are three values supported with paymentIntent, and depeneding on paymentIntent, subsequent processes varies. Find more detail with Specification - Parameter - PaymentIntent

When Update Checkout Session succeeds, Amazon Pay returns amazonPayRedirectUrl in API response. Merchant then redirects to amazonPayRedirectUrl.

You will find below in "webCheckoutDetails" in Update Checkout Session API response;
"amazonPayRedirectUrl": "https://pay.amazon.com/redirect/checkoutId-1"

Ref: Integration Guide - Update Checkout Session response sample

▶︎

When process successfully completes, Amazon Pay redirects to checkoutResultReturnUrl set by merchant in payloadJSON. webCheckoutDetails.checkoutResultReturnUrl.

Amazon Pay adds amazonCheckoutSessionId as a URL parameter

i.e. https://anyurl.com/result/?amazonCheckoutSessionId=26be7331-7dc2-4722-be22-f7e75582d3ef

▶︎

Merchant then calls Complete Checkout Session API to complete checkout.

Amazon Pay returns chargePermissionId and maybe chargeId in API response.
Merchants needs these IDs for subsequent processes, so merchant needs to save them in their database linked to respective order information

Ref: Integration Guide - Complete Checkout Session response sample

There is a chance that payment process fails, so merchant needs to implement error handling properly.

Error handling
Re: Integration Guide - Manage erros

▶︎

Merchant shows order confirmation page.

● ● ●

Order confirmation page

✔️

Recurring Amazon Pay flow

Merchant site		Amazon Pay Hosted page in general
Merchant adds Amazon Pay button rendering script to show Amazon Pay button on merchant site. The buyer clicks Amazon Pay button. ● ● ● Cart page	▶︎	The buyer is redirected to Amazon Pay Hosted page, and sign-in with Amazon ID and Password.	▶︎	After sign in is complete, buyer is redirected to a page where buyer can select shipping address+payment instrument, and click "Continue to checkout" button. For Recurring The buyer sees "Recurring" link on Amazon Pay Hosted page, and when the buyer clicks the link, Amazon Pay shows recurring frequency that merchant set in recurringMetaData (i.e. 1 month, 1 year etc). Recurring Hosted Page for shipping address/payment instrument selection For productType="PayAndShip" Merchant Shipping address Change Test Taro 153-0064 Shimomeguro 1-8-1, Meguro, Tokyo0 Payment instrument Change VISA xxxx1111 Recurring Cancel Amazon Pay, and return to xxx > For productType="PayOnly" Merchant Payment instrument Change VISA xxxx1111 Recurring Cancel Amazon Pay, and return to xxx > Hosted Page with consent For Recurring, the buyer always sees shipping address and/or payment instrument page. When the buyer clicks "Recurring" link Payment will be processed every xxx *Amazon Pay shows recurringMetaData.frequency set by merchant in "xxx" (i.e. 1 month, 2year etc)	▶︎	Flow continues as General flow - Amazon Pay Hosted page redirect to merchant site.

Difference between OneTime and Recurring

There is no big difference between the two in terms of buyer experience, but note below for Recurring;

You need to Create Charge against Charge Permission from next payment onwards by calling Create Charge API (Amazon doesn't initiate Charge on-behalf of you).
When buyer change or cancels Recurring payment, you need to update or close Charge Permission.

Details are explained in Integraiton Steps section.