Merchant Onboarding And Account Management APIs

Overview

The account management APIs in JP region enable a partner to onboard a merchant onto Amazon Pay programatically. The APIs can only be invoked by authorised Solution Provider in JP. Please reach out to your Amazon Pay business representative if you need to access these APIs.

Supported operations

Create Merchant Account API - POST https://pay-api.amazon.jp/:environment/v2/merchantAccounts
Update Merchant Account API - PATCH https://pay-api.amazon.jp/:environment/v2/merchantAccounts/:merchantAccountId
Merchant Account Claim API - POST https://pay-api.amazon.jp/:environment/v2/merchantAccounts/:merchantAccountId/claim

Download the Amazon Pay SDK if one is available for your programming language.

Environments supported :

live
sandbox

1. Integrating with Amazon Pay
2. API General Information
3. API detailed information
4. Data Model
5. Sample Request-Response
6. Error Codes
7. Differences between Environments
8. API Throttling Limits

1. Integrating with Amazon Pay

(Guide on How to use API Combination for Partners according to the Business Model at their end)

1.1. For a partner with a business model where each account is linked to a single shop on the partner’s side

Our recommendation for a business model where each account having a business legal entity linked to a single shop having all the KYC related details (for example : BusinessAddress, Legal Representative details, Point of Contact details etc.) are :

Integrate with Create Merchant Account API : Create Merchant account API will help to create an AmazonPay Merchant Account along with a default AmazonPay store where the domainUrls (where the AmazonPay button needs to be rendered) reside for the Business along with other personalized checkout related details such as storeName, description and privacyPolicyUrl .
Integrate with Update Merchant Account API : Update Merchant account API will help to update Merchant Account and store details.
Integrate with Merchant Account Claim API : The Merchant Account Claim API will assist CSPs in enabling their merchants to access their respective Amazon Pay Merchant accounts, that were created via Create Account API.

1.2. For a partner with a Business Model where multiple shops are managed under a Single Account on the partner’s side

1.2.1. In a single account, each shop has its own business legal entity

Our recommendation for a business model where each account can be linked to multiple shops having separate business legal entities needs to call the below set of APIs for each shop :

Integrate with Create Merchant Account API : Create Merchant account API will help to create an AmazonPay Merchant Account along with a default AmazonPay store where the domainUrls (where the AmazonPay button needs to be rendered) reside for the Shop along with other personalized checkout related details such as details storeName, description and privacyPolicyUrl .
Integrate with Update Merchant Account API : Update Merchant account API will help to update Merchant Account and store details.
Integrate with Merchant Account Claim API : The Merchant Account Claim API will assist CSPs in enabling their merchants to access their respective Amazon Pay Merchant accounts, that were created via Create Account API.

1.2.2. All stores have the same KYC and other details, just different branding of shops

Our recommendation for a business model where each account can be linked to multiple shops having one business legal entity, but shops have different branding :

Integrate with Create Merchant Account API : Create Merchant account API will help to create an AmazonPay Merchant Account along with multiple AmazonPay stores where the domainUrls (where the AmazonPay button needs to be rendered) reside for the Business along with other details such as storeName, description and privacyPolicyUrl .
Integrate with Update Merchant Account API : Update Merchant account API will help to update Merchant Account and store details. It will also help to create new stores if externalStoreId is passed in the request.
Integrate with Merchant Account Claim API : The Merchant Account Claim API will assist CSPs in enabling their merchants to access their respective Amazon Pay Merchant accounts, that were created via Create Account API.

2. API General Information

SL.No.	Region	Endpoint
1	JP	pay-api.amazon.jp

curl
-X POST
-H "content-type:application/json"
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-H "x-amz-pay-authToken:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
-d @request_body

Name	Location	Description	Type	Mandatory (Create Merchant Account)	Mandatory (Update Merchant Account)	Mandatory (Merchant Account Claim)	Mandatory (Create Store)	Mandatory (Update Store)
authorization	Header	Signing requests	String	Required	Required	Required	Required	Required
x-amz-pay-date	Header	UTC timestamp of when the request is made in ISO 8601 format. This header is required for every request Example: "20190805T051457Z"	String	Required	Required	Required	Required	Required
content-type	Header	Content type of the request body. Must be "application/json". This header is required for every request	String	Required	Required	Required	Required	Required
x-amz-pay-authToken	Header	This token is needed to make delegated calls on behalf of a merchant. The token will be received in CreateMerchantAccount Response Payload	String	No	Required	No	Required	Required

3. API detailed information

3.1. Create Merchant Account API

Provide merchant info through this API to create loginable account for your merchant partners. Client (CSP) should expect either a success message or a detailed error message based on data validation and fulfillment.

Client should expect either success message or a detailed error message based on data validation and fulfilment.

Note: By invoking the API, you are agreeing to share/send merchant data to Amazon Pay.

Path: POST /live/v2/merchantAccounts

Note : For testing purpose, please use our Sandbox environment.

Path: POST /sandbox/v2/merchantAccounts

Request:

{
    "uniqueReferenceId": String,           //mandatory
    "ownerAccountId": String,              //optional
    "ledgerCurrency": ENUM                 //mandatory [JPY]
    "businessInfo" : BusinessInfo,         //mandatory
    "primaryContactPerson" : Person,       //optional
    "beneficiaryOwners" : [Person],        //mandatory
    "stores" : [Store],                    //mandatory
    "integrationInfo" : IntegrationInfo,   //optional
    "merchantStatus" : MerchantStatus      //mandatory
}

-------

BusinessInfo: {
    "email" : String,                      //mandatory
    "businessCategory": ENUM,              //mandatory
    "countryOfEstablishment" : String,     //mandatory (JP)
    "businessType" : ENUM,                 //mandatory (CORPORATE)
    "businessLegalName" : String,          //mandatory
    "businessAddress" : AddressInfo,       //mandatory
    "businessDisplayName" : String,        //mandatory
    "customerSupportInformation" : CustomerSupportInformation  //optional
    "annualSalesVolume": Price              //optional
}

AddressInfo: {
    "addressLine1" : String,                //mandatory
    "addressLine2" : String,                //optional
    "city" : String,                        //optional
    "stateOrRegion" : String,               //optional
    "postalCode" : String,                  //mandatory
    "countryCode" : String                  //mandatory
}

CustomerSupportInformation : {
    "customerSupportEmail" : String,            //optional
    "customerSupportPhoneNumber" : PhoneNumber  //optional
}

PhoneNumber: {
    "countryCode" : String,                //mandatory
    "number" : String,                     //mandatory
    "extension" : String                   //optional
}

Person: {
    "personFullName" : String,             //mandatory
    "residentialAddress" : AddressInfo,    //optional
}

Price: {                   
    "amount" : String,                     //mandatory
    "currencyCode" : String  //ISO(4217)   //optional
}

Store: { 
    "externalStoreId": String,             //optinal (mandatory in case of creating multistores)
    "domainUrls": List<String>,            //mandatory 
    "storeName": String,                   //optional 
    "privacyPolicyUrl": String,            //optional
    "storeStatus": {                       //optional
        "state": ENUM,                     //mandatory
        "reasonCode": ENUM                 //optional
    } 
}

IntegrationInfo: {
    "ipnEndpointUrls" : List<String>        //optional
}

merchantStatus: {
    "statusProvider" : String,            //optional (Mandatory in case of Active state)
    "state" : ENUM,                       //mandatory
    "reasonCode": ENUM                    //optional
}

Response:

Returns HTTP Status 201 (Created) if the operation was successful.

Response : Single-Store Creation

{
    "uniqueReferenceId": "UNIQUE_REFERENCE_ID",
    "ownerAccountId": "OWNER_ACCOUNT_ID",             //(if passed in the request)
    "merchantAccountId" : "AMAZON_PAY_MERCHANT_ID",
    "authorizationToken" : "AUTHORIZATION_TOKEN",
    "storeIdList": [{"storeId" : "String"}]
}

Response : Multi-Store Creation

{
    "uniqueReferenceId": "UNIQUE_REFERENCE_ID",
    "ownerAccountId": "OWNER_ACCOUNT_ID",           //(if passed in the request)
    "merchantAccountId" : "AMAZON_PAY_MERCHANT_ID",
    "authorizationToken" : String, 
    "storeIdList": [{
        "externalStoreId" : "externalStoreId1",    //(passed in the request)
        "storeId" : "storeId1"
        },
        {
        "externalStoreId" : "externalStoreId2",   //(passed in the request) 
        "storeId" : "storeId2"
        }
     ]
}

MerchantAccountId and StoreId are the IDs of the resources created during the API call.For update and claim APIs, partners are to use this merchantAccountID for any subsequent calls.

Idempotency Handling

Response code HTTP Status 200 (Ok) will be returned with MerchantId and Authorization token whenever a create account call is received with the same uniqueReferenceId.
uniqueReferenceId acts as an Idempotency key.

Limitation

We currently don’t support the creation of AmazonPay merchant accounts if the email is already associated with an account within amazon, we will throw a 400 HttpsStatusCode with details :

{
  "reasonCode": "InvalidRequest",
  "message": "Request parameters are either missing or invalid. Please check errorList attribute for more details",
  "errorList": [
    {
      "reasonCode" : "EmailAlreadyInUse",
      "parameterName" : "businessInfo.email",
      "message" : "The emailId is already in use"
    },
  ]
}

In this case, a merchant needs to come via Web Based Registration [Link] with a different emailId and complete the Registration.

3.2 Update Merchant Account API

Updates a merchant account and store for the given Amazon merchantAccountId. Partners are only able to update fields which do not change the legal business entity itself and till the account is claimed. Partner (That supports multi-branding within a store) can even create and update additional stores using this API.

Path: PATCH /live/v2/merchantAccounts/:merchantAccountId

Note : For testing purpose, please use our Sandbox environment.

Path: PATCH /sandbox/v2/merchantAccounts/:merchantAccountId

Request :

{
    "businessInfo" : BusinessInfo,          //optional
    "primaryContactPerson" : Person,        //optional
    "beneficiaryOwners" : [Person],         //optional
    "stores" : [Store],                     //optional
    "integrationInfo" : IntegrationInfo,    //optional
    "merchantStatus" : MerchantStatus       //optional
}

-------

BusinessInfo: {
    "email" : String,                       //optional
    "businessCategory": ENUM,               //optional
    "businessLegalName" : String,           //optional
    "businessAddress" : AddressInfo,        //optional
    "businessDisplayName" : String,         //optional
    "customerSupportInformation" : CustomerSupportInformation      //optional
    "annualSalesVolume" : Price                                    //optional
}

AddressInfo: { //AddressInfo itself is Optional field but if needs an update, you needs to pass all the mandatory parameters listed below
    "addressLine1" : String,                //mandatory
    "addressLine2" : String,                //optional
    "city" : String,                        //optional
    "stateOrRegion" : String,               //optional
    "postalCode" : String,                  //mandatory
    "countryCode" : String                  //mandatory
}

CustomerSupportInformation : {
    "customerSupportEmail" : String,              //optional
    "customerSupportPhoneNumber" : PhoneNumber    //optional
}

PhoneNumber: { //PhoneNumber itself is Optional field but if needs an update, you needs to pass all the mandatory parameters listed below
    "countryCode" : String,                 //mandatory
    "number" : String,                      //mandatory
    "extension" : String                    //optional
}

Person: {
    "personFullName" : String,             //optional
    "residentialAddress" : AddressInfo,    //optional
}

Price : {
    "amount" : String,                     //optional
    "currencyCode" : String  //ISO(4217)   //optional
}

Store: { 
    "storeId": String,                     //mandatory (Optional in case of new Store creation)
    "externalStoreId": String,             //Optional  (Will create new Store if passed)
    "domainUrls": List<String>,            //optional
    "storeName": String,                   //optional
    "privacyPolicyUrl": String,            //optional
    "storeStatus": { 
        "state": ENUM,                      //optional
        "reasonCode": ENUM                  //optional
    } 
}

IntegrationInfo: {
    "ipnEndpointUrls" : List<String>        //optional
}

merchantStatus: {
    "statusProvider" : String,             //optional 
    "state" : ENUM,                        //optional
    "reasonCode": ENUM                     //optional
}

Response :

Return HTTP Status 200 (Ok) if the operation was successful.

{
    "uniqueReferenceId" : "UNIQUE_REFERENCE_ID",
    "merchantAccountId" : "AMAZON_PAY_MERCHANT_ID",
    "storeIdList": [{"storeId" : "amz.storeId"}]
}

New Store Creation [if externalStoreId passed in request] :

{
    "uniqueReferenceId" : "UNIQUE_REFERENCE_ID",
    "merchantAccountId" : "AMAZON_PAY_MERCHANT_ID",
    "storeIdList": [{
        "externalStoreId" : "externalStoreId", 
        "storeId" : "storeId"
      }
    ]
}

3.3. Merchant Account Claim API

Once the merchant account is created using the above CreateMerchantAccount API’s, CSP’s will need to integrate with claimAccount API to allow the customer to claim (get access to the merchant account). Account claim starts in Initiated state by CSP calls Merchant Account Claim API. After merchants complete their Seller Central setting, moving to Completed state.

3.3.1 Merchant Account Claim Flow

(1) There are 3 ways to trigger a claim flow.
- Apay will send Email to merchant and merchant clicks it OR
- You (CSP) will send email to merchant and merchant clicks it OR
- Merchant will see notification or button to claim Apay account on your portal, and the merchant clicks it.
Note: CSP should have an ingress point exposed on their portal to provide awareness and start the claim process
(1) The email received will have the link configured to point to your login portal, Example: https://amazoncsp.com/login.html?action=claimAPayAccount

Note: This endpoint can be decided by the CSP and needs to be provided to APay by the CSP during onboarding

Expectation: The expectation from the CSP from this endpoint is that the merchant should be redirected to CSP login portal and on successful authentication, the CSP should start the claim process by invoking the merchant Account Claim API

(2) and (3) As per the API usage contract, merchant must be first redirected to your authentication portal for login, on the click of email hyperlink.
(4) and (5) Post login, your backend will make a call to merchantAccountClaim API to start the claim process
(6) APay, as part of merchantAccountClaim API call, will return a 303 response with Initiated status. ClaimApayEndpoint (which was triggered from merchant click action and eventually called merchantAccountClaim API) must return the same 303 response to merchant browser (app/any user agent from where merchant triggered claim action) with Location header. Merchant’s browser/user agent will then be redirected to APay provided location to configure credentials for the Account | Note: This action needs to be done as is and no changes should be done by the CSP to the url returned by APay as part of the Location Header
(8) On APay, 2-Factor Authentication will be done on the email provided during account creation
(9) On successful authentication, the account claim process is complete, and the merchant will be redirected to SellerCentral

After this, Apay will return a 200 response with completed status if you call merchantAccountClaim API because merchant’s account claim is completed.

Note: We recommend that the merchant account should be claimed in 90 days, after 90 days the merchant account will not be transaction eligible, and buyers will no longer be able to use Apay for transactions on the merchant

Note: If there are some accidents during account claim process (network issue, tab closing etc.) on merchant’s end. This process including calling merchantAccountClaim API should be retried by the CSP until the account claim process is complete on merchant’s end.

3.3.2 Merchant Account Claim API

Initiates the merchant account claim process. Clients should expect a redirection response or a detailed error message based on data validation and fulfillment.

POST Path: live/v2/merchantAccounts/:merchantAccountId/claim

Note : For testing purpose, please use our Sandbox environment.

POST Path: sandbox/v2/merchantAccounts/:merchantAccountId/claim

Request:

{
    "uniqueReferenceId": String  //mandatory
}

Response:

Return HTTP Status 303 (redirection) with Location header if the operation was successful.

Response Body:

{
    "status" : "INITIATED",
    "uniqueReferenceId" : "UNIQUE_REFERENCE_ID",
    "merchantAccountId" : "AMAZON_PAY_MERCHANT_ID"
}

Response Headers：

{
    "Location" : "<redirected-URL>"
}

3.3.3 Idempotency Handling

uniqueReferenceId acts as an Idempotency key.

Before merchants complete their account claim

Response code HTTP Status 303 (redirection) will be returned with the following body and header whenever the merchant account claim API is called by the CSP.

Response Body

{
    "status" : "INITIATED",
    "uniqueReferenceId" : "UNIQUE_REFERENCE_ID",
    "merchantAccountId" : "AMAZON_PAY_MERCHANT_ID"
}

Response Headers

{
    "Location" : "<redirected-URL>"
}

After merchants complete their account claim

Response code HTTP Status 200 (Ok) will be returned with merchantAccountId whenever the merchant account claim API is called by the CSP, for an account for whom the claim process is already completed

Response Body:

{
    "status" : "COMPLETED",
    "uniqueReferenceId" : "UNIQUE_REFERENCE_ID",
    "merchantAccountId" : "AMAZON_PAY_MERCHANT_ID"
}

Response Headers:
No specific response headers related to account claim will be returned

Note: If the merchant’s claim process is completed AmazonPay will return 200(OK) response with “status” as “COMPLETED”, on receiving this CSP’s should show a message to the merchant that their account claim process is completed

4. Data Model

We will be supporting English, Hiragana, Kanji & Katakana characters (both single and full byte) as part of UTF-8.

Legend	Value
Mandatory (Create)	Fields marked are mandatory fields to create an Amazon Pay account
Can Field be updated	Fields marked cannot be updated once Amazon Pay account has been created

4.1. Type:CreateMerchantRequest

Request Parameter	Location	Value	Description	Validation	Mandatory (for Create API)
authorization	Header	Signing requests		NA	Required
x-amz-pay-date	Header	UTC timestamp of when the request is made in ISO 8601 format. This header is required for every request Example: "20190805T051457Z"		NA	Required
content-type	Header	Content type of the request body. Must be "application/json". This header is required for every request		NA	Required
uniqueReferenceId (Idempotency key)	Body	Identifier used by partners to uniquely identify merchants at their end	This value is the account identifier used to uniquely represent an account at the level where the partner collects Business KYC details. Example : The account Identifier can be MerchantId/ShopId/WebStoreId which uniquely identifies the account containing the business KYC details	Max length: 128	Required
ownerAccountId	Body	External object identifier for owning account Id	This value represents the owning account Id at partner's end. Example: If a merchant has multiple webstores with separate business entities under a single account, utilize this field to provide the ownerAccountId for those businessEntities.	Max length: 128	No
ledgerCurrency	Body	JPY	JPY	ENUM	Required
businessInfo	Body	Type:businessInfo	Information about the business legal entity	NA	Required
primaryContactPerson	Body	Type:primaryContactPerson	PrimaryContactPerson of the business	NA	No
beneficiaryOwners	Body	Type:beneficiaryOwners	Information on the company representatives.	NA	Required
integrationInfo	Body	Type:integrationInfo	Provide details regarding integration with AmazonPay systems specially Instant Payment Notification Systems	NA	No
merchantStatus	Body	Type:merchantStatus	Provide updates to Amazon Pay regarding current merchant account status depending on your internal compliance, risk, fraud and other verifications.	NA	Required
stores	Body	Type:Store	Merchant webstore related information which will later be used during buyer checkout to provide store related branding	NA	Required

4.2. Type:UpdateMerchantRequest

Request Parameter	Location	Value	Description	Validation	Mandatory (for Update API)
authorization	Header	Signing requests		NA	Required
x-amz-pay-date	Header	UTC timestamp of when the request is made in ISO 8601 format. This header is required for every request Example: "20190805T051457Z"		NA	Required
x-amz-pay-authToken	Header	AuthenticationToken retured in the response of createMerchantAccount API	This token is needed to make delegated calls on behalf of a merchant.		Required
content-type	Header	Content type of the request body. Must be "application/json". This header is required for every request		NA	Required
businessInfo	Body	Type:businessInfo	Information about the business legal entity	NA	No
primaryContactPerson	Body	Type:primaryContactPerson	PrimaryContactPerson of the business	NA	No
beneficiaryOwners	Body	Type:beneficiaryOwners	Information on company representatives.	NA	No
integrationInfo	Body	Type:integrationInfo	Provide details regarding integration with AmazonPay systems specially Instant Payment Notification Systems	NA	No
merchantStatus	Body	Type:merchantStatus	Provide updates to Amazon Pay regarding current merchant account statusdepending on your internal compliance, risk, fraud and other verifications.	NA	No
stores	Body	Type:Store	Merchant webstore related information which will later be used during buyercheckout to provide store related branding	NA	No

4.3. Type:BusinessInfo

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
businessType	Represents the merchant’s business type: Individual or Corporate Supported values: CORPORATE	String	CORPORATE	Required	No
businessLegalName	The registered legal name of the business	String	Max length: 50	Required	Yes
businessAddress	The address of the merchant legal entity.	Type:Address Info		Required	Yes
businessDisplayName	Display name of the business. It doesn’t need to be same as registered legalname of the business	String	Max length: 50	Required	Yes
businessCategory	BusinessCategory of the merchant	Type:Business Category	ENUM	Required	Yes
email	Valid email address of the merchant which can be used for 2 factor (OTP) verification We strongly recommend to provide OTP verified email id during account creation else we not not be 100% sure if merchant really has possession of that email and would eventually fail the claim process. [Note] : An email used creating an account sandbox can't be used to create account in live environment	String	Max length: 64	Required	Yes
annualSalesVolume	The estimated average annual sales volume of the merchant over previous fiscal year.	Type:Price		No	Yes
countryOfEstablishment	Merchant country of establishment.	String	The country Of Establishment is in ISO 3166-2 format, such as JP (Japan), US (The United States of America), GB (The United Kingdom of Great Britain and Northern Ireland), or DE (Germany).	Required	No
customerSupportInformation	customer support information of the merchant for buyers	Type:CustomerSupportInformation	The country Of Establishment is in ISO 3166-2 format, such as JP (Japan), US (The United States of America), GB (The United Kingdom of Great Britain and Northern Ireland), or DE (Germany).	Required	No

4.4. Type:PrimaryContactPerson

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
personFullName	Person Name: Full Name of point of contact）	String	Max length: 50	No	Yes
residentialAddress	AddressInfo: Address of business representative	Addressinfo		No	Yes

4.5. Type:BeneficiaryOwners

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
personFullName	Person Name: Full Name of business representative	String	Max length: 50	Required	Yes
residentialAddress	AddressInfo: Address of business representative	Addressinfo		No	Yes

4.6. Type:Integration info

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
ipnEndpointUrls	An endpoint where merchant can receive Instant Payment Notifications	List< String >	Max length of List : 10 Max length of URL: 150 We support max of 10 IPN URLs for a merchant and beyond that will throw an error stating InvalidRequest	No	Yes

4.7. Type:MerchantStatus

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
state	Provide current state of transaction eligibility of merchant account depending on your verifications or verification help by your partner organisation (For ex : PSP (PaymentServiceProvider)) ACTIVE INACTIVE	ENUM	ENUM	Required	Yes
statusProvider	partner or associated partner providing merchantStatus Example: psp providing merchantStatus to our csp partner	String	Max length: 50	No (Mandatory in case of Active state)	Yes
reasonCode	Underlying reason why the account became disabled/inactive KYC_RESULT_PENDING, KYC_NOT_STARTED, KYC_NON_COMPLIANT, SCREENING_VIOLATION, FRAUD_VIOLATION	ENUM	ENUM	No	Yes

4.8. Type:Address Info

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
addressLine1	Address Line 1	String	Max length: 180	Required	Yes
addressLine2	Address Line 2	String	Max length: 60	No	Yes
city	city	String	Max length: 50	No	Yes
stateOrRegion	State	String	Max length: 50	No	Yes
postalCode	postal Code	String	Max length: 20	Required	Yes
countryCode	country Code	String	Max length: 2	Required	Yes

4.9. Type:CustomerSupportInformation

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
customerSupportEmail	Merchant's customer support email for buyers seeking assistance.	String	Max length: 64	No	Yes
customerSupportPhoneNumber	Merchant's customer support phoneNumber for buyers seeking assistance.	PhoneNumber		No	Yes

4.10. Type:PhoneNumber

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
countryCode	Country code for phone numberCountry Calling Codes defined by ITU Ref	String	Max length: 4	Required	Yes
number	International telephone number.	String	Max length: 19 Add numbers without any special characters	Required	Yes
extension	Extension for phone number.	String	Max length: 19	No	Yes

4.11. Type:Store

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
externalStoreId	A key ExternalStoreId passed in the request to explicitely create multi-stores. This is intended to be the storeId on CSPs side that support Multi Brandings	String
storeId	storeId and value storeId or lwaClientId is the unique identifier of the store on AmazonPay side Required field in case of update	String
domainUrls	These are domain URLs for each merchant where the Amazon Pay button will be displayed, and a domain URL where buyers will be redirected to after clicking/signing in. The domains may be the same or different, depending on the specific checkout experience of the merchant store. These URLs must be provided for each merchant during registration so that we can validate them from a security standpoint during each transaction.	List < String>	Max list size : 25 Max length of URL: 256 Only URLs with the HTTPS protocol are accepted [URLs with http protocol or URLs without a protocol are not supported]	Required	Yes
privacyPolicyUrl	URL maintaining the privacy policy of the merchant. This will be rendered duringbuyer checkout	String	Max length of URL: 256	No	Yes
storeName	Name of each store for separate branding.Will use businessDisplayName as default if store name not provided	String	Max length: 128	No	Yes
storeStatus	Provide updates to Amazon Pay regarding merchant store status depending onyour internal verifications	Type:StoreStatus		No	Yes

4.12. Type:StoreStatus

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
state	Provide current state of webStore ACTIVE INACTIVE	ENUM	ENUM	Required	Yes
reasonCode	Underlying reason why the store became disabled/inactive STORE_DOWN AUP_VIOLATION	ENUM	ENUM	No	Yes

4.13. Type:Price

Parameter	Description	Type	Validation	Mandatory(Create)	Can Field be updated
amount	amount of the estimated average annual sales volume of the merchant over previous fiscal year	String	Min: 0, Max: 1000000000000	No	Yes
currencyCode	The currency code of the sales volume.	ENUM	The currencyCode is in ISO 4217 format, such as JPY (yen), USD (dollars), EUR (euros), or GBP (pounds).	No	Yes

4.14 Type:Create Merchant Account Response

Response Parameter	Description	Type
uniqueReferenceId	This value is the account identifier used to uniquely represent an account at the level where the partner collects Business KYC details passed in the create call.	String
ownerAccountId	This value represents the owning account Id at partner's end passed in the create call.	String
merchantAccountId	MerchantAccountId or MerchantId is the Amazon ID associated with the merchant	String
authorizationToken	Its the HS256 encoded JWT Token that will be used to make V2 API calls on behalf of the merchant.	String
storeId	storeId or lwaClientId is the unique identifier of the store on AmazonPay side. It contains all the allowed domains where the AmazonPay button needs to be displayed and also includes customized checkout details such as storeName and privacyPolicyUrl.	String

4.15. Type:Merchant Account Claim Request

Request Parameter	Description	Type	Validation	Mandatory
uniqueReferenceId	Identifier used by partners to uniquely identify merchants at their endShould be the same provided during account creation	String	Max length: 128	Yes

4.16. Type:Merchant Account Claim Response

Response Parameter	Description	Type	Comments
status	Provides the current status of account claim INITIATED COMPLETED	ENUM	When merchants complete account cliam process on Amazon Pay, this will be moved to COMPLETED.
uniqueReferenceId	This value is the account identifier used to uniquely represent an account at the level where the partner collects Business KYC details passed in the create call.	String
merchantAccountId	MerchantAccountId is the Amazon ID associated with the merchant	String

Response Header	Description	Type
Location	This value denotes the URL where the merchant must be redirected to by the CSP	String

4.17. Type:ENUM Business Category

Parameter	Description	Type	Validation	Mandatory (Create)	Can Field be updated
BusinessCategory	Partners need to map Business Categories on their side with these Business Categories and provide them in the request. Beauty Jewelry Watches Electronics Media Automotive Photography Gift Travel Store Apparel Digital Goods Education Content & Services Personal Computer Healthcare Software Antiques Books Home Improvement Collectibles Pet Products Business Food and Drink Toy Sports Health Food, Supplement Information Product Beauty Goods (Excluding cosmetics) Dating Service Fortune Telling Please contact the Amazon Pay business team if you have any questions about mapping your categorization. Please also ensure that you convey the mapped content to the Amazon Pay business team before the production release to ensure that the content is correct.	ENUM	Required	Yes	ENUM

5. Sample Request-Response

Note: For all fields (Optional) in the APIs empty strings are not accepted and will throw a error. Recommendation is to not send any string value in payload if it’s empty/null.

5.1. Create Merchant Account

Request:

{
  "uniqueReferenceId": "SPMERCHANT_1234",
  "businessInfo": {
    "email": "rufus@abc.com",
    "businessType": "CORPORATE",
    "businessLegalName": "Kunal Mehta",
    "businessCategory" => "Beauty",
    "businessAddress": {
      "addressLine1": "4-7, Sunny Mansion 203",
      "addressLine2": "Boren Ave",
      "city": "Chiryushi",
      "stateOrRegion": "AICHI",
      "postalCode": "4720021",
      "countryCode": "JP",
      "phoneNumber": {
        "countryCode": "81",
        "number": "2062062061"
      }
    },
    "businessDisplayName": "Rufus's Cafe",
    "annualSalesVolume": {
      "amount": "100000",
      "currencyCode": "JPY"
    },
    "countryOfEstablishment": "JP",
    "customerSupportInformation": {
      "customerSupportEmail": "test.merchant@abc.com",
      "customerSupportPhoneNumber": {
        "countryCode": "1",
        "number": "1234567",
        "extension": "123"
      }
    }
  },
  "beneficiaryOwners": [
    {
      "personFullName": "Rufus Rufus",
      "residentialAddress": {
        "addressLine1": "4-7, Sunny Mansion 203",
        "addressLine2": "Boren Ave",
        "city": "Chiryushi",
        "stateOrRegion": "AICHI",
        "postalCode": "4720021",
        "countryCode": "JP",
        "phoneNumber": {
          "countryCode": "81",
          "number": "2062062061"
        }
      }
    }
  ],
  "primaryContactPerson": {
    "personFullName": "Rufus Rufus"
  },
  "integrationInfo": {
  "ipnEndpointUrls": ["https://cloudfront.net/ipnendpoint"]
  },
  "stores": [
  {
    "domainUrls": [
      "https://www.rufus.com"
    ],
    "storeName": "Rufus's Cafe",
    "privacyPolicyUrl": "https://www.rufus.com/privacy",
    "storeStatus": {
      "state": "ACTIVE",
      "reasonCode": null
    }
  }
  ],
  "merchantStatus": {
      "statusProvider" : "Ayden",
      "state" : "ACTIVE",
      "reasonCode": null
  }
}

Success Response:

{
    "uniqueReferenceId" : "SPMERCHANT_1234",
    "merchantAccountId" : "AMZ789123",
    "storeIdList": [{"storeId" : "amz.storeId.123456"}]
    "authorizationToken" : "amaz.ab1.ajdkd"
}

5.2. Update Merchant Account

Considering merchant changes Business Address and Add Origin and Redirect Urls in Store.

Request:

{
  "businessInfo": {
    "businessAddress": {
      "addressLine1": "4-7, Sunny Mansion 203",
      "addressLine2": "Boren Ave",
      "city": "Chiryushi",
      "stateOrRegion": "AICHI",
      "postalCode": "4720021",
      "countryCode": "JP",
      "phoneNumber": {
        "countryCode": "81",
        "number": "2062062061"
      }
    },
  },
 "stores": [
   {
    "storeId" : "amaz.ob1.123456"
    "domainUrls": [
      "https://www.rufus.com"
    ]
   }
  ]
}

Success Response :

{
    "uniqueReferenceId": "SPMERCHANT_1234",
    "merchantAccountId"  : "AMZ789123",
    "storeIdList": [{"storeId" : "amz.storeId.123456"}]
}

Creating a new Store for MultiStore CSP supporting multi-branding within a Store

{
 "stores": [
   {
    "externalStoreId" : "SP_STORE_ID"
    "domainUrls": [
      "https://www.rufus.com"
    ]
   }
  ]
}

Success Response :

{
    "uniqueReferenceId": "SPMERCHANT_1234",
    "merchantAccountId"  : "AMZ789123",
    "storeIdList": [{
    "storeId" : "amz.storeId.123456",
    "externalStoreId" : "SP_STORE_ID"
    }
    ]
}

5.3. Merchant Account Claim

Merchant Account Claim Request

{
    "uniqueReferenceId": "SPMERCHANT_1234"
}

Merchant Account Claim Success Response
HTTP Status 303 (redirection)

Response Body

{
    "status" : "INITIATED",
    "uniqueReferenceId" : "SPMERCHANT_1234",
    "merchantAccountId" : "AMZ789123"
}

Response Header

{
    "Location": "https://sellercentral-japan.amazon.com/ap/register?openid.return_to..."
}

Idempotency Handling:

Merchant Account Claim Idempotent Response : HTTP Status 200 (Ok)

Response Body

{
    "status" : "COMPLETED",
    "uniqueReferenceId" : "SPMERCHANT_1234",
    "merchantAccountId" : "AMZ789123"
}

Response Header :
No specific response headers related to account claim will be returned

6. Error Codes

Clients should expect an ErrorList with populated data only in case of an InvalidRequest errorReasonCode, where they may encounter errors like InvalidParameterValue and MissingParameterValue. For other reason codes, the ErrorList will be empty. We also recommend to configure atleast 3 retires for 5xx errors. [SDKs are already configured with retries]

HttpStatusCode	errorReasonCode	errorList	Description
400 BAD_REQUEST	InvalidRequest	InvalidParameterValue	You submitted an invalid value for at least one of the parameters of your API call
400 BAD_REQUEST	InvalidRequest	MissingParameterValue	One of the mandatory request parameters is missing in the API call.For details, check the message element in the API response
400 BAD_REQUEST	DuplicateIdempotencyKey		The IdempotencyKey that you have specified in this request was already used in a different request and cannot be reused.
400 BAD_REQUEST	UnrecognizedField		You have passed at least one invalid field in the request body.
400 BAD_REQUEST	InvalidRequestFormat		You submitted a request in invalid JSON format. Validate request body format
429 TOO_MANY_REQUESTS	TooManyRequests		The request is throttled, due to too many requests in a given amount of time.You should retry the request
403 FORBIDDEN	AccessDenied		You do not have the permission to access this resource.
409 CONFLICT	DuplicateRequest		Another request for the same operation is already in progress.Please wait and try again later.
500 INTERNAL_SERVER_ERROR	InternalServerError		There was an unknown error in the service .Retry the request. However, retry does not guarantee a successful response
500 NON_RETRYABLE_INTERNAL_SERVER_ERROR	NonRetryableInternalServerError		There was an unknown error in the serviceYou may retry the request. However, retry does not guarantee a successful response
503 SERVICE_UNAVAILABLE	ServiceUnavailable		The service is currently unable to handle the request, due to a temporary overloading or maintenance.Retry the request

If you have received any error codes other than those mentioned above, please refer to AmazonPay's general error guide for more details

Sample Error Responses:

#1 Sample Error Response In case of 400 Bad Request InvalidReasonCode

{
  "reasonCode": "InvalidRequest",
  "message": "Request parameters are either missing or invalid. Please check errorDetails attribute for more details",
  "errorList": [
   {
    "message": "Parameter value passed for businessDetails.businessType is not valid.",
    "parameter": "businessDetails.businessType",
    "reasonCode": "InvalidParameterValue"
   },
   {
    "message": "Length must be between 1 and 50",
    "parameter": "primaryContactPerson.personFullName",
    "reasonCode": "InvalidParameterValue"
   },
   {
    "message": "businessDetails.businessAddress.postalCode is not provided.",
    "parameter": "businessDetails.businessAddress.postalCode",
    "reasonCode": "MissingParameterValue"
   }
  ]
}

#2 Sample Error Response In case of 403 Forbidden

{
  "reasonCode": "AccessDenied",
  "message": "You do not have the permission to access this resource.",
  "errorList": [ ]
}

#3 Sample Error Response In case of 500 Internal Server Error

{
  "reasonCode": "InternalServerError",
  "message": "There was an unknown error in the service.",
  "errorList": [ ]
}

7. Differences between Environments

Note: Sandbox environment is purely for CSP testing purpose, the differences between the two environments and what is supported is listed below.

Use Case	Sandbox	Live
Email field in create account API	Use only test account emails, as any emails used for sandbox testing cannot be used in live	Use only live/real merchant emails
Email notifications	In Sandbox, no merchant-facing emails are triggered	In Live, merchant-facing emails will be triggered

8. API Throttling Limits

We recommend strictly adhering to the API call limits within the maximum quota outlined below.

API	Sandbox		Live
API	Max quota (TPS)	Restore rate (TPS)	Max quota (TPS)	Restore rate (TPS)
Create Merchant Account	0.5	0.5	0.5	0.5
Update Merchant Account	0.5	0.5	0.5	0.5
Merchant Account Claim	0.5	0.5	0.5	0.5