Alexa用Amazon Pay APIリファレンス



Alexa用Amazon Pay APIリファレンス

このセクションの内容

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

オプション

ユーザーへのメールに記載されるトランザクションの説明です。paymentActionAuthorizedAndCaptureに設定されている場合にのみ表示されます。
最大値: 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"
}