Se connecter
Se connecter
Merci de votre visite. Cette page est disponible en anglais uniquement.

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

(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 :

  1. 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 .
  2. Integrate with Update Merchant Account API : Update Merchant account API will help to update Merchant Account and store details.
  3. 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

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 :

  1. 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 .
  2. Integrate with Update Merchant Account API : Update Merchant account API will help to update Merchant Account and store details.
  3. 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 :

  1. 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 .
  2. 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.
  3. 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
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
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