スキルと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(出品者ID)
    • MWS Access Key IDおよびMWSシークレットアクセスキー
  3. Amazon Pay Sandboxアカウントをテスト用にセットアップします。テスト環境では、実際のお金を使わずに、Amazon Payを使用したユーザーエクスペリエンスをシミュレートできます。詳細については、Amazon Payインテグレーションガイドの次のセクションを参照してください。

Amazon開発者として登録する

Alexaスキルを作成するには、https://developer.amazon.com/ でAmazon開発者として登録する必要があります。音声対話フローを制御するためにAWS Lambda関数を使用する場合や、他のAWSサービスを使用する予定がある場合は、AWSアカウントをaws.amazon.comで作成します。AWSアカウントはLambda関数で使用され、音声対話フローやAmazon Payのインテグレーションを行います。

スキルを作成する

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

  1. Alexaスキルをビルドします。不明点がある場合は、次のAlexaドキュメントを参照してください。
  2. Alexa開発者コンソールでスキルを登録します。詳細については、開発者コンソールアカウントの作成を参照してください。
  3. アクセス権限ページで、Amazon Payオプションを有効にしてください。
    For an example showing how to use Amazon Pay for your shopping experiences with Alexa, check out this custom skill for a demonstration store.

セラーセントラルでスキルを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アカウントに接続します。

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

Amazon Pay Buyer ID は、事業者ごとにカスタマーを一意に特定できるようにした永続的な ID です。

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

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

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

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

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

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

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

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

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

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

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

スキル内でAmazon Payを使用するには、ユーザーがスキルにAmazon Payのアクセス権限を付与し、Alexaアプリで音声ショッピングを有効にする必要があります。

もし、カスタマーが音声ショッピングの権限もしくは、Amazon Payの権限を有効にしていない場合は、開発者はカスタマーに決済をする前に権限を有効にする為のカードを Alexa アプリに送信する必要があります。buyer IDを使用している場合は、アクセス権限を確認するように推奨しております。

アクセス権限が有効になっていない場合は、Alexaのリクエスト本文に以下の形式で情報が表示されます。詳細については、JSONリクエスト形式のSystemオブジェクトの説明を参照してください。

アクセス権限の確認は、エラーとDeclineの処理でも行う必要があります。


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

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


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('Amazon Payの権限が有効になっておりません。Alexaアプリにカードを送りましたのでAlexaアプリからAmazon Payを有効にしてください。’)
          .withAskForPermissionsConsentCard([ 'payments:autopay_consent' ])
          .getResponse();
      }
       ...
  }
}

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

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

次の場合に最適です。

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

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

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

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

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

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


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",
                    "sellerNote": "Billing Agreementに関する販売事業者のメモ",
                    "sellerBillingAgreementAttributes": {
                        "@type": "SellerBillingAgreementAttributes ",
                        "@Version": "2",
                        "sellerBillingAgreementId": "B03-XXXXXX-XXXXXXX",
                        "storeName": "テスト用ストア名",
                        "customInformation": "テスト用カスタム情報"
                    }
                },
                "needAmazonShippingAddress": false
            },
            "token": "correlationToken"
        };
        return handlerInput.responseBuilder
            .addDirective(directiveObject)
            .withShouldEndSession(true)
            .getResponse();
    }
};

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

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

スキル内で Amazon pay を利用するには、購入者は Amazon Payと音声ショッピングの権限を有効にする必要があります。これらの権限の状態はrequestのpayloadに含まれており、開発者は下記のサンプルコード と同様に確認することができます。権限の有効の確認は好きなタイミングで確認することができるためスキルの起動時にもしくは、Chargeのシナリオ処理の手前で確認することが可能です。必要なシナリオに応じてお使いください。 詳しくは、 スキルでamazon-payのアクセス権限を有効にするようにユーザーに依頼する


function handleErrors(statusCode, handlerInput ) {
  let errorCode = handlerInput.requestEnvelope.request.payload.errorCode;
  let errorMessage = handlerInput.requestEnvelope.request.payload.errorMessage;

  switch ( errorCode ) {
    case "ACCESS_NOT_REQUESTED":
      return handlerInput.responseBuilder
                .speak('Amazon Payの権限が有効になっておりません。Alexaアプリにカードを送りましたのでAlexaアプリからAmazon Payを有効にしてください。')
                .withAskForPermissionsConsentCard([ 'payments:autopay_consent' ])
                .getResponse();
      break;
    default:
      return handlerInput.responseBuilder
            .speak("エラーが発生しました。エラーステータスコード: " + statusCode + "。 エラーペイロードメッセージ " + errorMessage + ".")
            .getResponse();
  }
}

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


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;
        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": "100",
                        "currencyCode": "JPY"
                    },
                    "transactionTimeout": 0,
                    "sellerAuthorizationNote": "テスト用販売事業者の認証に関するメモ"
                },
                "sellerOrderAttributes": {
                    "@type": "SellerOrderAttributes",
                    "@version": "2",
                    "sellerOrderId": "ABC-000-123234",
                    "storeName": "テスト用ストア名",
                    "customInformation": "テスト用カスタム情報",
                    "sellerNote": "テスト用の販売事業者のメモ"
                }
        },
        "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) {
            //エラー処理を実装します
        }
        return handlerInput.responseBuilder
            .speak("決済が完了しました。ご注文ありがとうございました。")
            .getResponse();
    }
};

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

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

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

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

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

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

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

後で請求の一般的な手順

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

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



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",
                    "sellerNote": "Billing Agreementに関する販売事業者のメモ",
                    "sellerBillingAgreementAttributes": {
                        "@type": "SellerBillingAgreementAttributes",
                        "@version": "2",
                        "sellerBillingAgreementId": "B03-XXXXXX-XXXXXXX",
                        "storeName": "テスト用ストア名",
                        "customInformation": "テスト用カスタム情報"
                    }
               },
               "needAmazonShippingAddress": false
          },
          "token": "correlationToken"
      };

        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版   日本語版

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

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

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

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

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

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

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

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

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

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

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

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

Important

When you submit your skill through certification, Amazon will test your skill in the Sandbox environment and will create Sandbox Billing Agreements and charges.

When an order is placed during certification, the authorization details status reasonCode will return "CertificationTestTransaction."

Make sure that your business logic ignores CertificationTestTransaction certification orders to prevent unintended items to be shipped out.

関連トピック