スキルとAmazon Payのインテグレーション



スキルとAmazon Payのインテグレーション

このセクションの内容

始める前に

ユーザーデータを保護するため、スキルは、以下の要件を満たしている必要があります。スキルが以下の要件のいずれかに違反しているとAmazonが判断した場合、スキル認定の申請を却下または保留にし、開発者アカウントに紐づいたメールアドレスに通知します。

  • 開発者コンソールの公開ページで、スキルに適用するプライバシーポリシーへのリンクを含める必要があります。
  • 子ども向けスキルは認められません。詳細については、子供向けAlexaスキルを参照してください。
  • ユーザー連絡先情報は、ユーザーにより許可された契約サービスの履行に必要な場合にのみ使用することができます。
  • デバイスアドレス情報を使用して、バックグラウンドでユーザーのアカウントにリンクすることはできません。つまり、Alexaユーザーを同じ所在地情報を持つアカウントプールのユーザーに関連付けることは認められません。

Amazon Pay販売事業者として登録する

AlexaスキルをAmazon Payに接続してトランザクションを処理するには、Amazon Payアカウントをセットアップし、このアカウントを使用してAlexaスキルを設定できるようにします。

  1. Amazon Payウェブサイト(https://pay.amazon.com/jp/merchant)から、Amazon Payアカウントに登録(または、既存のアカウントをプロビジョニング)します。
  2. 認証情報を収集します。
    セラーセントラルのAmazon PayおよびLogin with Amazonインテグレーション設定ページ(インテグレーションメニューからMWS Access Keyをクリック)で、次の認証情報を確認できます。
    • マーチャントID(出品者ID)
    • MWS Access Key IDおよびMWSシークレットアクセスキー
  3. Amazon Pay Sandboxアカウントをテスト用にセットアップします。
    テスト環境では、実際のお金を使わずに、Amazon Payを使用したユーザーエクスペリエンスをシミュレートできます。詳細については、Amazon PayインテグレーションガイドのAmazon Pay SANDBOXのテストアカウント設定を参照してください。

Amazon開発者になる

Alexaスキルを作成するには、Amazon開発者として登録する必要があります。

AWSアカウントをaws.amazon.comで作成します。AWSアカウントはLambda関数で使用され、音声対話フローやAmazon Payのインテグレーションを行います。

スキルを作成する

Amazon Payアカウント、Amazon開発者アカウント、およびAWSアカウントをセットアップすると、Amazon Payを使用する権限を持つスキルを作成できるようになります。

  1. Alexaスキルをビルドします。不明点がある場合は、次のAlexaドキュメントを参照してください。

    注:問い合わせ方法をユーザーに伝えるインテントをスキルに含めて、購入のキャンセルや返金リクエストを行えるようにする必要があります。この情報には、スキルの説明、およびユーザーに送信するカードに含めることをお勧めします。

  2. Alexa開発者コンソールでスキルを登録します。
  3. アクセス権限ページで、Amazon Payオプションを選択します。

Personalize your customers' experience with buyer ID

Amazon Pay Buyer ID は、事業者ごとにカスタマーを一意に特定できるようにした永続的な ID です。 これを利用することで、カスタマー個人ごとに最適化した購入体験を演出することができるようになります。 例えば EC サイトなどで、スマートホンでスタートさせた購入手続きを、あとから Alexa を使って完了させるようなこともできます。

Amazon Pay は、3rd パーティースキルに、カスタマーの購入プロセスにおける早い段階でAmazon Pay Buyer ID を確認し、 そのIDが既に登録されたものと一致するかどうかを確認することを推奨しています。 これは Alexa アカウントリンクの制約を回避することにもつながります。

詳細は, How to use buyer IDを参照してください。

Important: Amazon Pay buyer ID使用するスキルを開発する場合は, 以下のリンクの使用する為の条件をご覧ください。 Amazon Pay buyer ID requirements

セラーセントラルでスキルをAmazon Payアカウントに接続する

  1. セラーセントラルにサインインします。
  2. Sandboxビューが表示されていることを確認します。
  3. インテグレーションをクリックしてから、Alexaをクリックします。
  4. Alexaスキル向けAmazon Pay​ページで、Alexaスキルに接続​をクリックします。
  5. ダイアログボックスでAlexaスキルIDを入力します。次に、スキルでは、Amazon Payのサービス利用規定で禁止されている商材を販売しないこと、及びAlexa上で使用されるデジタルの商品やサービスは販売しないことに合意するチェックボックスを選択して、接続をクリックします。
  6. 本番環境ビューで手順3~5を繰り返し、本番環境で使用するスキルをAmazon Payアカウントに接続します。

支払いワークフローをセットアップする

Amazon Payの請求シナリオには、次の2種類があります。

  • 今すぐ請求: ユーザーがスキルと対話中に請求します。
  • 後で請求: スキルからバックエンドサーバーにトークンを渡して、後でユーザーに請求します。これは、Amazon Pay APIで処理する必要があります。

AlexaアプリでAmazon Pay対応スキルを有効にしたときに作成されるユーザーのconsentTokenは異なります。ユーザーが許可していない場合、consentTokenは有効になりません。

Alexaスキル向けAmazon Payでは、Billing Agreementの概念を使用して、ユーザーに請求を行います。Billing Agreementは、購入者の優先支払方法、優先配送先住所、および定期的な支払いの許可(該当する場合)で構成されるオブジェクトです。

Amazon Pay APIは、返金やユーザー情報の取得のためにバックエンドサーバーで使用されます。ユーザーに請求および返金する際の運用方法によっては、バックエンドサーバーを構築する必要があります。

支払いワークフロー1: 今すぐ請求

これは、もっともシンプルな支払いシナリオです。Billing Agreementを作成して、ユーザーに請求できます。

次の場合に最適です。

  • 購入金額が事前にわかっている。
  • ユーザーがまだスキルを使用している。
  • 定期的な支払いやサブスクリプションのユースケースを構築する予定がない。

このワークフローでは、バックエンドサーバーのセットアップは任意です。

購入、支払いDecline、返金のシナリオに対する今すぐ請求の一般的な手順

今すぐ請求の一般的な手順

ユーザーに対してAmazon Payを初めて呼び出すときは、Connections.SendRequestを設定するためのSetupAmazonPayペイロードを作成する必要があります。Connections.SendRequestをAlexaに送信すると、SetupAmazonPayペイロードを含むSetupアクションが指示されます。

Setupの結果として、Connections.Responseリクエストがスキルに返されます。


this.handler.response = {
  "version": "1.0",
  "response": {
      "directives": [
          {
              "type": "Connections.SendRequest",
              "name": "Setup",
              "payload": {
                          "SetupAmazonPay" : {
                              "consentToken": this.event.context.System.apiAccessToken,
                              "sellerId": "A33OD7583R_SellerID",
                              "countryOfEstablishment": "JP",
                              "ledgerCurrency": "JPY",
                              "checkoutLanguage": "ja_JP",
                              "billingAgreementAttributes": {
                                   "platformId": "",
                                   "sellerNote": "Billing Agreementに関する販売事業者のメモ",
                                   "sellerBillingAgreementAttributes": {
                                        "sellerBillingAgreementId": "B03-XXXXXX-XXXXXXX",
                                        "storeName": "テスト用ストア名",
                                        "customInformation": "テスト用顧客情報"
                                   }
                              },
                              "needAmazonShippingAddress": false
                          }
               },
              "token": "correlationToken"
          }
      ],
      "shouldEndSession": true
  }
};

this.emit(":responseReady");

Setupが完了したら、Connections.ResponseリクエストをgetBillingAgreementDetailsbillingAgreementIdに使用できます。billingAgreementIdを保存しておくと、次に同じユーザーがスキルを使用したときにSetup手順を省略できます。

注: ユーザーがスキルでAmazon Payのアクセス権限を有効にしていない場合は、有効にするようにリクエストできます。次のコードサンプルは、Amazon Payのアクセス権限を有効にするようにユーザーに指示する方法を示しています。


function handleErrors( actionResponseStatusCode, this ) {
	var actionResponseErrorCode 	= this.event.request.payload.errorCode;
	var actionResponsePayloadMessage 	= this.event.request.payload.errorMessage;

	switch ( actionResponseErrorCode) {
		case 'ACCESS_NOT_REQUESTED':
			this.emit( ':tellWithPermissionCard', ''Amazon Payの権限が有効になっておりません。Alexaアプリにカードを送りましたのでAlexaアプリからAmazon Payを有効にしてください。', [ 'payments:autopay_consent' ] );
			break;
		default:
			this.emit( ':tell', 'エラーが発生しました。エラーステータスコード ' + actionResponseStatusCode + '。エラーペイロードメッセージ ' + actionResponsePayloadMessage + '。' );
	}
}

次は、ユーザーに請求を行います。ChargeAmazonPayペイロードにbillingAgreementIDを設定して、ChargeアクションとChargeペイロードを含むConnections.SendRequestを送信します。


var handlers = {
    "Connections.Response" : function () {
    	const actionName = this.event.request.name;
        const actionResponsePayload = this.event.request.payload;
        const actionResponseStatusCode = this.event.request.status.code;
        if (actionName == "Setup") {
            if (actionResponseStatusCode != 200) {
                //エラー処理を実装します
        	}
        	const consentToken = this.event.context.System.apiAccessToken;

        	//ペイロードからbillingAgreementDetailsとbillingAgreementIDを取得します

        	const billingAgreementDetails = actionResponsePayload["billingAgreementDetails"];
        	const billingAgreementID = billingAgreementDetails['billingAgreementId'];
        	var chargePayload = buildChargePayload(consentToken, billingAgreementID);
        	var chargeResponse = {
                "shouldEndSession": true,
                "directives": [
                    {
                        "type" : "Connections.SendRequest",
                        "name" :  "Charge",
                        "payload" : chargePayload,
                        "token": "correlationToken"
                    }
                ]
            };
            var response = {
                version : '1.0',
                sessionAttributes: {},
                response: chargeResponse
            };
            this.handler.response = response;
            this.emit(':responseReady');
        } else if (actionName == "Charge") {
            if (actionResponseStatusCode != 200) {
        		//エラー処理を実装します
        	}   //TODO: オーソリのエラーハンドリングをする
        	this.emit(':tell', "決済が完了しました。ご注文ありがとうございました。");
        }
    }
};

var buildChargePayload = function(consentToken, billingAgreementId) {
    var payload = {
       "ChargeAmazonPay" : {
    	    "consentToken": consentToken,
        	    "sellerId": "A33OD7583RGD6B",
        	    "billingAgreementId": billingAgreementId,
        	    "paymentAction": "AuthorizeAndCapture",
        	    "authorizeAttributes": {
        	    	"authorizationReferenceId": "sdfwr3423fsxfsrq43",
        	    	"authorizationAmount": {
        	    		"amount" : "100",
        	    		"currencyCode": "JPY"
        	    	},
        	    	"transactionTimeout": 0,
        	    	"sellerAuthorizationNote" : "テスト用販売事業者の認証に関するメモ",
        	    	"softDescriptor": "AMZ*"
        	    },
    	    "sellerOrderAttributes": {
    		"sellerOrderId" : "ABC-000-123234",
    		"storeName": "テスト用ストア名",
    		"customInformation": "テスト用顧客情報",
    		"sellerNote": "テスト用の販売事業者のメモ"
    	    }
     }
   };
   return payload;

Chargeの成功応答を受け取ったら、請求フローが完了、ユーザーへの確認が行われます。

  • 金額を確認し、Amazon Payを使用して請求が行われることを知らせる会話がユーザーに再生されます。
  • Alexaアプリに、請求の詳細をすべて含んだ確認カードが表示されます。
  • 請求金額を確認する電子メールがユーザーに送信されます。

エラー処理をセットアップして、請求のフローを完成させます。

支払いワークフロー2: 後で請求

後で請求支払いオプションは、ユーザーのセットアップと、後で行われるユーザーへの請求を分離するので、今すぐ請求よりも柔軟性のある支払方法です。このオプションでは、定期的な支払いが設定されたAmazon Payのインテグレーションが必須です。

このワークフローは次のような場合に最適です。

  • ユーザーがまだ買い物を続けているか、チェックアウトする商品の選択後にまだスキルを使用している場合(アップセルの機会や販促タイアップに適しています)。
  • 都度払いでの利用や、サービス後に使用される場合など、支払金額がまだ不明な場合。
  • サブスクリプションや繰り返し発生する定期的な支払いに対して請求を行う場合。
  • ユーザーを認識し、アカウントの履歴に基づいてパーソナライズまたは調整したエクスペリエンスを提供する場合。

後で請求の一般的な手順

後で請求の一般的な手順

ユーザーに対してAmazon Payを初めて呼び出すときは、Connections.SendRequestを設定するためのSetupAmazonPayペイロードを作成する必要があります。Connections.SendRequestをAlexaに送信すると、SetupAmazonPayペイロードを含むSetupアクションが指示されます。


this.handler.response = {
  "version": "1.0",
  "response": {
      "directives": [
          {
              "type": "Connections.SendRequest",
              "name": "Setup",
              "payload": {
                          "SetupAmazonPay" : {
                              "consentToken": this.event.context.System.apiAccessToken,
                              "sellerId": "A33OD7583R_SellerID",
                              "countryOfEstablishment": "JP",
                              "ledgerCurrency": "JPY",
                              "checkoutLanguage": "ja_JP",
                              "billingAgreementAttributes": {
                                   "platformId": "",
                                   "sellerNote": "Billing Agreementに関する販売事業者のメモ",
                                   "sellerBillingAgreementAttributes": {
                                        "sellerBillingAgreementId": "B03-XXXXXX-XXXXXXX",
                                        "storeName": "テスト用ストア名",
                                        "customInformation": "テスト用顧客情報"
                                   }
                              },
                              "needAmazonShippingAddress": false
                          }
               },
              "token": "correlationToken"
          }
      ],
      "shouldEndSession": true
  }
};

this.emit(":responseReady");

注: SellerBillingAgreementAttributesは、ユーザーへのメール通知に表示されます。Amazon Pay Auto Pay機能インテグレーションガイドの提供可能な購入者メールコンテンツを参照してください。

Setupの結果として、Connections.Responseリクエストがスキルに返されます。

Setupが完了したら、Connections.ResponseリクエストをgetBillingAgreementDetailsbillingAgreementIdに使用できます。billingAgreementIdを保存しておくと、同じユーザーが次にスキルを使用したときや定期的な支払いのシナリオで次にユーザーに請求するときにSetupのプロセスを省略できます。

注: ユーザーがスキルでAmazon Payのアクセス権限を有効にしていない場合は、有効にするようにリクエストできます。次のコードサンプルは、Amazon Payのアクセス権限を有効にするようにユーザーに指示する方法を示しています。


function handleErrors( actionResponseStatusCode, this ) {
	var errorCode 	= this.event.request.payload.errorCode;
	var errorMessage 	= this.event.request.payload.errorMessage;

	switch (errorCode) {
		case 'ACCESS_NOT_REQUESTED':
    case 'ACCESS_DENIED':
      this.emit( ':tellWithPermissionCard', ''Amazon Payの権限が有効になっておりません。Alexaアプリにカードを送りましたのでAlexaアプリからAmazon Payを有効にしてください。', [ 'payments:autopay_consent' ] );
      break;
	default:
      // for debug
			// this.emit( ':tell', 'エラーが発生しました。エラーステータスコード ' + actionResponseStatusCode + '。エラーペイロードメッセージ ' + actionResponsePayloadMessage + '。' );
      this.emit( ':tell', '申し訳ございません、エラーが発生しました。しばらくたってからもう一度お試しください。' );
	}
}

Setupで取得した有効なbillingAgreementIdをバックエンドサーバーに送信して、ユーザーアカウントとともに保存したり、メールアドレスなどの追加情報の取得に使用したりできます。詳細については、Amazon Pay API リファレンスのGetBillingAgreementDetailsを参照してください。

以下のコードサンプルでは、billingAgreementIdを受け取り、取得する方法を示しています。


var handlers = {
    "Connections.Response" : function () {
      const actionName = this.event.request.name;
        const actionResponsePayload = this.event.request.payload;
        const actionResponseStatusCode = this.event.request.status.code;
        if (actionName == "Setup") {
            if (actionResponseStatusCode != 200) {
                //エラー処理を実装します
                return handleErrors(actionResponseStatusCode, this);
          }

          //ペイロードからbillingAgreementDetailsとbillingAgreementIDを抽出します
          const billingAgreementDetails = actionResponsePayload["billingAgreementDetails"];
          const billingAgreementID = billingAgreementDetails['billingAgreementId'];
    }
};

注: このワークフローでは、バックエンドサーバーのセットアップは必須です。詳細については、バックエンドサーバーをセットアップするを参照してください。

ユーザーへの請求を行うには、Amazon Pay Auto Pay機能インテグレーションガイドに示されているインテグレーション手順に従ってください。

バックエンドサーバーをセットアップする

後で請求のシナリオでは、スキルとやり取りし、AmazonマーケットプレイスWebサービス(Amazon MWS)サーバーに対するリクエストを実行してサーバーから応答を受信するために、バックエンドサーバーが必要です。

重要
以下を順守することを強くお勧めします。
  • クライアントアプリに機密情報を記録または保存しない。
  • 認証情報(MWSアクセスキーとMWSシークレットアクセスキー)を配布しない。
  • クライアントアプリケーションからAmazon MWS APIを直接呼び出さない。クライアントアプリにMWSアクセスキーとMWSシークレットアクセスキー、出品者IDを保存することは危険なため、MWSの呼び出しはサーバーから行う必要があります。Lambdaなどの安全なAWSコンポーネントからのMWSの呼び出しは、ベストプラクティスのガイドラインに適合しています。
  • 傍受やman-in-the-middle攻撃を防止するために、アプリとサーバー間の通信はすべてTLS/SSLを介して行う。

Amazon Payでは、バックエンドサーバーのセットアップに役立つ複数言語のSDKが用意されています。サービスとAmazonのサーバー間のインテグレーションをもっとも簡単に実現できるため、これらを確認して使用することを強くお勧めします。詳細については、Amazon PayドキュメントにあるSDKとサンプルへのリンクを参照してください。

エラー処理をセットアップして、後で請求のフローを完成させます。

エラー処理をセットアップする

選択した支払いフローのシナリオに関係なく、Alexaスキル用のエラー処理をセットアップする必要があります。

エラータイプの詳細と説明については、支払いのDeclineと処理エラーを参照してください。

インテグレーション後にテストする

Sandboxテスト環境でのテストでは、実際の注文をせずにスキルとAmazon Payのインテグレーションを検証できます。

Setupを呼び出すときは、Sandboxユーザーの電子メールIDを渡し、ペイロードの作成時にSandboxテスト環境モードをtrueに設定する必要があります。 Setupから、SandboxのBillingAgreementIdが返されます。Decline発生時のフローをテストするには、特定の支払いシナリオをシミュレートするためのSandboxシミュレーション文字列を使用できます。たとえば、 InvalidPaymentMethodAmazonRejectedTransactionTimedOutなどがあります。

今すぐ請求シナリオのテスト: SandboxのBillingAgreementIdを使用してChargeを呼び出します。これにより、テスト環境モードがシミュレートされます。

後で請求シナリオ: Sandboxシミュレーション文字列の詳細については、Amazon PayインテグレーションガイドのSandboxシミュレーションを参照してください。

Alexaスキルのテストの詳細については、スキルのテストセクションを参照してください。

スキルの認定を取得して、本番環境で使用する

お疲れさまでした。 スキルの作成、Amazon Payへのリンク、およびテスト環境モードでのテストが完了し、スキルが正常に機能することを確認しました。本番環境モードに切り替えた後、最後の手順として起動します。

  1. 開発者ポータルに戻ってサインインします。
  2. 公開タブをクリックし、スキルの認定手順に従います。