Alexa用Amazon Pay APIリファレンス
Alexaスキルで使用されているAmazon Payの支払い機能は、 EUおよび英国では2022年12月31、日本では2023年1月31日、米国では2023年3月31日に無効になります。
詳細については、廃止された機能を参照してください。
このセクションの内容
Setup
このメソッドは、Billing Agreement IDを返します。ユーザーのBilling Agreementを設定する場合にこの操作を呼び出します。有効なBilling Agreementは、次の場合に使用できます。
- 任意の時点での購入または支払い
- ユーザー情報の取得
- 支払金額がまだ不明な場合
- 定期支払いまたは予約購入
リクエストパラメーター |
説明および型 |
@type
必須 |
定数値: SetupAmazonPayRequest 型:string |
@version
必須 |
定数値: 2
型:string |
countryOfEstablishment
必須 |
Amazon Payアカウントの開設時に販売事業者が法人として登録した国です。
使用可能な値:
型:string |
ledgerCurrency
必須 |
通貨を指定します。日本の販売事業者は JPY しか使えません。
使用可能な値:
型:string |
sellerId
必須 |
出品者IDです(マーチャントIDとも呼ばれます)。 注: Eコマースプロバイダー(ソリューションプロバイダー)の場合は、プロバイダーIDではなく、出品者IDを指定します。 型:string |
checkoutLanguage
オプション |
販売事業者が取引に使用する言語です。
使用可能な値:
型:string |
billingAgreementAttributes
オプション |
販売事業者は、BillingAgreementAttributesに指定された属性を設定できます。 詳細については、以下のBillingAgreementAttributesを参照してください。 型: BillingAgreementAttributes |
needAmazonShippingAddress
オプション |
ユーザーの優先配送先住所を応答で受け取るには、このパラメーターをtrueに設定します。 ユーザーの配送先住所が不要の場合は、指定する必要はありません。 型:boolean |
sandboxMode
オプション |
Sandboxテスト環境モードでテストするには、このパラメーターをtrueに設定します。 デフォルト値:false 型:boolean |
sandboxCustomerEmailId
オプション |
このパラメーターは、Sandboxテスト環境で支払契約を作成する場合に使用します。 このパラメーターを使用するには、最初に、セラーセントラルでSandboxテスト環境ユーザーアカウントを作成します。次に、そのアカウントに関連付けられているEメールアドレスを渡します。 型:string |
BillingAgreementAttributes
リクエストパラメーター |
説明および型 |
@type
必須 |
定数値: BillingAgreementAttributes 型:string |
@version
必須 |
定数値: 2
型:string |
platformId
オプション |
Eコマースプラットフォームを開発したソリューションプロバイダーのSellerIdを指定します。
この値は、それを必要とするソリューションプロバイダーのみが使用します。自分でカスタムインテグレーションされた販売事業者は、指定不要です。このリクエストパラメーターには、販売事業者のSellerIdを指定しないでください。 販売事業者の場合は、PlatformIdを入力しないでください。 型:string |
sellerNote
オプション |
購入者へのEメールに表示するBilling Agreementの説明を指定します。
最大値: 1,024文字 型:string |
sellerBillingAgreementAttributes
オプション |
このBilling Agreementオブジェクトで表されるBilling Agreementに関して、詳細情報を指定します。
型: SellerBillingAgreementAttributes |
SellerBillingAgreementAttributes
リクエストパラメーター |
説明および型 |
@type
必須 |
定数値: SellerBillingAgreementAttributes 型:string |
@version
必須 |
定数値: 2
型:string |
sellerBillingAgreementId
オプション |
販売事業者が指定した、このBilling Agreementの識別子です。1つ以上のリクエストパラメーターを指定する必要があります。
次の文字のみを使用することをお勧めします。
型:string |
storeName
オプション |
注文が生成された店舗名です。このパラメーターを指定すると、セラーセントラルの設定>出品用アカウント情報の値を上書きします。この値は、購入者のメールとAmazon
Payウェブサイトのトランザクション履歴に表示されます。
型:string |
customInformation
オプション |
このBilling Agreementに含めたい追加情報です。
1つ以上のリクエストパラメーターを指定する必要があります。 型:string |
ペイロードの例
{
"@type":"SetupAmazonPayRequest",
"@version":"2",
"sellerId": "A00776781C_EXAMPLE_ID",
"countryOfEstablishment":"JP",
"ledgerCurrency":"JPY",
"checkoutLanguage":"ja_JP",
"billingAgreementAttributes":{
"@type":"BillingAgreementAttributes",
"@version":"2",
"sellerNote":"Billing Agreementに関する販売事業者のメモ",
"sellerBillingAgreementAttributes":{
"@type":"SellerBillingAgreementAttributes",
"@version":"2",
"sellerBillingAgreementId":"B03-XXXXXX-XXXXXXX ",
"storeName":"テスト用ストア名",
"customInformation":"テスト用カスタム情報"
}
},
"needAmazonShippingAddress":true,
"sandboxMode":true,
"sandboxCustomerEmailId":"testuseraccount@amazon.com"
}
応答要素
要素名 |
説明 |
billingAgreementDetails | 詳細については、Amazon Pay API リファレンスのBillingAgreementDetails参照してください (米国版、英国版、ドイツ版、日本語版)。 |
応答ペイロードの例
{
"billingAgreementDetails":{
"billingAgreementId":"C03-0000002-0000003",
"creationTimestamp":"2018-03-24T00:31:57.352Z",
"destination":{
"physicalDestination": {
"district": null,
"city": null,
"countryCode": "JP",
"stateOrRegion": "東京都",
"addressLine1": "目黒区下目黒1-8-1",
"postalCode": "153-0064",
"addressLine2": "アルコタワー",
"phone": "1111122222",
"addressLine3": null,
"county": null,
"name": "アマゾン 太郎"
},
"checkoutLanguage":"ja_JP",
"billingAgreementStatus":"OPEN",
"releaseEnvironment":"SANDBOX"
}
}
Charge
この操作を行うと、Alexaが購入金額を確認し、確認カードをユーザーに送信します。この操作を使用できるのは、購入金額がわかっており、かつユーザーが存在し、スキルとリアルタイムで対話しているときです。
リクエストパラメーター |
説明および型 |
@type
必須 |
定数値: ChargeAmazonPayRequest
型:string |
@version
必須 |
定数値: 2
型:string |
billingAgreementId
必須 |
作成されたユーザーのBilling Agreement(テストの場合は、Sandbox用のBillingAgreement IDにすることができます)。
型:string |
paymentAction
必須 |
適用可能な支払いアクションを使用します。
型:string |
sellerId
必須 |
出品者IDです(マーチャントIDとも呼ばれます)。 注: Eコマースプロバイダー(ソリューションプロバイダー)の場合は、プロバイダーIDではなく、出品者IDを指定してください。 型:string |
authorizeAttributes
必須 |
AuthorizeAttributesテーブルに指定されたアトリビュートを設定します。
型:authorizeAttributes 詳細については、Amazon Pay API リファレンスのAuthorizationDetailsを参照してください ( 米国版、 英国版、 ドイツ版、 日本語版)。 |
sellerOrderAttributes
オプション |
Eメールおよびご利用履歴で購入者に表示される要素を指定します。
型:sellerOrderAttributes 詳細については、Amazon Pay API リファレンスのSellerOrderAttributesを参照してください (米国版、 英国版、 ドイツ版、 日本語版)。 |
ペイロードの例
{
"@type":"ChargeAmazonPayRequest",
"@version":"2",
"sellerId":"A00776781C_EXAMPLE_ID",
"billingAgreementId":"C03-XXXXXXX-XXXXXXX",
"paymentAction":"AuthorizeAndCapture",
"authorizeAttributes":{
"@type":"AuthorizeAttributes",
"@version":"2",
"authorizationReferenceId":"fv01gtgpu8cam7p4s0000000",
"authorizationAmount":{
"@type":"Price",
"@version":"2",
"amount":"1000",
"currencyCode":"JPY"
},
"transactionTimeout":0,
"sellerAuthorizationNote":"テスト用販売事業者の認証に関するメモ"
},
"sellerOrderAttributes":{
"@type":"SellerOrderAttributes",
"@version":"2",
"sellerOrderId":"",
"storeName":"TestStoreName",
"customInformation":"テスト用カスタム情報",
"sellerNote":"テスト用の販売事業者のメモ"
}
}
AuthorizeAttributes
ユーザーに許可する金額と、認可操作に役立つ情報を指定します。
リクエストパラメーター |
説明および型 |
@type
必須 |
定数値: AuthorizeAttributes
型:string |
@version
必須 |
定数値: 2
型:string |
authorizationReferenceId
必須 |
この認可トランザクションの識別子です。この識別子は、すべての認可トランザクションで一意でなければなりません。 次の文字のみを使用してください。
最大値: 32文字 型:string |
authorizationAmount
必須 |
オーソリする金額 型:Price |
sellerAuthorizationNote
オプション |
ユーザーへのメールに記載されるトランザクションの説明です。paymentActionがAuthorizedAndCaptureに設定されている場合にのみ表示されます。 最大値: 255文字 型:string |
softDescriptor
オプション |
paymentActionがAuthorizedAndCaptureに設定されている場合に、購入者の請求明細に表示される説明です。 SoftDescriptorは支払処理から ”AMZ*<SoftDescriptor>”の形式で送信されます。 日本ではJCBのみ有効です。(JCBでSoftDescriptorが設定されていない場合、法人名を自動で設定)JCB以外は固定値が表示されます。 * 設定いただくパラメータは、英数字である必要があります。 最大値: 16文字 型:string |
transactionTimeout
オプション |
オーソリ処理を完了するまでの最大分数を割り当てます。時間をオーバーした場合は、自動的に失敗になり、オーソリに対しての売上請求はできません。 Alexaトランザクションのデフォルト値は0です。音声ユーザーのチェックアウト時間を短縮するには、特別な理由がない限りこの値を変更しないことをお勧めします。 型:string |
SellerOrderAttributes
Order Referenceオブジェクトで表される注文に関する、詳細情報を指定します。
リクエストパラメーター |
説明および型 |
@type
必須 |
定数値: AuthorizeAttributes
型:string |
@version
必須 |
定数値: 2
型:string |
sellerOrderId
オプション |
販売事業者が指定するこのOrder ReferenceのIDです。この値は購入者のメールとAmazon Pay Webサイトのトランザクション履歴に表示されます。 これは推奨パラメーターですが、その値が一意である必要はありません。 次の文字のみを使用することをお勧めします。
型:string |
storeName
オプション |
注文が生成された店舗名です。これは、セラーセントラルの設定>出品用アカウント情報の値を上書きします。 この値は購入者のメールとAmazon Pay
Webサイトのトランザクション履歴に表示されます。 型:string |
customInformation
オプション |
このOrder Referenceに含めるその他の情報です。 最大値: 1,024文字 型:string |
sellerNote
オプション |
購入者のメールに表示される注文の説明です。 最大値: 1,024文字 型:string |
Price
リクエストパラメーター |
説明および型 |
@type
必須 |
定数値: Price 型:string |
@version
必須 |
定数値: 2
型:string |
amount
必須 |
金額指定値です。
最小値: 1文字 型:string |
currencyCode
必須 |
ISO 4217形式の通貨コード(日本はJPY)です。
型:string |
応答要素
要素名 |
説明 |
amazonOrderReferenceId | Order Referenceの識別子です。 |
authorizationDetails | 詳細については、Amazon Pay API リファレンスのAuthorizationDetailsを参照してください ( 米国版、 英国版、 ドイツ版、 日本語版)。 |
応答ペイロードの例
{
"authorizationDetails":{
"authorizationAmount":{
"amount":"1000",
"currencyCode":"JPY"
},
"capturedAmount":{
"amount":"1000",
"currencyCode":"JPY"
},
"softDescriptor":"AMZ*Test Seller",
"expirationTimestamp":"2018-05-23T07:10:22.522Z",
"idList":["S03-8245791-0000000-C000000"],
"softDecline":false,
"authorizationStatus":{
"lastUpdateTimestamp":"2018-04-23T07:10:22.522Z",
"reasonCode":"MaxCapturesProcessed",
"state":"Closed"
},
"authorizationFee":{
"amount":"1000",
"currencyCode":"JPY"
},
"captureNow":true,
"sellerAuthorizationNote":"TestSellerAuthorizationNote",
"creationTimestamp":"2018-04-23T07:10:22.522Z",
"amazonAuthorizationId":"S03-XXXXXXX-XXXXXXX-AXXXXXXX",
"authorizationReferenceId":"fv01gtgpu8cam7p4s30000000"
},
"amazonOrderReferenceId":"S03-XXXXXXX-XXXXXXX"
}
Buyer ID
Buyer IDの使い方
ユーザーがスキルを有効にするとき、そのスキルは Amazon PayのBuyer IDを入手するためにユーザーから Amazon Payの権限の同意を得る必要があります。
スキルから送信されるそれぞれのリクエストは、スキルに付与されたカプセル化した権限である API access token (apiAccessToken)が含まれます。Amazon Pay buyer ID を得るためには、このト ークンを取り出し、HTTP リクエストの authorization header にこれを含める必要があります。
apiAccessToken は Context 内の System オブジェクトに追加されています。 リクエストのbody全体を確認するためには、こちらを参照してください。Request Format
{
"version": "1.0",
"session": {},
"context": {
"AudioPlayer": {
"playerActivity": "IDLE"
},
"Display": {},
"System": {
"application": {
"applicationId": "amzn1.ask.skill.1111111-2222-3333-4444-5555555"
},
"user": {
"userId": "amzn1.ask.account.XXXXXXXXXX",
"accessToken": "Atza|AAAAAABBBBBBCCCCCC"
},
"device": {},
"apiEndpoint": "https://api.amazonalexa.com",
"apiAccessToken": "AxThk..."
}
},
"request": {}
}
このサンプルはリクエストハンドラーの apiAccessToken へのアクセス方法を示しています。 このサンプルコードは Alexa Skills Kit SDK for Node.js (v2) を使います。
const thirdPartySkillIntentHandler = {
//...
handle(handlerInput){
var apiAccessToken = handlerInput.requestEnvelope.context.System.apiAccessToken;
// ...
}
};
Amazon Pay buyer ID を取得するためのリクエストを作るときは、このフォーマットのAuthorization ヘッダーに access token を含めてください。
Bearer <ACCESS_TOKEN>
この例に示すように <ACCESS_TOKEN> が、Alexa のリクエストメッセージにある apiAccessToken フィールドです。
Authorization: Bearer AxThk...
API リファレンス
エンドポイント、パス、および認証ヘッダーを指定して HTTP GET リクエストを呼ぶことができ ます。安全にサーバー側で buyer id を取得するために、access token をクライアントからサ ーバーへの送信には HTTPS を使ってください。次に、サーバー側から、その access token を使 用して buyer id のエンドポイントを呼び出します。
Region |
Endpoint |
NA | pay-api.amazon.com |
EU and UK | pay-api.amazon.eu |
JP |
pay-api.amazon.jp |
Path: /live/v1/buyer/id
リクエストヘッダー
Header |
Description and type |
Authorization
Required |
フォーマット化された access token:
型: 文字列 |
サンプルリクエストとレスポンス
リクエストメッセージの例
Host: pay-api.amazon.com
Accept: application/json
Authorization: Bearer AxThk...
GET https://pay-api.amazon.jp/live/v1/buyer/id
レスポンスメッセージの成功例
HTTP/1.1 200 OK
Host: pay-api.amazon.com
Content-Type: application/json
{
"buyerId" : "amznl.account.K2LI23KL2LK2"
}
成功時のレスポンスヘッダー
Header |
Description |
Content-Type | application/json |
成功時のレスポンスパラメーター
Parameter |
Description and type |
buyerId | 事業者ごとにカスタマーを一意に特定できるようにした永続的な ID
型: 文字列 |
購入者住所
購入者住所の使い方
Buyer Address APIはデフォルトの購入者住所を返却します。 このAPIはスキルの中でいつでも呼び出すことができます。
下記に理由により、SetupやChargeの前にこのAPIをCallすることをお勧めします。
- 配達することが可能なアドレスであることを確認するため
- 受注金額に含まれる送料・税金を計算するため
API reference
下記のendpoint・pathに対して、下記authentication headerを含んだHTTP GETリクエストをCallすることができます。セキュアにサーバー側の 購入者住所を取得するために、 クライアントからaccess tokenをサーバー側にHTTPSで送信し、そしてサーバー側から購入者情報のendpointをその access tokenを使用して呼び出します。
地域 |
Endpoint |
NA | pay-api.amazon.com |
EU and UK | pay-api.amazon.eu |
日本 |
pay-api.amazon.jp |
Path
Live - /live/v1/buyer/addresses
Sandbox - /sandbox/v1/buyer/addresses
Request headers
Live
Header |
説明 と Type |
Authorization
必須 |
下記フォーマットの現在のaccess token:
Type: string |
Sandbox
Header |
説明 と Type |
Authorization
必須 |
下記フォーマットの現在のaccess token:
Type: string |
x-amz-pay-sandbox-email-id
必須 |
Sandbox user account向けのEmail address:
Type: string |
Request query parameters
Header |
説明 と Type |
sellerId
必須 |
自分のSeller ID
Type: string |
</table>
requestとresponseのサンプル
requestメッセージのサンプル
Host: pay-api.amazon.com
Accept: application/json
Authorization: Bearer AxThk...
GET https://pay-api.amazon.com/live/v1/buyer/addresses?sellerId=ABC
成功時のresponseメッセージのサンプル
{
"addresses": [
{
"address": {
"addressLine1": "83034 Terry Ave",
"city": "Seattle",
"countryCode": "US",
"name": "Jack Smith",
"phone": "800-000-0000",
"postalCode": "98121",
"stateOrRegion": "WA"
},
"addressType": "DefaultOneClickShippingAddress"
}
]
}
Error コード
Status |
Error code |
説明 |
403 |
Forbidden |
指定されたmerchant accountはこのリクエストでは許可されていません。 |
400 |
InvalidRequest |
requestに必須パラメタが指定されていないか、間違っています。 |
400 |
InvalidToken |
提供されたaccess tokenは期限切れか、取り消されたか、不正か、またはその他の理由で無効です。 |
401 |
InsufficientScope |
提供されたaccess tokenは必要なscopeへのアクセス権を持っていません。 |
500 |
ServerError |
サーバー側でRuntimeエラーが発生しました。 |
400 |
InvalidSandboxCustomerEmail |
提供されたsandboxのemailが無効か、指定されたmerchantのものではありません。 |
上記エラーコードに加えて、より詳細な情報をJSONのpayloadとして受信できます。下記はerror responseのサンプルです。
HTTP/1.1 400 Bad Request
Content-Type: application/json;
{
"errorCode": "invalidToken",
"errorMessage": "The access token provided is expired, revoked, malformed, or invalid for other reasons.",
"requestId": "bef0c2f8-e292-4l96-8c95-8833fbd559df"
}