ログイン

加盟店のセラーアカウント登録用 API

全体概要

JPリージョンのアカウント管理APIを使用すると、サービスプロバイダー(SP)はAmazon Payにプログラム的に加盟店を登録することができます。APIは、JPの認定したSPによってのみ呼び出すことができます。これらのAPIにアクセスする必要がある場合は、Amazon Payビジネス担当者にお問い合わせください。

サポートされている操作

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

SDKを利用できるプログラミング言語の場合は、 Amazon Pay SDKをダウンロードします。

サポートされているenvironmentの値 :

live
sandbox

1. Amazon Payとのインテグレーション
2. APIの基本情報
3. APIの詳細情報
4. データモデル
5. サンプル　リクエストとレスポンス
6. Error Codes
7. 本番環境とSANDBOX環境の違い・留意点
8. API Throttling Limits

1. Amazon Payとのインテグレーション

ここでは、サービスプロバイダー（SP）のビジネスモデル・事業者のマネージメント方法によって、どのようにAPIを利用すれば良いかの考え方をお伝えします。

1.1. SP側で管理する1つの加盟店アカウントで1つのショップのみを管理する形式で扱っている場合

1つの加盟店のアカウントとして、１つのショップとそれに関連するKYC（例：ビジネスアドレス、法定代表者の詳細、連絡先の詳細など）を持っている場合に、以下の流れでAmazon Payセラーアカウントの登録方法を進めて下さい：

Create Merchant Account API のインテグレーション：Create Merchant account APIは、AmazonPayのセラーアカウントの作成を行うのに利用します。このAPIで、セラーアカウントを開設するのに必要な様々な情報*をAmazon Payに連携します。
Update Merchant Account API のインテグレーション：Update Merchant Account APIは、加盟店のセラーアカウント情報やストア情報を更新・修正するのに利用します。
Merchant Account Claim API のインテグレーション：Merchant Account Claim API は、Create Account API を介して作成された Amazon Pay のセラーアカウントに加盟店がアクセス可能とするために、利用します。

1.2. SP側で管理する1つの加盟店アカウントで複数のショップを管理する形式で扱っている場合

※ 1つの加盟店アカウントの中で、複数のショップとそれに関連するKYCを管理している場合、日本ではこちらの形式をサポートしておりません。その為、この場合でも、1.1にある流れと同様に、それぞれ別のAmazon Payのセラーアカウントを作成するように処理を行って下さい。

2. APIの基本情報

エンドポイント

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

ヘッダー構成とAPI実行時の要否

Name	Location	Description	Type	要否(Create Merchant Account)	要否 (Update Merchant Account)	要否(Merchant Account Claim)
authorization	Header	authorization Header keyは、リクエストの送信者を確認するために使用されます。このヘッダーはすべてのリクエストに必要です。例： "AMZN-PAY-RSASSA-PSS PublicKeyId=AHEGSJCM3L2S637RBGABLAFW, SignedHeaders=accept;content-type;x-amz-pay-date;x-amz-pay-host;x-amz-pay-region, Signature=lDCyYfDN7ni7zfWQz/KvC89qSrZZidsYmZqqORBye/7zHCAR26svJh5DDZnEHkTvcJI/H/NyxzmPyAJpLEGaD7G3NKboIXLxuZYLUY2uS1NLkUMGAkP18NSie0AwuRuD2dngHw6ZIYJWtYBUCbDfAcsH6aCZjjRP+MjKqaIc6Pdwqcch/jXkDKhC0NhlCRQr1v50sI1cFK6rWhzc3qIQ/OGPdb5Oi+NfKWzg7oCxZrbvS6qpSi8u+Wr1qxIf51atWWtkbZH/ZWB6e6Q8V+ssOez/+0apXkOIc+Y2wPMP4SV7xqHDnvqTWOfZpRp/mFo7m/P9ayc730jrwQ65lalj5w=="	String	必須	必須	必須
x-amz-pay-date	Header	リクエストがISO8601形式で行われたときのUTCタイムスタンプ。このヘッダーはすべてのリクエストに必要です。例：「20190805T051457Z」	String	必須	必須	必須
content-type	Header	リクエストボディのコンテンツタイプ。「application /json」である必要があります。このヘッダーはすべてのリクエストに必要です。	String	必須	必須	必須
x-amz-pay-authToken	Header	このトークンは、加盟店に代わってAPIを実施するために必要です。 CreateMerchantAccount APIのレスポンスで取得頂けます。	String	NA	必須	NA

ヘッダーのサンプル

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

3. APIの詳細情報

3.1. Create Merchant Account API

このAPIで、貴社加盟店の情報を提供し、加盟店が利用可能なAmazon Payのセラーアカウントを作成します。Amazon Payは、データバリデーションやデータ入力に基づき成功または詳細なエラーメッセージのいずれかを返却します。

本番エンドポイント

Path: POST /live/v2/merchantAccounts

SANDBOXエンドポイント

Path: POST /sandbox/v2/merchantAccounts

リクエスト:

{
"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
}

レスポンス:

オペレーションが成功した場合は、 HTTP Status 201 (Created) が返却されます。

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

MerchantAccountId と StoreId は、APIを実行したことで生成されたAmazon PayのセラーアカウントのIDとなります。詳細についてはこちらもご覧ください。なお、MerchantAccountIdは、updateやclaim APIsなど、今後のAPI実行にも利用します。※日本では、一つのセラーアカウントに対する複数Storeの作成(複数のショップの管理)はサポートしていない為、StoreIdは1つのみ返却されます。

Idempotency ハンドリング

このAPIでは、uniqueReferenceId が、Idempotency keyとなり、動作します。

その為、同じ uniqueReferenceId を用いて再度当API を実行した場合は、 HTTP Status 200 (Ok) をMerchantReferenceId・ AuthorizationTokenと共に返却します。

留意事項 既に何らかのAmazonアカウントに紐づいているメールアドレスを用いて、加盟店のセラーアカウントを作成することはできません。そのような既に他でご利用済みメールアドレスが設定されている場合は、Amazon Payは400 HttpsStatusCodeを返却します。エラーの詳細は以下のとおりです。

{
  "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"
    },
  ]
}

この場合は、加盟店に既存のAmazon Payのセラーアカウント開設フローをご案内し、セラーアカウントを開設頂いてください。

3.2 Update Merchant Account API

このAPIで、指定されたmerchantAccountIdのアカウント情報を更新することが可能です。ただし、法的なビジネス要件に影響しない項目のみ更新できます。

加盟店のセラーアカウント有効化が完了(Merchant Account Claim APIを実施)するまで、このAPIで情報を更新可能です。 (セラーアカウント有効化後は加盟店がセラーセントラルから情報を更新する必要があります。)

本番エンドポイント

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

SANDBOXエンドポイント

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

リクエスト:

{
"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)　※日本ではこの項目は利用しません
"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
}

レスポンス:

オペレーションが成功した場合は、 HTTP Status 200 (Ok) が返却されます。

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

※日本では、一つのセラーアカウントに対する複数Storeの作成はサポートしていない為、StoreIdは1つのみ返却されます。

3.3. Merchant Account Claim API

CreateMerchantAccount APIでAmazon Payのセラーアカウントを作成した後に、加盟店がセラーアカウントへのアクセスを可能とする為の処理が必要となります。このAPIを実行することで、加盟店がセラーアカウントを利用可能とするためのプロセスを進めることが可能となります。 Account claim は、SPがMerchant Account Claim APIを実行することで“Initiated” stateからスタートします。加盟店がセラーアカウント開設に必要な設定を完了すると“Completed” stateに遷移します。

Note: 後述に詳細がありますが、このAPIはSP側の管理画面で加盟店の認証が完了した後に実行する形でご利用下さい。

3.3.1 加盟店のセラーアカウントを有効化する為のフロー

①セラーアカウントの有効化を進める為のClaim API実行のトリガーは３つあります。

Amazon Payから加盟店にEmailを送付し、加盟店が本文のリンクをクリックする

または
SPから加盟店にEmailを送付し、加盟店が本文のリンクをクリックする

または
SPの管理画面で対象の加盟店に対して通知を表示し、加盟店がクリックする

Note: SPは自身の管理画面でAmazon Payのセラーアカウントの有効化が必要な旨を通知し、管理画面から有効化の作業を進めて頂く必要があります。

加盟店が受け取るEmailには、貴社が管理する加盟店のログインポータル(管理画面など)へのリンクが設定されています。
Ex: https://amazoncsp.com/login.html?action=claimAPayAccount

Note: この遷移先のエンドポイントについては、SP側に決めて頂けます。当機能を利用する際には、貴社からAmazon Payに遷移先の情報を提供する必要があります

Expectation: 以下のことを実現できるように遷移先のエンドポイントをご設定下さい。ここに遷移した加盟店がSPのログインポータルなどアカウント認証されるページにリダイレクトされ、加盟店がSPの加盟店として認証に成功(ログインが成功)させる。その後に、SPがMerchant Account Claim API を実行し、セラーアカウントの有効化処理を開始する。

③・④Merchant Account Claim APIの利用契約に基づき、加盟店はEmailのハイパーリンクをクリックすると、ご設定頂いたSPのログインポータルにリダイレクトされ、加盟店として正しくログインし、認証が完了する必要があります。

⑤加盟店がログインを行った後、貴社のバックエンドで merchantAccountClaim API を実行し、アカウントの有効化プロセスの開始指示を行います

⑥merchantAccountClaim APIのレスポンスとして、Amazon Payは HTTPステータス303 を“Initiated”ステータスと共に返却します。 SPは、加盟店のクリックアクションからトリガーされ、最終的に merchantAccountClaim API を呼び出した所から、同じ 303 レスポンスを Location ヘッダーと共に加盟店が操作しているブラウザ（加盟店がクレームアクションをトリガーしたアプリ/あらゆるユーザーエージェント）に返す必要があります。

⑦⑥の処理により、加盟店のブラウザー/ユーザーエージェントは、Amazon Payが提供する Location にリダイレクトされ、加盟店はセラーアカウントの必要情報を設定することができます。

Note: このアクションはそのまま実行される必要があります。SP はAmazon Payが Location ヘッダの一部として返す url に対して変更は加えないで下さい。

⑧Amazon Payは、アカウント作成時(Create Merchant Acount API)に提供されたEmail情報を元に加盟店に対して二段階認証を行います。

⑨加盟店が認証を完了すると、セラーアカウントの有効化プロセスは完了となり、セラーセントラルのページに遷移します。これよりに後に、もし merchantAccountClaim API を実行された場合、加盟店のセラーアカウントの有効化プロセスは完了済みとなる為、Amazon PayはHTTPステータス200を“Completed”ステータスと共に返却します。

Note: セラーアカウントの有効化及びセラーセントラル上での必要情報の入力は90日以内に加盟店によって行われる必要があります。

Note: もし加盟店側で当プロセスを実施する途中で何らかのアクシデント(ネットワーク切断、誤ってタブを閉じてしまう等)が発生した場合、加盟店のセラーアカウント有効化プロセスが完了となるまで、SP側でmerchantAccountClaim API の実行を含めて加盟店のリトライが可能となるように対応をしてください。

3.3.2 Merchant Account Claim API

このAPIで、加盟店のセラーアカウントの有効化の開始指示を行います。Amazon Payは、データバリデーションやデータ入力に基づき成功または詳細なエラーメッセージのいずれかを返却します。

本番エンドポイント

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

SANDBOXエンドポイント

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

リクエスト:

{
    "uniqueReferenceId": String  //mandatory
}

レスポンス:

オペレーションが成功した場合は、 HTTP Status 303 (redirection) を Location header と共に返却します。

レスポンスボディ:

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

レスポンスヘッダー：

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

3.3.3 Idempotency ハンドリング

このAPIでは、uniqueReferenceId が、Idempotency keyとなり、動作します。

レスポンス

加盟店がセラーアカウントの有効化プロセスを未完了の場合

HTTP Status 303 (redirection) を以下のheader, bodyと共に返却します。加盟店のセラーアカウントの有効化が未完了の為、ステータスは“INITIATED”で返却されます。

レスポンスボディ:

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

レスポンスヘッダー

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

加盟店がセラーアカウントの有効化プロセスを完了している場合

加盟店のセラーアカウントの有効化の開始指示を実施した時点で、既に該当のmerchantAccountIdのセラーアカウントの有効化が完了していた場合、HTTP Status 200 (Ok) を返却します。加盟店のセラーアカウントの有効化が完了している為、ステータスは“COMPLETED”で返却されます。

レスポンスボディ

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

Note : 加盟店のセラーアカウント有効化プロセスが完了すると、Amazon Pay は "status" : "COMPLETED" で 200(OK) レスポンスを返します。このレスポンスを受け取った場合は、「セラーアカウントの有効化の処理は既に完了しています」といったメッセージを加盟店に表示するようにして下さい。

レスポンスヘッダー: この場合は、レスポンスにLocationは設定されません。

4. データモデル

入力いただける値として、UTF-8の英語と日本語（ひらがな、カタカナ、漢字）、全角と半角をサポートします

Legend	Value
要否 (for Create API)	生成時に必須の項目は'必須'、それ以外は任意と記載
更新可否	更新時に更新が可能な項目は'可能'、不可能の場合は'不可'と記載

4.1. Type:CreateMerchantRequest

リクエストパラメータ	ロケーション	値	説明	バリデーション	要否 (for Create API)
authorization	Header	署名リクエスト		NA	必須
x-amz-pay-date	Header	要求がISO8601形式で行われたときのUTCタイムスタンプ。このヘッダーはすべてのリクエストに必要です。例：「20190805T051457Z」		NA	必須
content-type	Header	リクエストボディのコンテンツタイプ。「application /json」である必要があります。このヘッダーはすべてのリクエストに必要です。		NA	必須
uniqueReferenceId (Idempotency key)	Body	各SPにおいて、各加盟店の識別子となる値を指定してください	この値は、SPがビジネスKYCの詳細を収集する単位でアカウントを一意に表す為のアカウント識別子となります。例えば、ビジネスKYCの詳細を含むアカウントを一意に識別するMerchantId/ShopId/WebStoreIdなどをご設定頂くことが可能です。	Max length: 128	必須
ownerAccountId	Body	SP側でオーナーアカウントを管理する為のIDを指定下さい	この値は、SP側のオーナーアカウントIDとなります。例えば、加盟店が複数のウェブストアを1つのSPが管理するアカウントで運営している場合に、この項目に値を設定することで、それらのビジネスのオーナーとなるアカウントIDを連携してください。	Max length: 128	任意
ledgerCurrency	Body	JPY	JPY	ENUM	必須
businessInfo	Body	Type:businessInfo	事業主体に関する情報	NA	必須
primaryContactPerson	Body	Type:primaryContactPerson	企業の主な連絡先	NA	任意
beneficiaryOwners	Body	Type:beneficiaryOwners	企業の代表者の情報	NA	必須
integrationInfo	Body	Type:integrationInfo	AmazonPayシステムのIPNの設定に関する詳細情報	NA	任意
merchantStatus	Body	Type:merchantStatus	社内のコンプライアンス、リスク、不正、その他の検証に応じて、現在の加盟店アカウントのステータスに関する情報	NA	必須
stores	Body	Type:Store	加盟店のウェブストアに関連する情報。これらの情報は決済フローなどでウェブストアのブランド情報として利用されます	NA	必須

4.2. Type:UpdateMerchantRequest

リクエストパラメータ	ロケーション	値	説明	バリデーション	要否 (for Update API)
authorization	Header	署名リクエスト		NA	必須
x-amz-pay-date	Header	要求がISO8601形式で行われたときのUTCタイムスタンプ。このヘッダーはすべてのリクエストに必要です。例：「20190805T051457Z」		NA	必須
x-amz-pay-authToken	Header	createMerchantAccount APIで取得したAuthenticationToken	このトークンは、加盟店に代わってAPIを実施するために必要です。		必須
content-type	Header	リクエストボディのコンテンツタイプ。「application /json」である必要があります。このヘッダーはすべてのリクエストに必要です。		NA	必須
businessInfo	Body	Type:businessInfo	事業主体に関する情報	NA	任意
primaryContactPerson	Body	Type:primaryContactPerson	企業の主な連絡先	NA	任意
beneficiaryOwners	Body	Type:beneficiaryOwners	企業の代表者の情報	NA	任意
integrationInfo	Body	Type:integrationInfo	AmazonPayシステムのIPNの設定に関する詳細情報	NA	任意
merchantStatus	Body	Type:merchantStatus	社内のコンプライアンス、リスク、不正、その他の検証に応じて、現在の加盟店アカウントのステータスに関する情報	NA	任意
stores	Body	Type:Store	加盟店のウェブストアに関連する情報。これらの情報は決済フローなどでウェブストアのブランド情報として利用されます	NA	任意

4.3. Type:BusinessInfo

リクエストパラメーター	説明	タイプ	バリデーション	要否(Create)	更新可否
businessType	加盟店のビジネスタイプを表します：個人または法人(Individual or Corporate) このAPIでサポートしている値: CORPORATE	String	"CORPORATE" を指定	必須	不可
businessLegalName	登記上の商号	String	Max length: 50	必須	可能
businessAddress	法人所在地	Type:Address Info		必須	可能
businessDisplayName	ビジネスでの表示名 ※登記上の商号とおなじである必要はありません	String	Max length: 50	必須	可能
businessCategory	加盟店のビジネスカテゴリ ※ビジネスカテゴリとして設定できる値は、4.17 Business Categoryを参照下さい	Type:Business Category	ENUM	必須	可能
email	2段階認証（OTP）に使用できる加盟店の有効なEメールアドレス。 ※SP側でアカウント作成した際にOTP認証済みのEメールアドレスを提供することを強くお勧めします。もし有効でないEメールアドレスが連携されると、加盟店と連絡が取れず、最終的にAmazon Payのセラーアカウントの有効化に失敗する可能性があります。 ※注意：SANDBOX環境で使用されたメールアドレスは、本番環境で利用できません。本番環境に投入予定のメールアドレスをSANDBOX環境で利用しないで下さい。	String	Max length: 64	必須	可能
annualSalesVolume	加盟店の前年度年間平均売上高（見込み）	Type:Price		任意	可能
countryOfEstablishment	加盟店の設立国	String	”JP”を指定(TISO 3166-2 形式)	必須	不可
customerSupportInformation	加盟店の購入者サポートの問い合わせ先に用いられる情報	Type:Customer Support Information		任意	可能

4.4. Type:PrimaryContactPerson

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
personFullName	担当者のお名前（フルネーム）	String	Max length: 50	任意	可能
residentialAddress	担当者住所	Addressinfo		任意	可能

4.5. Type:BeneficiaryOwners

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
personFullName	ビジネス代表者のお名前（フルネーム）	String	Max length: 50	必須	可能
residentialAddress	ビジネス代表者住所	Addressinfo		任意	可能

4.6. Type:Integration info

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
ipnEndpointUrls	インスタント支払い通知(IPN)を受信する為のエンドポイント	List< String >	Max length of List : 10 Max length of URL: 150 最大で10個までのエンドポイントを設定頂けます。最大値を超えた場合は、InvalidRequestエラーを返却します。	任意	可能

4.7. Type:MerchantStatus

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
state	加盟店アカウントに関するステータス(有効または停止) ※加盟店アカウントの審査・管理を行っている機関(例えば、決済代行サービスプロバイダー(PSP))が保持しているステータスを連携して下さい ACTIVE INACTIVE	ENUM	ENUM	必須	可能
statusProvider	stateの提供元となるサービスプロバイダー名称例えば、貴社に加盟店の状況を連携している決済代行サービスプロバイダー(PSP)名	String	Max length: 50	任意 (Active stateを設定した場合は必須)	可能
reasonCode	アカウントが停止・使用不可となった理由 KYC_RESULT_PENDING, KYC_NOT_STARTED, KYC_NON_COMPLIANT, SCREENING_VIOLATION, FRAUD_VIOLATION	ENUM	ENUM	任意	可能

4.8. Type:Address Info

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
addressLine1	町域・番地	String	Max length: 180	必須	可能
addressLine2	建物名または会社名	String	Max length: 60	任意	可能
city	市区町村	String	Max length: 50	任意	可能
stateOrRegion	都道府県	String	Max length: 50	任意	可能
postalCode	郵便番号	String	Max length: 20	必須	可能
countryCode	国コード	String	Max length: 2	必須	可能

4.9. Type:CustomerSupportInformation

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
customerSupportEmail	購入者サポートの為の問い合わせ先となる加盟店のEmailアドレス	String	Max length: 64	任意	可能
customerSupportPhoneNumber	購入者サポートの為の問い合わせ先となる加盟店の電話番号	PhoneNumber		任意	可能

4.10. Type:PhoneNumber

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
countryCode	電話番号の国番号	String	Max length: 4 ITUで定められた国番号の値を設定して下さい	必須	可能
number	国際電話番号	String	Max length: 19 ハイフンなど数字以外の文字は入力頂けません	必須	可能
extension	内線番号	String	Max length: 19	任意	可能

4.11. Type:Store

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
externalStoreId	複数のショップを管理するために複数ストアを作成する場合にSPからリクエストで渡されるユニークキーId ※日本では、一つのセラーアカウントで複数のストアの設定はサポートしていないため、こちらの項目は設定しないで下さい。	String		任意(複数ストアを設定する場合は必須) ※日本では複数ストアの設定は行えません。	不可
storeId	Amazon Payが発行するstoreId。CreateMerchantAccount APIのレスポンスでSPに連携される。 [この項目はUpdateMerchantAccount APIを実行する際に設定が必要です]	String		N/A	不可
domainUrls	この項目は、各加盟店でAmazon Payボタンが表示されるページのドメインURLと、ボタンクリック/サインイン後に購入者がリダイレクトされる先のページのドメインURLになります。(ECサイトのUXによって、それぞれのドメインが同じ・異なる場合があります) これらのURLは、アカウント登録時に各加盟店に提供されており、Amazon Payにも連携頂く必要があります。Amazon Payはこれらの情報を各取引の際にセキュリティの観点の検証に利用します。	List < String>	Max list size : 25 Max length of URL: 256 HTTPS プロトコルのURLのみ設定頂けます (httpプロトコルやプロトコルを持たないURL設定できません)	必須	可能
privacyPolicyUrl	加盟店のプライバシーポリシーの記載を行っているURL。設定されたURLは購入者が決済する際に表示されます。	String	Max length of URL: 256	任意	可能
storeName	ストア名ストア名が提供されない場合、デフォルトとしてbusinessDisplayNameが使用されます。	String	Max length: 128	任意	可能
storeStatus	ウェブストアのステータスに関する項目SP側での検証結果に応じて、Amazon Payに加盟店のステータスに関する最新情報を設定します	Type:StoreStatus		任意	可能

4.12. Type:StoreStatus

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
state	ウェブストアの現在のステータス ACTIVE INACTIVE	ENUM	ENUM	必須	可能
reasonCode	ウェブストアが停止・使用不可となっている理由 STORE_DOWN AUP_VIOLATION	ENUM	ENUM	任意	可能

4.13. Type:Price

リクエストパラメーター	説明	タイプ	バリデーション	要否 (Create)	更新可否
amount	金額値	String	最小: 0,最大: 1000000000000	任意	可能
currencyCode	amountの通貨コード	'JPY'を指定(ISO 4217形式)	ENUM	任意	可能

4.14 Type:Create Merchant Account Response

レスポンスパラメーター	説明	タイプ
uniqueReferenceId	この値は、create APIで渡されたuniqueReferenceIdです。加盟店を一意に表すために使用されるユニークな識別子となります。 ※ビジネスKYCの詳細情報をパートナーが収集・管理しているレベルで一意で設定下さい。	String
ownerAccountId	この値は、create APIで渡されたownerAccountIdです。	String
merchantAccountId	Amazon Payのセラーアカウントに紐づけられたMerchantIdです	String
authorizationToken	これは、加盟店に代わってAmazon PayのAPIを実施するために必要なTokenIdです。	String
storeId	storeId またはlwaClientIdはAmazon PayのStore単位での一意の識別子です。StoreId単位で、Amazon Payボタンを描画するページのドメインや決済時に利用する情報(ストア名やプライバシーポリシーURLなど)が設定できます。	String

4.15. Type:Merchant Account Claim Request

リクエストパラメーター	説明	タイプ	バリデーション	要否
uniqueReferenceId	この値は、加盟店を一意に表すために使用されるユニークな識別子となります。 ※必ず、CreateMerchant APIで設定したIdと同じIdを設定するようにして下さい	String	Max length: 128	必須

4.16. Type:Merchant Account Claim Response

レスポンスパラメーター	説明	タイプ	備考
status	セラーアカウントの有効化の現在のステータス INITIATED COMPLETED	ENUM	加盟店がセラーアカウントの有効化を完了させるとこのステータスは COMPLETEDになります。
uniqueReferenceId	この値は、Merchant Account APIで渡されたuniqueReferenceIdです。加盟店を一意に表すために使用されるユニークな識別子となります	String
merchantAccountId	Amazon Payのセラーアカウントに紐づけられたMerchantIdです	String

レスポンスパラメーター	説明	タイプ
Location	SPが加盟店をリダイレクトさせる先のURLです	String

4.17. Type:Business Category

リクエストパラメーター	説明	タイプ	バリデーション	要否(Create)	更新可否
BusinessCategory	Amazon Payを利用開始する際に、事業者が選択するビジネスカテゴリ。貴社で保持している加盟店のビジネスカテゴリを以下のビジネスカテゴリにマッピングをして、Amazon Payに連携して下さい。 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 ※カテゴリ分類のマッピングについて、不明点があればAmazon Payビジネスチームにお問い合わせ下さい。また、本番リリース前にマッピングした内容をAmazon Payビジネスチームに連携し、内容に問題がないことを確認するようにして下さい。	ENUM	ENUM	必須	可能

5. サンプル　リクエストとレスポンス

5.1. Create Merchant Account

Note: 全てのOptional項目は空文字を受け付けず、エラーを返却します。ペイロードの文字列の値が空文字/nullとなる場合は該当の項目を送信しないこと推奨します。

リクエスト:

{
  "uniqueReferenceId": "SPMERCHANT_1234",
  "businessInfo": {
    "email": "rufus@abc.com",
    "businessType": "CORPORATE",
    "businessLegalName": "密林コーヒー",
    "businessCategory" => "Beauty",
    "businessAddress": {
      "addressLine1": "扇町４丁目５－１",
      "addressLine2": "フルフィルメントセンタービル",
      "city": "小田原市",
      "stateOrRegion": "神奈川県",
      "postalCode": "250-0001",
      "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": "あまぞん　花子",
      "residentialAddress": {
        "addressLine1": "鶴見区生麦２丁目２－２６",
        "addressLine2": "鶴見マンション",
        "city": "横浜市",
        "stateOrRegion": "神奈川県",
        "postalCode": "230-0052",
        "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
  }
}

成功レスポンス:

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

Idempotency ハンドリング:

このAPIでは、uniqueReferenceId が、Idempotency keyとなり、動作します。

その為、同じ uniqueReferenceId を用いて再度当API を実行した場合は、 HTTP Status 200 (Ok) をMerchantReferenceId・ AuthorizationTokenと共に返却します。

5.2. Update Merchant Account

加盟店のビジネスアドレスが変更となり、Storeに新たなドメインを追加する場合のサンプルリクエスト。

リクエスト:

{
  "businessInfo": {
    "businessAddress": {
      "addressLine1": "下目黒１－８－１",
      "addressLine2": "アルコタワー",
      "city": "目黒区",
      "stateOrRegion": "東京都",
      "postalCode": "153-0064",
      "countryCode": "JP",
      "phoneNumber": {
        "countryCode": "81",
        "number": "2062062061"
      }
    },
  },
 "stores": [
   {
    "storeId" : "amaz.ob1.123456"
    "domainUrls": [
      "https://www.rufus.com"
    ]
   }
  ]
}

成功レスポンス:

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

5.3. Merchant Account Claim

Merchant Account Claim Request

リクエスト:

{
"uniqueReferenceId": "SPMERCHANT_1234"
}

成功レスポンス:

レスポンスボディ

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

レスポンスヘッダー

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

Idempotency ハンドリングのケース:

レスポンスボディ

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

レスポンスヘッダー返却されません。

6. Error Codes

本APIのエラーレスポンスには、errorReasonCodeが'InvalidRequest'の場合のみ、ErrorListに'InvalidParameterValue'や'MissingParameterValue'などの追加のエラー情報が入ります。それ以外の場合は、ErrorListは空になります。

また、5xxエラーに対しては、少なくとも3回リトライを実行頂くことをお勧めします。 (Amazon Payが提供するSDKでは3回リトライが行われる設定となっています。)

HttpStatusCode	errorReasonCode	errorList	Description
400 BAD_REQUEST	InvalidRequest	InvalidParameterValue	API呼び出しのヘッダーパラメータの少なくとも1つに無効な値を送信しました詳細については、APIレスポンスのメッセージ内容を確認してください
400 BAD_REQUEST	InvalidRequest	MissingParameterValue	API呼び出しでヘッダーパラメータの1つが欠落しています詳細については、APIレスポンスのメッセージ内容を確認してください
400 BAD_REQUEST	InvalidRequest		送信したJSONフォーマットが不正です。リクエストボディのフォーマットを検証してください
429 TOO_MANY_REQUESTS	TooManyRequests		特定の時間内にリクエストが多すぎるため、リクエストが制限されましたリクエストを再試行する必要があります
403 FORBIDDEN	AccessDenied		このリクエストを実行する権限がありません
409 CONFLICT	DuplicateRequest		同じ内容のリクエストが処理中です。しばらく待って、リクエストを再試行してください
500 INTERNAL_SERVER_ERROR	InternalServerError		不明なエラーが発生しましたリクエストを再試行してください。ただし、再試行しても正常なレスポンスが保証されるわけではありません
500 NON_RETRYABLE_INTERNAL_SERVER_ERROR	NonRetryableInternalServerError		サービスで不明なエラーが発生しましたリクエストを再試行できます。ただし、再試行しても応答が確実に得られるとは限りません
503 SERVICE_UNAVAILABLE	ServiceUnavailable		一時的な過負荷またはメンテナンスのため、現在リクエストを処理できませんリクエストを再試行してください

上記以外のエラーコードが表示された場合は、AmazonPayの一般的なエラーガイドを参照してください。

サンプルエラーレスポンス :

#1 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 403 Forbiddenのサンプル

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

#3 500 Internal Server Errorのサンプル

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

7. 本番環境とSANDBOX環境の違い・留意点

SANDBOX環境はテスト用の環境です。両環境の違い・留意点は以下のとおりです。

項番	項目	SANDBOX	本番環境
1	Create Merchant Account APIのEメールアドレス	SANDBOX環境と本番環境をあわせて、メールアドレス重複チェックが行われます。その為、SANDBOXで使用されたメールアドレスは、本番で利用できません。本番環境に投入予定のメールアドレスを利用しないで下さい。	SANDBOX環境と本番環境をあわせて、メールアドレス重複チェックが行われます。
2	加盟店に送付されるメール	SANDBOX環境ではCreate Merchant Account APIで登録された加盟店のメールアドレスに対して、Eメールは送付されません。	Create Merchant Account APIで登録された加盟店のメールアドレスに対して、Eメールが送付されます。

8. API Throttling Limits

APIの実行は、以下に示す最大クォータの範囲内で行って下さい。

API	SANDBOX		本番環境
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

加盟店のセラーアカウント登録用 API

全体概要

サポートされている操作

1. Amazon Payとのインテグレーション

1.1. SP側で管理する1つの加盟店アカウントで1つのショップのみを管理する形式で扱っている場合

1.2. SP側で管理する1つの加盟店アカウントで複数のショップを管理する形式で扱っている場合

2. APIの基本情報

ヘッダーのサンプル

3. APIの詳細情報

3.1. Create Merchant Account API

リクエスト:

レスポンス:

Idempotency ハンドリング

3.2 Update Merchant Account API

リクエスト:

レスポンス:

3.3. Merchant Account Claim API

3.3.1 加盟店のセラーアカウントを有効化する為のフロー

3.3.2 Merchant Account Claim API

3.3.3 Idempotency ハンドリング

4. データモデル

4.1. Type:CreateMerchantRequest

4.2. Type:UpdateMerchantRequest

4.3. Type:BusinessInfo

4.4. Type:PrimaryContactPerson

4.5. Type:BeneficiaryOwners

4.6. Type:Integration info

4.7. Type:MerchantStatus

4.8. Type:Address Info

4.9. Type:CustomerSupportInformation

4.10. Type:PhoneNumber

4.11. Type:Store

4.12. Type:StoreStatus

4.13. Type:Price

4.14 Type:Create Merchant Account Response

4.15. Type:Merchant Account Claim Request

4.16. Type:Merchant Account Claim Response

4.17. Type:Business Category

5. サンプル リクエストとレスポンス

5.1. Create Merchant Account

5.2. Update Merchant Account

5.3. Merchant Account Claim

6. Error Codes

7. 本番環境とSANDBOX環境の違い ・留意点

8. API Throttling Limits

5. サンプル　リクエストとレスポンス

7. 本番環境とSANDBOX環境の違い・留意点