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



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

このセクションの内容

始める前に

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

  • スキルに適用するプライバシーポリシーへのリンクを開発者コンソールの公開ページに含める必要があります。
  • 子ども向けスキルは認められません。詳細については、子供向けAlexaスキルを参照してください。
  • スキルで提供する機能やサービスをサポートするために必要な場合には、ユーザーの連絡先情報を受け取る権限をリクエストする必要があります。リクエストする個人情報は、ユーザーの許可、プライバシー通知、適用される法令に従ってのみ利用するようにしてください。
  • 連絡先情報(名前、メールアドレス、電話番号)を使用して、バックグラウンドでユーザーのアカウントにリンクすることはできません。つまり、Alexaユーザーを同じ連絡先情報を持つアカウントプールのユーザーに関連付けることは認められません。
  • Alexaの購入を可能にするスキルの要件を満たしている必要があります。

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

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

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

Amazon開発者として登録する

Amazon Pay販売事業者として登録後、Alexaスキルを作成するには、Amazon開発者ポータル でAmazon開発者として登録する必要があります。音声対話フローを制御するためにサーバレス環境のAWS Lambda関数を使用する場合や、他のAWSサービスを使用する予定がある場合は、AWSアカウントを今すぐ AWS で構築を開始するで作成します。AWSアカウントでLambda関数を作成して、音声対話フローやAmazon Payのインテグレーションを行います。

スキルを作成する

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

  1. Alexaスキルをビルドします。不明点がある場合は、次のAlexaドキュメントを参照してください。
  2. Alexa開発者コンソールでスキルを登録します。詳細については、開発者コンソールアカウントの作成を参照してください。
  3. アクセス権限ページで、Amazon Payオプションを有効にしてください。

AlexaとAmazon Payを使ったお買い物体験のサンプルをご覧になる場合には、デモ店舗用カスタムスキルをチェックアウトしてください。

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

  1. セラーセントラルにサインインします。
  2. 環境変更のドロップダウンから、Amazon Pay (テスト環境)を選択します。
    環境変更のドロップダウンは、画面上部にあるメニューの中央にドロップダウンとして表示されます。

    画面が最小化されている場合、環境変更のドロップダウンは次のボタンに置き換えられます。

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

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

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

  • 今すぐ請求: ユーザーがスキルと対話中に請求します。
  • 後で請求: スキルからバックエンドサーバーにトークンを渡して、後でユーザーに請求します。これは、Amazon Pay APIへのリクエストを処理するようにセットアップできます。

Alexaスキル向けAmazon Payでは、Billing Agreementを使用して、ユーザーに請求を行います。 Billing Agreementは、ユーザーの優先支払方法、優先配送先住所、および自動支払いの許可で構成されるオブジェクトです。

ウェブで利用可能なAmazon Pay APIは、返金やユーザー情報の取得のためにバックエンドサーバーで使用することが可能です。 ユーザーへの請求および返金の運用方法によっては、バックエンドサーバーを構築が必要になる場合があります。

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

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

次の場合に最適です。

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

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

ユーザーの配送先アドレスを使って、配送できるかどうかのチェックや送料と受注総額に含まれる税金の計算などをする場合には、Buyer Address APIを、SetupやChargeを呼ぶ前に使うことができます。

「今すぐ請求」の一般的な手順(購入、支払いエラー(Decline)、返金のシナリオ)

「今すぐ請求」の一般的な手順
図を大きく表示

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

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

こちらのサンプルコードは、Alexa Skills Kit SDK for Node.js (v2)を使用しています。

const SetUpHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "IntentRequest" &&
            handlerInput.requestEnvelope.request.intent.name === "SetupPaymentIntent";
    },
    handle(handlerInput) {
        let directiveObject = {
            "type": "Connections.SendRequest",
            "name": "Setup",
            "payload": {
                "@type": "SetupAmazonPayRequest",
                "@version": "2",
                "sellerId": "AEMGQXXXKD154",
                "countryOfEstablishment": "JP",
                "ledgerCurrency": "JPY",
                "checkoutLanguage": "ja-JP",
                "billingAgreementAttributes": {
                    "@type": "BillingAgreementAttributes ",
                    "@version": "2",
                    "billingAgreementType": "CustomerInitiatedTransaction",//EU and UK merchants only
                    "sellerNote": "Billing Agreement Seller Note",
                    "sellerBillingAgreementAttributes": {
                        "@type": "SellerBillingAgreementAttributes ",
                        "@version": "2",
                        "sellerBillingAgreementId": "BA12345",
                        "storeName": "Test store name",
                        "customInformation": "Test custom information"
                    }
                },
                "needAmazonShippingAddress": false
            },
            "token": "correlationToken"
        };
    return handlerInput.responseBuilder
        .addDirective(directiveObject)
        .withShouldEndSession(true)
        .getResponse();
    }
};

こちらのサンプルコードは、Amazon Pay Alexa Utils for Node.jsを使用しています。

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const SetUpHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "IntentRequest" &&
            handlerInput.requestEnvelope.request.intent.name === "SetupPaymentIntent";
    },
    handle(handlerInput) {
        let payloadBuilder = AmazonPay.setupPayload('2')
          .withSellerId('AEMGQXXXKD154')
          .withCountryOfEstablishment('JP')
          .withLedgerCurrency('JPY')
          .withCheckoutLanguage('ja-JP')
          .withBillingAgreementType('CustomerInitiatedTransaction') //EU and UK merchants only
          .withSellerNote('Billing Agreement Seller Note')
          .withSellerBillingAgreementId('BA12345')
          .withStoreName('Test store name')
          .withCustomInformation('Test custom information')
          .shippingNeeded(false);
        let directiveObject = AmazonPay.setupDirective(payloadBuilder, 'correlationToken').build();

        return handlerInput.responseBuilder
            .addDirective(directiveObject)
            .withShouldEndSession(true)
            .getResponse();
    }
};

countryOfEstablishmentledgerCurrencycheckoutLanguageに正しい値が指定され、Amazon Payアカウントおよびユーザーが使用しているスキルの言語に一致していることを確認してください。

Setupが完了したら、Connections.ResponseリクエストをgetBillingAgreementDetailsbillingAgreementIdに使用できます。

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

こちらのサンプルコードは、Alexa Skills Kit SDK for Node.js (v2)を使用しています。

const ConnectionsSetupResponseHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "Connections.Response"
        && handlerInput.requestEnvelope.request.name === "Setup";
    },
    handle(handlerInput) {
        const actionResponsePayload = handlerInput.requestEnvelope.request.payload;
        const actionResponseStatusCode = handlerInput.requestEnvelope.request.status.code;
        if (actionResponseStatusCode != 200) {
            // Perform error handling
        }
        // Extract billingAgreementDetails and billingAgreementID from payload optionally to store it for future use
        const billingAgreementDetails = actionResponsePayload.billingAgreementDetails;
        const billingAgreementID = billingAgreementDetails.billingAgreementId;
        let directiveObject = {
            "type": "Connections.SendRequest",
            "name": "Charge",
            "payload": {
                "@type": "ChargeAmazonPayRequest",
                "@version": "2",
                "sellerId": "AEMGQXXXKD154",
                "billingAgreementId": billingAgreementID,
                "paymentAction": "AuthorizeAndCapture",
                "authorizeAttributes": {
                    "@type": "AuthorizeAttributes",
                    "@version": "2",
                    "authorizationReferenceId": "sdfwr3423fsxfsrq43",
                    "authorizationAmount": {
                        "@type": "Price",
                        "@version": "2",
                        "amount": "1.01",
                        "currencyCode": "JPY"
                    },
                    "transactionTimeout": 0,
                    "sellerAuthorizationNote": "Test Seller Authorization Note"
                },
                "sellerOrderAttributes": {
                    "@type": "SellerOrderAttributes",
                    "@version": "2",
                    "sellerOrderId": "ABC-000-123234",
                    "storeName": "Test Store Name",
                    "customInformation": "Test custom information",
                    "sellerNote": "Test seller note"
                }
        },
        "token": "correlationToken"
    };
        return handlerInput.responseBuilder
            .addDirective(directiveObject)
            .withShouldEndSession(true)
            .getResponse();
    }
};
const ConnectionsChargeResponseHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "Connections.Response"
        && handlerInput.requestEnvelope.request.name === "Charge";
    },
    handle(handlerInput) {
        const actionResponseStatusCode = handlerInput.requestEnvelope.request.status.code;
        if (actionResponseStatusCode != 200) {
            // Perform error handling
        }
        return handlerInput.responseBuilder
            .speak("Test skill will process transaction.")
            .getResponse();
    }
};

こちらのサンプルコードは、Amazon Pay Alexa Utils for Node.jsを使用しています。

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const ConnectionsSetupResponseHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "Connections.Response"
        && handlerInput.requestEnvelope.request.name === "Setup";
    },
    handle(handlerInput) {
        const actionResponsePayload = handlerInput.requestEnvelope.request.payload;
        const actionResponseStatusCode = handlerInput.requestEnvelope.request.status.code;
        if (actionResponseStatusCode != 200) {
            // Perform error handling
        }
        // Extract billingAgreementDetails and billingAgreementID from payload optionally to store it for future use
        const billingAgreementDetails = actionResponsePayload.billingAgreementDetails;
        const billingAgreementID = billingAgreementDetails.billingAgreementId;

        let payloadBuilder = AmazonPay.chargePayload('2')
          .withSellerId('AEMGQXXXKD154')
          .withBillingAgreementId(billingAgreementID)
          .withPaymentAction('AuthorizeAndCapture')
          .withAuthorizationReferenceId('sdfwr3423fsxfsrq43')
          .withAmount('1.01')
          .withCurrency('JPY')
          .withSellerAuthorizationNote('Test Seller Authorization Note')
          .withSellerOrderId('ABC-000-123234')
          .withStoreName('Test Store Name')
          .withCustomInformation('Test custom information')
          .withSellerNote('Test seller note');
        
        let directiveObject = AmazonPay.chargeDirective(payloadBuilder, 'correlationToken').build();
        
        return handlerInput.responseBuilder
            .addDirective(directiveObject)
            .withShouldEndSession(true)
            .getResponse();
    }
};
const ConnectionsChargeResponseHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "Connections.Response"
        && handlerInput.requestEnvelope.request.name === "Charge";
    },
    handle(handlerInput) {
        const actionResponseStatusCode = handlerInput.requestEnvelope.request.status.code;
        if (actionResponseStatusCode != 200) {
            // Perform error handling
        }
        return handlerInput.responseBuilder
            .speak("Test skill will process transaction.")
            .getResponse();
    }
};

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

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

「今すぐ請求」のフローを完成させるために、エラーとDeclineの処理をセットアップを参照ください。

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

「後で請求」支払いオプションは、ユーザーのセットアップと、後で行われるユーザーへの請求を分離するので、「今すぐ請求」よりも柔軟性のある支払方法です。このオプションでは、Amazon PayのAuto Payに関するインテグレーションが必要となります。詳細については、お住まいの地域に該当するガイドを参照してください。   日本語版   米国版   英国版   EU版

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

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

ユーザーの配送先アドレスを使って、配送できるかどうかのチェックや送料と受注総額に含まれる税金の計算などをする場合には、Buyer Address APIを、SetupChargeを呼ぶ前に使うことができます。

「後で請求」の一般的な手順

「後で請求」の一般的な手順
図を大きく表示

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

こちらのサンプルコードは、Alexa Skills Kit SDK for Node.js (v2)を使用しています。

const SetUpHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "IntentRequest" &&
            handlerInput.requestEnvelope.request.intent.name === "SetupPaymentIntent";
    },
    handle(handlerInput) {
        let directiveObject = {
            "type": "Connections.SendRequest",
            "name": "Setup",
            "payload": {
                "@type": "SetupAmazonPayRequest",
                "@version": "2",
                "sellerId": "AEMGQXXXKD154",
                "countryOfEstablishment": "JP",
                "ledgerCurrency": "JPY",
                "checkoutLanguage": "ja-JP",
                "billingAgreementAttributes": {
                    "@type": "BillingAgreementAttributes",
                    "@version": "2",
                    "billingAgreementType": "MerchantInitiatedTransaction",//EU and UK merchants only
                    "subscriptionAmount": {
                       "@type": "Price",
                       "@version": "2",
                       "amount": "19.99",
                       "currencyCode": "JPY"
                    },
                    "sellerNote": "Billing Agreement Seller Note",
                    "sellerBillingAgreementAttributes": {
                        "@type": "SellerBillingAgreementAttributes",
                        "@version": "2",
                        "sellerBillingAgreementId": "BA12345",
                        "storeName": "Test store name",
                        "customInformation": "Test custom information"
                    }
               },
               "needAmazonShippingAddress": false
          },
          "token": "correlationToken"
      };

        return handlerInput.responseBuilder
            .addDirective(directiveObject)
            .withShouldEndSession(true)
            .getResponse();
    }
};

こちらのサンプルコードは、Amazon Pay Alexa Utils for Node.jsを使用しています。

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const SetUpHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "IntentRequest" &&
            handlerInput.requestEnvelope.request.intent.name === "SetupPaymentIntent";
    },
    handle(handlerInput) {
        let payloadBuilder = AmazonPay.setupPayload('2')
          .withSellerId('AEMGQXXXKD154')
          .withCountryOfEstablishment('JP')
          .withLedgerCurrency('JPY')
          .withCheckoutLanguage('ja-JP')
          .withBillingAgreementType('MerchantInitiatedTransaction') //EU and UK merchants only
          .withSubscriptionAmount('19.99')
          .withSubscriptionCurrency('JPY')
          .withSellerNote('Billing Agreement Seller Note')
          .withSellerBillingAgreementId('BA12345')
          .withStoreName('Test store name')
          .withCustomInformation('Test custom information')
          .shippingNeeded(false);
        let directiveObject = AmazonPay.setupDirective(payloadBuilder, 'correlationToken').build();

        return handlerInput.responseBuilder
            .addDirective(directiveObject)
            .withShouldEndSession(true)
            .getResponse();
    }
};

countryOfEstablishmentledgerCurrencycheckoutLanguageに正しい値が指定され、 Amazon Payアカウントおよびユーザーが使用しているスキルの言語に一致していることを確認してください。

SellerBillingAgreementAttributesの値は、ユーザーへのメール通知に表示されます。お住まいの地域に該当する版のAmazon Pay Auto Pay機能インテグレーションガイドで、提供可能な購入者メールコンテンツを参照してください   (日本語版   米国版   英国版   EU版 )。

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

Setupが完了したら、Connections.ResponseリクエストをgetBillingAgreementDetailsbillingAgreementIdに使用できます。 定期購入や 「後で請求」のワークフローを行うには、billingAgreementIdを保存し(例えば、バックエンドサーバーなど)、必要なタイミングでAmazon Pay APIsを使用します。

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

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


const ConnectionsSetupResponseHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === "Connections.Response" &&
            handlerInput.requestEnvelope.request.name === "Setup";
    },
    handle(handlerInput) {
        const actionResponsePayload = handlerInput.requestEnvelope.request.payload;
        const actionResponseStatusCode = handlerInput.requestEnvelope.request.status.code;
        if (actionResponseStatusCode != 200) {
            // エラー処理を実装
        }

        // ペイロードからbillingAgreementDetailsとbillingAgreementIDを取得
        const billingAgreementDetails = actionResponsePayload.billingAgreementDetails;
        const billingAgreementID = billingAgreementDetails.billingAgreementId;

        return handlerInput.responseBuilder
            .speak("テストスキルの支払い設定が完了しました。")
            .getResponse();
    }
};

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

ユーザーへの請求を行うには、お住まいの地域に該当する版のAmazon Pay Auto Pay機能インテグレーションガイドに記載されているインテグレーション手順に従ってください。 (日本語版   米国版   英国版   EU版

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

「後で請求」のシナリオでは、スキルとやり取りし、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とサンプルへのリンクを参照してください。   米国版   英国版   EU版   日本語版

これらのSDKが要件に合わず、独自のバックエンドサーバーをセットアップする必要がある場合には、Using the Amazon MWS client librariesに詳細がありますので、ご参照ください。

スキルで取得したbillingAgreementIdは、SDKやAPIを直接使って請求を発行するのに使うことができます。

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

Buyer IDを使ってお客様のエクスペリエンスをカスタマイズする

Amazon Pay Buyer ID は、事業者ごとにお客様を一意に特定できるようにした永続的な ID です。

Amazon Pay は、3rd パーティースキルに、お客様の購入プロセスにおける早い段階でAmazon Pay Buyer ID を取得して、 そのIDが既に登録されたお客様と一致するかどうかを確認することを推奨しています。

これを利用することで、お客様ごとに最適化した購入体験を演出することができるようになります。 例えば EC サイトなどで、スマートホンでスタートさせた購入手続きを、後から Alexa を使って完了させるようなこともできます。

これは Alexa アカウントリンクの制約を回避することにもつながります。

詳細は、 Buyer IDの使い方を参照してください。

重要: Amazon Pay Buyer ID使用するスキルを開発する場合は、Amazon Pay Buyer ID 要件をご確認ください。

Amazon Payのアクセス権限と音声ショッピングの設定を確認する

スキル内でAmazon Payを使用するには、2つの権限が必要になります。(①Amazon Payのアクセス権限(スキル毎)、②音声ショッピングの設定(全体で1つの設定))
音声ショッピングの設定はAlexaアプリで有効にする必要がありますが、Amazon Payのアクセス権限は、声で権限を有効にすることが出来ます。 Amazon Pay Setup APIを呼び出すと、Alexaが双方の権限チェックを代わりに実施し、適切な発話をユーザに返します。 音声ショッピングの設定が有効になっていない場合は、Alexaアプリにカードが送信され、Amazon Payのアクセス権限が有効になっていない場合は、声で権限を有効にするようAlexaが促します。

  • Alexaに権限チェックを委ねることを推奨しますが、手動で権限チェックする場合は、スキルでAmazon Payのアクセス権限を有効にするようにユーザーに依頼するをご参照ください。
  • 権限チェックは、スキルを開始直後のタイミングでも、支払いを行う前のタイミングでも、どちらでも実施することができます。
  • Amazon Buyer IDの取得や購入者住所をSetup前に取得する場合は、手動で権限チェックし、権限がない場合Setup APIを呼び出すことで、権限がない場合の処理をAlexaに任せることが出来ます。

下記が、Alexaがそれぞれの場合においてどう挙動するかの概要となります。

音声ショッピング Amazon Pay権限 結果
ON GRANTED 全ての必要な権限が有効になっている場合。

Alexa は要求された通り、BillingAgreement を作成します。
お客様 は、明示的に設定している場合のみ、声のPINコードを要求されます。その後、スキルに処理が渡されます。
スキル は、BillingAgreement が正常に生成されたら、BillingAgreementDetails を受け取ります(請求処理を完了させることが可能な billingAgreementId を含む)。
ON DENIED スキルにAmazon Payの権限が付与されている必要があります。
Alexa は、お客様にAmazon Payの権限を有効にするよう話しかけ、Amazon Pay関連データを事業者様に共有する同意を得ます。お客様の応答次第で、Alexaは BillingAgreement を作成するか、Alexaアプリにカードを送付します(お客様が判断するための詳細情報を送付)
お客様 は、このスキルにAmazon Payの権限を有効にしていいか、話しかけられます。
スキル は、お客様が権限を有効にしエラーが発生しなかった場合のみ、BillingAgreementDetails を受け取ります(請求処理を完了させることが可能な billingAgreementId を含む)。権限が有効にされなかった場合の処理を考慮してください。
OFF GRANTED 音声ショッピングの設定を、Alexaアプリ上で有効にする必要があります。
お客様が、このスキルのAmazon Pay権限を以前設定しているかに応じて、Amazon Payの権限も有効にする必要がある可能性があります。
Alexa は、Alexaアプリにカードを送付します。カードには、お客様が音声ショッピングの設定やAmazon Pay権限を有効にするための方法が記載されています。
お客様 は、Alexaアプリにカードが送付され、音声ショッピングの設定やAmazon Pay権限を付与する必要があります。
スキル は、Permission errorsPIN errors を、受け取ります。詳細な情報は、支払いDeclineと処理エラー をご確認ください。
OFF DENIED

手動で、Amazon Pay権限と音声ショッピングの設定が不足している処理を実施する場合

Alexaに権限チェック処理を任せることを強く推奨しますが、スキルチェックを手動で行う場合、手動でAlexaアプリにカードを送ることが出来ます。

Amazon Payのアクセス権限と音声ショッピングの設定をチェックする

もし、Amazon Buyer IDの取得や購入者住所をSetup前に取得する場合は、手動で権限チェックをする必要があります。 権限が有効になっている場合は、下記の通りAlexaのリクエスト本文に以下の形式で情報が表示されます。 詳細については、JSONリクエスト形式のSystemオブジェクトの説明を参照してください。

{
    "version": "1.0",
    "user": {
        "userId": "amzn1.ask.account.[unique-value-here]",
        "accessToken": "Atza|AAAAAAAA...",
        "permissions": {
            "consentToken": "ZZZZZZZ...",
            "scopes": {
                "payments:autopay_consent": {
                "status": "GRANTED"
            }
        }
    }
}

こちらのサンプルコードは、Amazon Pay Alexa Utils for Node.jsを使用しています。

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const permissionIsGranted = AmazonPay.isAmazonPayPermissionGranted(handlerInput.requestEnvelope);

もし、ユーザーが音声ショッピングの設定もしくはAmazon Pay権限を有効にしていない場合は、Alexaに Setup処理の一部として権限チェック処理を任せるか、手動で権限チェックを実施してユーザのAlexaアプリにカードを送付する必要があります。

手動で権限をリクエストする

ユーザーに対して、手動でAmazon Payのアクセス権限をスキルに付与するようにリクエストする際のサンプルコードです。

こちらのサンプルコードは、Alexa Skills Kit SDK for Node.js (v2)を使用しています。

const BuyTicketIntentStartedHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'IntentRequest' 
    && handlerInput.requestEnvelope.request.intent.name === 'BuyTicketIntent';
  },
  handle(handlerInput) {
    const permissions = handlerInput.requestEnvelope.context.System.user.permissions; 
    const amazonPayPermission = permissions.scopes['payments:autopay_consent'];
    if(amazonPayPermission.status === "DENIED"){
      return handlerInput.responseBuilder
          .speak('Please enable permission for Amazon Pay in your companion app.')
          .withAskForPermissionsConsentCard([ 'payments:autopay_consent' ])
          .getResponse();
      }
       ...
  }
}

こちらのサンプルコードは、Amazon Pay Alexa Utils for Node.jsを使用しています。

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const BuyTicketIntentStartedHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'IntentRequest' 
    && handlerInput.requestEnvelope.request.intent.name === 'BuyTicketIntent';
  },
  handle(handlerInput) {
    if(!AmazonPay.isAmazonPayPermissionGranted(handlerInput.requestEnvelope)){
        AmazonPay.askForPermissionCard('Please enable permission for Amazon Pay in your companion app.')
          .send(handlerInput.responseBuilder);
      }
       ...
  }
}

ユーザーの連絡先情報をリクエストする

ユーザーがAlexaスキルを有効にすると、スキルはユーザーに連絡先情報を使用する権限をリクエストできます。ユーザーが承諾すると、スキルで名前、Eメールアドレス、電話番号などの連絡先情報を使用できます。その詳細としくみについては、スキルで使用するためにユーザーの連絡先情報をリクエストするを参照してください。

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

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

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

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

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

Setupを呼び出すときは、Sandboxユーザーの電子メールIDを渡し、ペイロードの作成時にSandboxテスト環境モードをtrueに設定する必要があります。 Setupから、SandboxのBillingAgreementIdが返されます。

Decline発生時のフローをテストするには、特定の支払いシナリオをシミュレートするためのSandboxシミュレーション文字列を使用できます。たとえば、 InvalidPaymentMethodAmazonRejectedTransactionTimedOutなどがあります。

「今すぐ請求」シナリオでの請求失敗をシミュレートするために、Capture関連のシミュレーション文字列を使用して、SandboxのBillingAgreementIdに対してChargeを呼び出すこともできます。

ペイロード内のSellerAuthorizationNoteに、下記文字列を入れるとエラーが返ってくるようになります。

例:"{\"SandboxSimulation\":{\"State\":\"Declined\", \"ReasonCode\":\"InvalidPaymentMethod\", \"PaymentMethodUpdateTimeInMins\":5}}"

Sandboxシミュレーション文字列の詳細については、お住まいの地域に該当する版のAmazon PayインテグレーションガイドのSANDBOXシミュレーションを参照してください。  日本語版  米国版  英国版  EU版

【重要】

Amazon では、スキルを審査する際にAmazon PayのSandbox環境を使用します。そのためBilling AgreementとChargeはSandbox環境で生成されます

スキルの審査をしている間のテストトランザクションを判断する為に、Amazon Payでは、authorization detailsのステータスにのreasonCodeを"CertificationTestTransaction"として返します

reasonCodeが"CertificationTestTransaction"の場合は、実際に注文ロジックを実行しないようにしてください

関連トピック