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アカウントの開設時に販売事業者が法人として登録した国です。

型:string

ledgerCurrency

必須

通貨を指定します。

型: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つ以上のリクエストパラメーターを指定する必要があります。

次の文字のみを使用することをお勧めします。

  • 小文字(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"
}