Alexa用Amazon Pay APIリファレンス

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

このセクションの内容

Setup
- BillingAgreementAttributes
- SellerBillingAgreementAttributes
Charge
Buyer ID
購入者住所

Setup

このメソッドは、Billing Agreement IDを返します。ユーザーのBilling Agreementを設定する場合にこの操作を呼び出します。有効なBilling Agreementは、次の場合に使用できます。

任意の時点での購入または支払い
ユーザー情報の取得
支払金額がまだ不明な場合
定期支払いまたは予約購入

リクエストパラメーター	説明および型
@type 必須	定数値： SetupAmazonPayRequest 型：string
@version 必須	定数値： 2 型：string
countryOfEstablishment 必須	Amazon Payアカウントの開設時に販売事業者が法人として登録した国です。使用可能な値: AT BE CH CY DE DK ES FR HU IE IT JP LU NL PT SE UK US 型：string
ledgerCurrency 必須	通貨を指定します。日本の販売事業者は JPY しか使えません。使用可能な値: EUR GBP JPY (日本のみ) USD 型：string
sellerId 必須	出品者IDです（マーチャントIDとも呼ばれます）。注： Eコマースプロバイダー（ソリューションプロバイダー）の場合は、プロバイダーIDではなく、出品者IDを指定します。型：string
checkoutLanguage オプション	販売事業者が取引に使用する言語です。使用可能な値: ja_JP de_DE en_GB en_US es_ES fr_FR it_IT 型：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つ以上のリクエストパラメーターを指定する必要があります。次の文字のみを使用することをお勧めします。小文字（a-z）大文字（A-Z）数字（0-9）ダッシュ（-）アンダースコア（_）型：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 必須	適用可能な支払いアクションを使用します。 Authorize - 注文を確認し、注文金額のオーソリ処理をしますが、この時点ではキャプチャしません。 AuthorizeAndCapture - 注文を確認し、注文金額をオーソリし、キャプチャも行います。型：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 必須	この認可トランザクションの識別子です。この識別子は、すべての認可トランザクションで一意でなければなりません。次の文字のみを使用してください。小文字（a-z）大文字（A-Z）数字（0-9）ダッシュ（-）アンダースコア（_）最大値： 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サイトのトランザクション履歴に表示されます。これは推奨パラメーターですが、その値が一意である必要はありません。次の文字のみを使用することをお勧めします。小文字（a-z）大文字（A-Z）数字（0-9）ダッシュ（-）アンダースコア（_）型：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:

Bearer <your 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:

Bearer <your access token>

Type: string

Sandbox

Header

説明と Type

Authorization

必須

下記フォーマットの現在のaccess token:

Bearer <your 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"
}