Vielen Dank für Ihren Besuch. Diese Seite ist momentan nur auf Englisch verfügbar. Wir arbeiten an der deutschen Version. Vielen Dank für Ihr Verständnis.

Integrate a Skill with Amazon Pay

In this section

Before you begin

To protect customer data, your skill must meet the requirements below. If Amazon determines that your skill violates any of these requirements, we will reject or suspend your submission and notify you using the email address associated with your developer account.

  • You must include a link to the Privacy Policy that applies to your skill on the Distribution page of the developer console.
  • Your skill must not be a child-directed skill. For more information, see Child-directed Alexa Skills.
  • You must request permission to receive customer contact information only when required to support the features and services provided by your skill. You must use any personal information you request only as permitted by the user and in accordance with your privacy notice and applicable law.
  • You must not use customer information (name, email address, phone number) to link the customer's account in the background. That is, you must not associate an Alexa customer to a customer in your account pool with the same contact information.
  • The skill must call Alexa Customer Profile API to get the latest customer information every time when the customer invokes the skill.
  • You must meet the Alexa requirements for skills that allow purchases.

Register as an Amazon Payments merchant

To link your Alexa skill with Amazon Pay and process transactions, set up your Amazon Pay account and have it ready for configuring your Alexa skill.

  1. Sign up for an Amazon Payments account (or provision an existing account) from the Amazon Pay website:
  2. Gather your credentials.
    You can find the following credentials in Seller Central on the Amazon Pay and Login with Amazon Integration Settings page (from the Integration menu, click MWS Access Key):
    • Merchant ID (Seller ID)
    • MWS Access Key ID and MWS Secret Access Key
  3. Set up Amazon Payments Sandbox test accounts for testing.
    The Sandbox environment lets you simulate your customers' experience using Amazon Pay but without using real money. For more information, see the Setting up an Amazon Pay Sandbox test account section in the Amazon Pay and Login with Amazon integration guide.

Register as an Amazon Web Services developer

If you will use an AWS Lambda function to control the voice interaction flow or plan to use any other AWS service, create an AWS account at aws.amazon.com. The AWS account is used for Lambda functions to control the voice interaction flow and integration with Amazon Pay.

Create your skill

After you have set up your Amazon Payments account, your Amazon developer account, and your AWS account, you are ready to create your skill with permission to use Amazon Pay.

  1. Build your Alexa skill. If you have questions, see this Alexa documentation:
  2. Register your skill on the Alexa Developer Console. For more information, see Create a Developer Console Account.
  3. On the Permissions page, choose the Amazon Pay permission option.

Link your skill with your Amazon Pay account in Seller Central

  1. Sign in to Amazon Seller Central:
  2. Choose Amazon Pay (Sandbox View) from the Marketplace Switcher drop-down box.
    The Marketplace Switcher appears as a drop-down box in the center of the menu located at the top of the screen:

    If your screen is minimized, the Marketplace Switcher drop-down box is replaced with this button:

  3. Click Integration, and then click Alexa.
  4. On the Amazon Pay on Alexa Skills page, click Connect an Alexa skill.
  5. In the dialog box, paste your Alexa skill ID, check the check box to acknowledge that your skill will sell only goods and services that are permitted by Amazon Pay’s Acceptable Use Policy and no digital goods or services consumed on Alexa, and then click Connect.
    Amazon Pay Acceptable Use Policy for:
  6. Choose Amazon Pay (Production View) from the Marketplace Switcher drop-down box that you used in step 2.
  7. Repeat steps 3 through 5 in Production View to link your skill to your Amazon Payments account for production use.

Set up your payment workflow

Amazon Pay offers two types of charging scenarios:

  • Charge now: You charge customers while they are interacting with your skill.
  • Charge later: You charge customers later by passing the token from your skill to your backend servers, which you can set up to handle requests to the Amazon Pay API.

Amazon Pay for Alexa Skills uses billing agreements to charge your customers. A billing agreement is a record of the customer's preferred payment method, preferred shipping address, and authorization for an automatic payment. Eligible merchants can also receive the customer’s billing address inside the skill. For more information, see Am I eligible to receive customer billing addresses?

The Amazon Pay API is also used by your backend servers for refunds or to retrieve information about your customers. Depending on your preferred way of charging and refunding a customer, you might need to set up a backend server to complete your payment workflows.

Check for Amazon Pay permissions and Voice Purchase settings

To use Amazon Pay inside your skill, customers need to grant Amazon Pay permission to the skill and enable Voice Purchasing in their Alexa app.

You can check to confirm that these permissions are enabled either at the start of your skill or before you take payment.

If the permissions are enabled, the information in the Alexa request body’s user domain is shown in the format below. For more information, see JSON Request format System Object.

Checking for permissions should also be part of your error and decline handling.


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

To proactively request customers to grant Amazon Pay permissions to your skill, you can follow the sample below.


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();
      }
       ...
  }
}

Payment workflow 1: Charge now

The simplest payment scenario lets you create a billing agreement and charge the customer.

This is the best fit, if:

  • You know the purchase amount up front.
  • The customer is still using your skill.
  • You are not planning to build recurring or subscription use cases.

Setting up backend servers is optional for this workflow.

Typical charge-now sequence diagram for purchase, payment decline, and refund scenarios

typical charge-now sequence diagram
See larger diagram

The first time you call Amazon Pay for a customer, build the SetupAmazonPay payload to set the Connections.SendRequest directive. Sending a Connections.SendRequest directive to Alexa indicates a Setup action with SetupAmazonPay payload.

The result of Setup is a Connections.Response request provided to your skill.


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": "US",
                "ledgerCurrency": "USD",
                "checkoutLanguage": "en_US",
                "billingAgreementAttributes": {
                    "@type": "BillingAgreementAttributes ",
                    "@version": "2",
                    "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();
    }
};

Make sure you specify the correct values for countryOfEstablishment, ledgerCurrency, and checkoutLanguage so they match your Amazon Payments account and the skill language that the customer is using.

When you have completed Setup, you can use a Connections.Response request to getBillingAgreementDetails and billingAgreementId. Storing the billingAgreementId lets you skip the Setup step the next time the same customer uses your skill.

To use Amazon Pay inside your skill, customers need to grant Amazon Pay permission to the skill and enable Alexa Voice Shopping.

This information is included in the Alexa request body’s user domain in the format below. Use this information as soon as a customer enters a charge flow or at the time of skill launch if your skill only offers charge scenarios. For details, see Ask customers to turn on Amazon Pay permissions in your skill.


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('Please enable permission for Amazon Pay in your companion app.)
                .withAskForPermissionsConsentCard([ 'payments:autopay_consent' ])
                .getResponse();
      break;
    default:
      return handlerInput.responseBuilder
            .speak("Error Occured. Error status code " + statusCode + ". Error payload message " + errorMessage  + ".")
            .getResponse();
  }
}


The next step is to charge your customer. Set the billingAgreementId in the ChargeAmazonPay payload to send a Connections.SendRequest directive with the Charge action and the Charge payload:


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": "USD"
                    },
                    "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();
    }
};

When a successful Charge response is received, the charge flow is complete. Confirmation is provided to your customers:

  • They hear a prompt confirming the amount and telling them they will be charged using Amazon Pay.
  • A confirmation card is pushed to the Alexa companion app with all of the charge details.
  • They receive an email confirming the charge amount.

To complete the charge-now flow, set up error and decline handling.

Payment workflow 2: Charge later

The charge-later payment option provides more flexibility than charge now by separating customer setup from the process for charging the customer at a later point. This option requires an Amazon Pay with automatic payments integration. For details, see the appropriate guide for your region:   US   UK   EU

This workflow is the best fit if:

  • The customer is still shopping or using your skill after selecting items for checkout (good for upsell opportunity or promotional tie-ins).
  • The checkout amount is not yet known, such as for pay-as-you-go usage or when the service will be used at a later time.
  • You charge on a subscription or regularly recurring basis.
  • You will recognize the customer and offer personalized or tailored experiences based on account history.

Typical charge-later sequence diagram

typical charge-later sequence diagram
See larger diagram

The first time you call Amazon Pay for a customer, you should build the SetupAmazonPay payload to set the Connections.SendRequest directive. Sending a Connections.SendRequest directive to Alexa indicates a Setup action with SetupAmazonPay payload.



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": "US",
                "ledgerCurrency": "USD",
                "checkoutLanguage": "en_US",
                "billingAgreementAttributes": {
                    "@type": "BillingAgreementAttributes",
                    "@version": "2",
                    "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();
    }
};

Be sure to specify the correct values for countryOfEstablishment, ledgerCurrency and checkoutLanguage so they match your Amazon Payments account and the skill language that the customer is using.

Note: SellerBillingAgreementAttributes are shown in email communications to the customer. See "Buyer-facing email content that you can provide" in the appropriate version of the Amazon Pay with recurring payments integration guide for your region:   US   UK   EU

The result of Setup is a Connections.Response request provided to your skill.

When you have completed Setup you can use a Connections.Response request to getBillingAgreementDetails and billingAgreementId. Storing the billingAgreementId lets you skip the Setup step the next time the same customer uses your skill or the next time you charge the customer in a recurring payments scenario.

Now that you have a valid billingAgreementId on file for your customer, you can send it to your backend server, store it with the customer account, or use it to retrieve additional information, like the email address. For more information, see the GetBillingAgreementDetails section of the appropriate version of the Amazon Pay API reference guide for your region:   US   UK   EU

The following code sample demonstrates receiving the billingAgreementId and handing it over to store it.



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;

        return handlerInput.responseBuilder
            .speak("Test skill has completed setting up payment.")
            .getResponse();
    }
};

Note: Setting up backend servers is required for this workflow. For more information, see Set up your backend server.

To charge the customer, follow the integration steps in the appropriate version of the Amazon Pay with automatic payments integration guide for your region:   US   UK   EU

Set up your backend server

In a charge-later scenario, you need a backend server to communicate with your skill and to make requests to and receive responses from the Amazon Marketplace Web Service (Amazon MWS) server.

Important
We strongly recommend that you observe the following practices:
  • Do not log or store sensitive information in client apps.
  • Do not distribute your credentials (MWS Access and MWS Secret Access Keys).
  • Do not call Amazon MWS APIs directly from client applications. MWS calls should take place from your server because it is unsafe to save your MWS Access and Secret Access Keys and your Seller ID in a client app. MWS calls from a secure AWS component such as Lambda meet best practice guidelines.
  • To prevent eavesdropping or man-in-the-middle attacks, exchange all app-to-server communications via TLS/SSL.

Amazon Pay provides SDKs in multiple languages to help you set up your backend server. We strongly recommend that you review and use them because they provide the quickest integration between your service and Amazon's servers. For more information, see the appropriate Amazon Pay SDKs and samples links for your region:   US   UK   EU

If our SDKs don't meet your needs and you want to set up your own backend server, see Using the Amazon MWS client libraries for more information.

To complete the charge-later flow, set up error and decline handling.

Request customer contact information

When a customer enables your Alexa skill, your skill can request the customer's permission to access their contact information, which includes name, email address, and phone number, with the customer's consent. For more details and to learn how this works, see Request customer contact information for use in your skill.

Set up error and decline handling

Regardless of which payment flow scenario you chose, you need to set up error and decline handling for your Alexa skill.

For details and descriptions of the error types, see Payment declines and processing errors.

Test your integration

Testing in a Sandbox environment lets you validate the integration of your skill with Amazon Pay without placing live orders.

Note that when calling setup and building your payload, you must pass the Sandbox user email id and set Sandbox mode to true. Setup will return a Sandbox BillingAgreementId.

To test decline flows, you can use sandbox simulation strings to simulate specific payment scenarios. For example: InvalidPaymentMethod, AmazonRejected, and TransactionTimedOut.

To simulate failing charges in a charge-now scenario, you can also use Capture-related simulation strings and call Charge on the Sandbox BillingAgreementId.

For details about sandbox simulation strings, see the appropriate version of the Amazon Pay and Login with Amazon integration guide for your region:   US   UK   EU

See also