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.

  • On the Launch page of the developer console, you must include a link to the Privacy Policy that applies to your skill.
  • Your skill must not be a child-directed skill. For more information, see Child-Directed Alexa Skills.
  • You must use the requested customer contact information only as strictly required to perform the contractual service requested by the customer.
  • You must not use device address information 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 address information.

Register as an Amazon Pay 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 Pay account (or provision an existing account) from the Amazon Pay website, at https://pay.amazon.com/us/merchant.
  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 Pay 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.

Become an Amazon developer

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 Pay 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:

    Note:Amazon requires you to include an intent in your skill that tells customers how to contact you to cancel a purchase and/or request a refund for a purchase. We recommend that you include this information in your skill description and in any cards that you push to the customer.

  2. Register your skill on the Alexa Developer Console.
  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 Seller Central.
  2. Confirm that you are in Sandbox View.
  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.
  6. Repeat steps 3 through 5 in Production View to link your skill to your Amazon Pay account for production use.
  7. After linking your account, disconnect the skill from your Seller Central account by choosing Disconnect Skill.

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.

The workflows depend on the user consentToken that is created when the customer enables the Amazon Pay-enabled skill in the Alexa companion app. If the customer does not give permission to enable Amazon Pay for the skill, the consentToken will not be valid for any of the payment workflows.

Amazon Pay for Alexa Skills uses the concept of billing agreements to charge your customers. A billing agreement is a record of the buyer's preferred payment method, preferred shipping address, and if applicable, authorization for a recurring payment.

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 must set up a backend server to complete your payment workflows.

Payment workflow 1: Charge now

This is the simplest payment scenario, which 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

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.

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) {
        const consentToken = handlerInput.requestEnvelope.context.System.apiAccessToken;
        let directiveObject = {
            "type": "Connections.SendRequest",
            "name": "Setup",
            "payload": {
                "SetupAmazonPay": {
                    "consentToken": consentToken,
                    "sellerId": "AEMGQXXXKD154",
                    "countryOfEstablishment": "US",
                    "ledgerCurrency": "USD",
                    "checkoutLanguage": "en_US",
                    "billingAgreementAttributes": {
                        "platformId": "",
                        "sellerNote": "Billing Agreement Seller Note",
                        "sellerBillingAgreementAttributes": {
                            "sellerBillingAgreementId": "BA12345",
                            "storeName": "Test store name",
                            "customInformation": "Test customer information"
                        }
                    },
                    "needAmazonShippingAddress": false
                }
            },
            "token": "correlationToken"
        };

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

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

Note: If your customer has not turned on Amazon Pay permissions in your skill, you can request that they do so. The code sample below shows how to direct your customer to turn on the Amazon Pay permissions.


function handleErrors( actionResponseStatusCode, handlerInput ) {
  let actionResponseErrorCode   = handlerInput.requestEnvelope.request.payload.errorCode;
  let actionResponsePayloadMessage  = handlerInput.requestEnvelope.request.payload.errorMessage;
  let speakMessage = "";

  switch ( actionResponseErrorCode) {
    case "ACCESS_NOT_REQUESTED":
      speakMessage = "Please enable permission for Amazon Pay in your companion app.";
      break;
    default:
      speakMessage = "Error Occured. Error status code " + actionResponseStatusCode + ". Error payload message " + actionResponsePayloadMessage + ".";
  }

  return speakMessage;
}

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;
        const consentToken = handlerInput.requestEnvelope.context.System.apiAccessToken;
        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": {
                "ChargeAmazonPay": {
                    "consentToken": consentToken,
                    "sellerId": "AEMGQXXXKD154",
                    "billingAgreementId": billingAgreementID,
                    "paymentAction": "AuthorizeAndCapture",
                    "authorizeAttributes": {
                        "authorizationReferenceId": "sdfwr3423fsxfsrq43",
                        "authorizationAmount": {
                            "amount": "1.01",
                            "currencyCode": "USD"
                        },
                        "transactionTimeout": 0,
                        "sellerAuthorizationNote": "Test Seller Authorization Note",
                        "softDescriptor": "AMZ*"
                    },
                    "sellerOrderAttributes": {
                        "sellerOrderId": "ABC-000-123234",
                        "storeName": "Test Store Name",
                        "customInformation": "Test customer 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 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 recurring payments integration.

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

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) {
        const accessToken = handlerInput.requestEnvelope.context.System.apiAccessToken;
        let directiveObject = {
            "type": "Connections.SendRequest",
            "name": "Setup",
            "payload": {
                "SetupAmazonPay": {
                    "consentToken": consentToken,
                    "sellerId": "AEMGQXXXKD154",
                    "countryOfEstablishment": "US",
                    "ledgerCurrency": "USD",
                    "checkoutLanguage": "en_US",
                    "billingAgreementAttributes": {
                        "platformId": "",
                        "sellerNote": "Billing Agreement Seller Note",
                        "sellerBillingAgreementAttributes": {
                            "sellerBillingAgreementId": "BA12345",
                            "storeName": "Test store name",
                            "customInformation": "Test customer information"
                        }
                    },
                    "needAmazonShippingAddress": false
                }
            },
            "token": "correlationToken"
        };

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

Note: SellerBillingAgreementAttributes are shown in email communications to the customer. See Buyer-facing email content that you can provide in the Amazon Pay with recurring payments integration guide.

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 enables you to 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.

Note: If your customer has not turned on Amazon Pay permissions in your skill, you can request that they do so. The code sample below shows how to direct your customer to turn on the Amazon Pay permissions.


function handleErrors(actionResponseStatusCode, handlerInput) {
    let actionResponseErrorCode = handlerInput.requestEnvelope.request.payload.errorCode;
    let actionResponsePayloadMessage = handlerInput.requestEnvelope.request.payload.errorMessage;
    let speakMessage = "";

    switch (actionResponseErrorCode) {
        case "ACCESS_NOT_REQUESTED":
            speakMessage = "Please enable permission for Amazon Pay in your companion app.";
            break;
        default:
            speakMessage = "Error Occured. Error status code " + actionResponseStatusCode + ". Error payload message " + actionResponsePayloadMessage + ".";
    }

    return speakMessage;
}

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 GetBillingAgreementDetails in the Amazon Pay API reference guide.

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;
        const consentToken = handlerInput.requestEnvelope.context.System.apiAccessToken;
        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 Amazon Pay with recurring payments integration guide.

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 must take place from your server as 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 SDKs and Samples links in the Amazon Pay Documentation.

If our SDKs do not 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 handling.

Set up error handling

Regardless of which payment flow scenario you chose, you need to set up error 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, you must pass the Sandbox user email id and set Sandbox mode to true when building your payload. 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.

For testing a charge-now scenario: Use the Sandbox BillingAgreementId to call Charge which would simulate the Sandbox mode.

In a charge-later scenario: For further details on sandbox simulation strings, see Sandbox simulations in the Amazon Pay and Login with Amazon integration guide.

Learn more about testing your Alexa skill in the Test Your Skill section.

Get your skill certified and go live

Congratulations! You have built your skill, linked it with Amazon Pay, and tested it in Sandbox mode to confirm that it is working as desired. Your final step, after switching to Production mode, is to launch.

  1. Return to the developer portal, and then sign in.
  2. Click the Launch tab, and follow the steps for getting your skill certified.