Address and Payment instrument Detail
You can get buyer information, address and payment instrument from Checkout Session (post-checkout, you get similar information from Charge Permission).
Note that you can only get these data from Charge Permission under following condition:
- OneTime: in the first 30 days after the time the Charge Permission was created.
- Recurring: during Charge Permission is in Open State or for up to 30 days after the Charge Permission is closed
See Integration Guide - Charge Permission for detail.
Buyer information and address
Checkout Session: buyer
| Item | Description | Note |
|---|---|---|
| buyerId | Amazon user account ID | Unique ID of Amazon user account. Amazon Pay returns different buyerId by merchant for security reasons |
| name | Name of the Amazon user | - Name is provided in single string. Last name and first name are not separated. - Name can be nickname (not formal name, depending on what is registered by user). Country Difference [Japan]: If you need to split last name and first name or need furigana, see sample script. |
| Email address of the Amazon user | ||
| phoneNumber | Phone number of Amazon user's billing address | Phone number can be in the format such as 0312345678, 03-1234-5678 (w or w/o hyphen, 1-byte or 2-byte character) Phone number is returned in API response when: - In case of productType = PayAndShip, you put phoneNumber in scopes parameter in Amazon Pay button rendering script payload. - In case of productType = PayOnly, two ways to get phoneNumber; 1) you put phoneNumber in scopes parameter in Amazon Pay button rendering script payload. 2) you don't set scopes parameter at all. |
See Integration Guide – Generate the Create Checkout Session payload for scopes.
Checkout Session: shippingAddress
| Item | Description | Note |
|---|---|---|
| CountryCode | Country Code | ISO3166 format: Japan = JP |
| Name | Name | - Name is provided in single string. Last name and first name are not separated. - Name can be nickname (not formal name) depending on what is registered by user. Country Difference [Japan]: If you need to split last name and first name or need furigana, see sample script. |
| PostalCode | Postal code | i.e. 153-0064 or 1530064 (with or without hyphen, 1-byte or 2-byte character) |
| StateOrRegion | Prefecture | If you want to limit stateOrRegion chosen by buyer, use addressRestriction in Amazon Pay button rendering script's payload. See Integration Guide - payload sample Country difference [Japan]: Amazon Pay returns “Prefecture/State” such as "東京都" , "北海道" in this field. Prefeture could be "東京" or "Tokyo-to" depending on buyer's input on Amazon account. |
| City | Country difference [Japan]: Value is returned in SANDBOX, but not returned in Live. Instead, “AddressLine3” maybe returned an alternative. | |
| Country | Country difference [Japan]: Not used in Japan | |
| District | Country difference [Japan]: Not used in Japan | |
| AddressLine1 | Address Line 1 | Amazon Pay returns value in this field as mandatory. |
| AddressLine2 | Address Line 2 | May be no value returned in this field. |
| AddressLine3 | Address Line 3 | - May be no value returned in this field. - Company name or apartment name maybe returned in this field. - If you want to test this field, add value to this field when adding new address on Amazon hosted page (see How to add Japanese address on Amazon Hosted page in sandbox below). Country difference [Japan]: “AddressLine3” is available as an alternative to City field. This doesn't mean City value is returned in AddressLine3 field, but Amazon may return some portion of address in this field as an additional field. |
| PhoneNumber | Phone Number | Optional i.e. 0312345678 or 03-1234-5678 (w or w/o hyphen, 1-byte or 2-byte character. Special character like #8234 may also be included） |
How to add Japanese address on Amazon Hosted Page in sandbox
- Go to our demo site and click Amazon Pay button to move to Amazon Hosted Page, and sign in with your Amazon Pay test account. (See FAQ: I want to know how to create my test account as needed)
- After signed in, you will be redirected to Order Review page. On this page, click "お届け先修正" (edit address) button to re-visit Amazon hosted page.
- On Amazon hosted page page, click 変更 (Change) button located beside お届け先住所 (Shipping Address). It shows you a list of shipping address (below image on the left)
- If you click 新しい住所を追加 (add new address) located at the bottom of shipping address list, shipping address input form opens (below image on the right), so you can add new address as prefered.
Mapping Table - Input form field vs shipping address field in API response
| Input form field | Description | Shipping address field returned |
|---|---|---|
| Field 1 | 国/地域 (Country) | CountryCode |
| Field 2 | 氏名 (Name) | Name |
| Field 3 | 電話番号 (Phone number) | phoneNumber |
| Field 4 | 郵便番号 (Postal Code) | postalCode |
| Field 5 | 都道府県 (Prefecture) | StateOrRegion |
| Field 6 | 市区町村 (City) | AddressLine1 |
| Field 7 | 丁目・番地・号 (Municipalities) | AddressLine2 |
| Field 8 | 建物名/会社名 + 部屋番号 (Building/apartment room number etc) | AddressLine3 |
Note above mapping is an ideal case when buyer registers their address using latest Amazon address form. There was a time when buyer could input their address in more flexible form in past (less validation implemented at that time). Such data may not be perfectly mapped as above. Below table shows ideal case and bad case comparison. Make sure to handle both cases when you use address provided by Amazon Pay.
| Shipping address field returned | a) Ideal case | b) Bad case |
|---|---|---|
| postalCode | Postal code | Postal code |
| stateOrRegion | Prefecture | Prefecture |
| addressLine1 | City OR Municipalities | City + Municipalities + Town and street number |
| addressLine2 | Town and street number | Building / Company name / Apartment room number |
| addressLine3 | Building / Company name / Apartment room number | null |
Why this happens?
In case buyer registers shipping address via the latest form on Amazon site, each field should look like (a) in above table.
However, if the shipping address has been registered via older form on Amazon site, it may look like (b) in above table.
If you need to map them strictly, use sample script to map each fields as (a).
Checkout Session: billingAddress
billingAddress is address attached to payment instrument registerd by buyer on Amazon account.
Fields in billingAddress are same with shippingAddress.
billingAddress is returned in API response in following cases;
In case of PayAndShip
Put billingAddress in scopes parameter in Amazon Pay button rendering script payload.
In case of PayOnly
Two ways to get billingAddress;
1) Put billingAddress in scopes parameter in Amazon Pay button rendering script payload.
2) Don't set scopes parameter at all.
See Integration Guide – Generate the Create Checkout Session payload for scopes detail.
- billingAddress is null when productType=PayOnly and buyer only has Gift Card on Amazon account regardless of scopes setting.
- billingAddress is same with shippingAddress when productType=PayAndShip and buyer only has Gift Card on Amazon account regardless of scopes setting.
- Sandbox returns fixed billingAddress (same billingAddress information) for all payment instrument.
Japan Specific - Name and address adjustmens
- Name is not split into first name and last name.
- No "furigana".
- Address may not be split into general Japanese address format.
- Some buyers maybe with no "shi-ku-cho-son" (municipalities).
- City field is not used in live while it's used in sandbox.
- One of the addressLine1 or addressLine2 or addressLine3 must be filled with address at least.
- space maybe included in addressLine1 and addressLine2 and addressLine3.
For spliting first name and last name or to get furigana, see:
- 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.
Payment instrument
Below is Amazon hostd page payment instrument example.
The merchant does not need any special settings to enable GC on their integration.
If it is selected (default is to use all GC balance), the GC balance will be used for the amount of order in preference to the credit card.
The buyer can uncheck to use Amazon GC on Hosted change flow.
Also, buyer can add GC code on it.
As a result of payment instrument selected on Amazon hosted page, you get paymentDescriptor in API response. Below are some example of payment descriptor.
“Amazonギフトカード (Amazon Pay)meaning Only Gift CardAmazonギフトカード と Visa ****6069 (Amazon Pay)meaning Gift Cart and Credit CardVisa ****6069 (Amazon Pay)meaning Only Credit Card
Note you need special attention for Gift Card as it behaves different from other payment instruments:
- If buyer only has Amazon Gift Card on their Amazon account, you cannot do either over-charge or over-refund.
- Gift Card balance is deducted (called "encumbered" at Amazon) when merchant redirects to amazonPayRedirectUrl during checkout session completion (implementation detail is explained in Flow chapter)
- Gift Card balance is released back to buyer account when;
- Charge Permission is closed and Charge is canceled.
- Charge gets declined
- Partial captured is completed (this means remaining Charge balace is no longer used, so the balance will be released back to buyer)
- Charge is expired
- Gift Card is NOT available on sandbox.
- When buyer only has Gift Card on Amazon account and productType=PayOnly, billingAddress cannot be retrieved from Checkout Session regardless of scopes setting.