Integrate your Skill with Amazon Pay

Before you begin

Be aware of the requirements for your skill to pass certification.

Register as an Amazon Payments merchant

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

  1. Sign up for an Amazon Payments account (or use an existing account) from the Amazon Pay website:
  1. 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
  2. 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 Amazon Web Services (AWS) Lambda function to control the voice interaction flow or plan to use any other AWS services, 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 Merchant account, your Amazon Developer account , and your AWS account, you're ready to create your skill with permission to use Amazon Pay.

  1. Build your Alexa skill. If you have questions, see these Alexa resources:
  2. Register your skill on the Alexa Developer Console.
  3. On the Permissions page, choose the Amazon Pay permission option.

For an example showing how to use Amazon Pay for your shopping experiences with Alexa, check out this custom skill for a demonstration store.

  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: Marketplace Switcher
    If your screen is minimized, the Marketplace Switcher drop-down box is replaced with this button:
    Marketplace Switcher
  3. Click Integration, and then click Alexa.
  4. On the Amazon Pay for Alexa Skills page, click Connect an Alexa skill.
  5. In the dialog box, add 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:

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 BillingAgreement 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 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?

Payment workflow 1: Charge now

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

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. If you want to use the customer's shipping address to determine if you can deliver to their address or calculate shipping and taxes to include in the order total, you can use the Buyer Address API in the charge-now workflow before you call Setup or Charge.

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

typical charge-now sequence diagram See larger diagram

The first call you will make with Amazon Pay for a customer, will be for the Setupoperation. Build the SetupAmazonPayRequest payload and add it to a Connections.SendRequest directive. When sending the Connections.SendRequest directive to Alexa, please specify the name as Setup.

This sample code uses the 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": "US",
                "ledgerCurrency": "USD",
                "checkoutLanguage": "en-US",
                "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();
    }
};

This sample code uses the 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('US')
          .withLedgerCurrency('USD')
          .withCheckoutLanguage('en-US')
          .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();
    }
};

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 will recieve a Connections.Response request, which you can use to get BillingAgreementDetails and the billingAgreementId. A Connectins.Response will include the correlationToken you specified in your Directive to allow you to match requests and responses.

The next step is to charge your customer. Set the billingAgreementId and all other required details in the ChargeAmazonPayRequest payload and send a Connections.SendRequest directive with the Charge action as part of your response:

This sample code uses the 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": "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();
    }
};

This sample code uses the 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('USD')
          .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();
    }
};

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. If you're selling in Europe or the UK, also follow the payment authentication handling guidance.

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: EU  JP  UK  US  

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.

If you want to use the customer's shipping address to determine if you can deliver to their address or calculate shipping and taxes to include in the order total, you can use the Buyer Address API in the charge-later workflow before you call Setup or Charge.

Typical charge-later sequence diagram

typical charge-later sequence diagram

See larger diagram

The first call you will make with Amazon Pay for a customer, will be for the Setupoperation. Build the SetupAmazonPayRequest payload and add it to a Connections.SendRequest directive. When sending the Connections.SendRequest directive to Alexa, please specify the name as Setup.

This sample code uses the 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": "US",
                "ledgerCurrency": "USD",
                "checkoutLanguage": "en-US",
                "billingAgreementAttributes": {
                    "@type": "BillingAgreementAttributes",
                    "@version": "2",
                    "billingAgreementType": "MerchantInitiatedTransaction",//EU and UK merchants only
                    "subscriptionAmount": {
                       "@type": "Price",
                       "@version": "2",
                       "amount": "19.99",
                       "currencyCode": "USD"
                    },
                    "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();
    }
};

This sample code uses the 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('US')
          .withLedgerCurrency('USD')
          .withCheckoutLanguage('en-US')
          .withBillingAgreementType('MerchantInitiatedTransaction') //EU and UK merchants only
          .withSubscriptionAmount('19.99')
          .withSubscriptionCurrency('USD')
          .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();
    }
};

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. Also specify your intended use of the BillingAgreement via the billingAgreementType parameter.

If you intend to offer subscriptions or other recurring payment use cases, also specify the subscriptionAmount if it's already known at this stage. Otherwise, just leave it out completely.

The result of Setup is a Connections.Response request provided to your skill. A Connectins.Response will include the correlationToken you specified in your Directive to allow you to match requests and responses.

When you have completed Setup you can use the payload in the Connections.Response request to get BillingAgreementDetails and the billingAgreementId. Storing the billingAgreementId (for example, on your backend) lets you charge the customer in a recurring payments or charge-later scenario using the Amazon Pay backend APIs.

If you're selling in Europe or the UK, also follow the guidance for payment authentication handling.

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:   EU  JP  UK  US

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

This sample code uses the 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;

        storeAmazonPayBillingAgreementOnBackend(billingAgreementID);

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

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

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.

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:  EU  JP  UK  US

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.

You can use the billingAgreementId received in your skill to issue a charge using our SDKs or via our APIs directly.

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

Personalize your customers' experience with buyer ID

Amazon Pay buyer ID is a persistent ID specific to a customer and merchant. You can use the Amazon Pay buyer ID to build connected and personalized experiences for customers, like letting a customer start a purchase on their smartphone and complete it later using Alexa.

Amazon Pay recommends that third-party developers of Alexa skills call the Amazon Pay buyer ID API early in the customer journey to check if they can match the existing customer record using Amazon Pay buyer ID. This avoids the friction that comes with Alexa account linking.

For details, see How to use buyer ID

If you are using the Amazon Pay Alexa Utils for Node.js, you can benefit from the convenience function getBuyerId as follows:

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

  async handle: {
  ...
  // use this to have the current locale decide for the region to use
  const buyerId = await AmazonPay.getBuyerId(requestEnvelope);

  // if you want to specify the region yourself
  const buyerId = await AmazonPay.getBuyerIdForRegion(requestEnvelope, region);
  ...
  }

Amazon Pay permissions and Voice Purchase settings

To use Amazon Pay inside your skill, customers need to grant Amazon Pay permission to your skill and enable Voice Purchasing in their Alexa app. When executing the Amazon Pay Setup operation, Alexa handles this for you. To learn how you can manually handle this - e.g. for Buyer ID or Buyer Address needs before initiating a checkout - please read how to Manually handle missing Amazon Pay permissions or Voice Purchase settings.

Here is an overview on how Alexa will handle the different situations:

Voice Purchasing Amazon Pay permission Result
ON GRANTED All required settings are in place.
Alexa attempts to create a BillingAgreement as requested.
Customers will be asked for the voice PIN - if set up and required - and afterwards be handed back to your skill.
Your skill will receive BillingAgreementDetails including a billingAgreementId which you can use to complete the checkout when a BillingAgreement was created successfully. You still need to be prepared to handle non-permission related errors.
ON DENIED Amazon Pay permissions for your skill need to be granted by the customer.
Alexa will ask the customer to grant the Amazon Pay permission and consent to sharing checkout-related data via voice. Depending on the customer's response, Alexa can attempt to create a BillingAgreement or might send a card to the customer's Alexa app, e.g. to give the customer more information to make this decision.
Customers will be asked if they agree to granting the Amazon Pay permission for your skill.
Your skill will receive BillingAgreementDetails including a billingAgreementId which you can use to complete the checkout, if the customer grants permissions and no further error occurs. Please be prepared to handle declined permissions or any other form of error that might occur.
OFF GRANTED Voice Purchasing settings need to be turned on in the Alexa app. Depending if a customer previously granted Amazon Pay for your skill or not, the Amazon Pay permission also needs to be granted. The process for both cases is however the same.
Alexa will send a card to the Alexa app of the customer, which helps the customer in setting up Voice purchasing permissions and if required also to grant the Amazon Pay permission.
Customers will be informed about the card sent to their Alexa app and are required to enable Voice purchasing, respectively grant the Amazon Pay permission via the Alexa app.
Your skill will receive one of the error messages listed in Permission errors or PIN errors listed in the payment declines and processing errors section.
OFF DENIED

Manually handle missing Amazon Pay permissions or Voice Purchase settings

We highly recommend allowing to let Alexa handle permissions and voice purchase settings for you. However, there are situations where you need to know at runtime, if permissions are (still) granted and all required settings are in place. If needed, you can also manually send a card to request permissions to the customer's Alexa app.

Checking for Amazon Pay permission and Voice purchase status at runtime

In some situations - e.g. when using the Buyer ID and Buyer Address APIs - or as part of your error and decline handling, you will need to manually check for permissions.
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.

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

This sample code uses the Amazon Pay Alexa Utils for Node.js.

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

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

If your customer has not turned on Voice Purchasing or Amazon Pay permissions in your skill, you can still rely on Alexa handling this for you as part of the Setupoperation, or manually request permissions by sending a permission card to the customer's Alexa app.

Manually request permissions at runtime

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

This sample code uses the 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();
      }
       ...
  }
}

This sample code uses the 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);
      }
       ...
  }
}

Request customer contact information

Amazon Pay enables you to retrieve the customer information needed to fulfill the order, which includes name, email address, delivery address and phone number, using the BillingAgreement created via the Setupoperation.
If you need this data earlier in your voice experience, your skill can request the customer's permission to access their contact information separately. 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

You need to set up error and decline handling for your Alexa skill as well as for your Amazon Pay integration.

For details and descriptions of the Alexa error types, see Payment declines and processing errors.
For details and descriptions of the Amazon Pay error types, see Step 7: Prepare to handle declined authorizations in the Amazon Pay and Login with Amazon integration guide.

Set up payment authentication handling (for EU and UK merchants only)

This section is relevant for all merchants offering their real-world goods and services in Europe or the UK.

The Payment Service Directive 2 (PSD2) introduces Strong Customer Authentication (SCA) in the EU and the UK. To inform merchants about the outcome of the payment authentication, Amazon Pay has added dedicated error responses.

Follow the instructions for handling the authentication response in your payment workflow (either charge now or charge later) in addition to the general guidance given in this guide. To simulate the different outcomes of the challenge in the Sandbox environment, see Test your integration.

Payment workflow 1: Charge now

In a charge-now scenario, the payment authentication happens after the Charge operation has been called by your skill. The response from Amazon Pay doesn't change if the challenge is completed successfully.

If a customer fails or abandons the payment verification challenge, the Charge operation sends dedicated error responses. Amazon Pay handles those errors by providing meaningful prompts to customers. Make sure that you also handle those errors correctly in your skill, and don't fulfill your order because no charge will have been made when such an error response is received.

For details and prompts, see Authentication errors.

Payment workflow 2: Charge later

Charge later scenarios are currently not supported in the EU and UK.

Testing payment authentications (for EU merchants only)

Testing payment authentications in a Sandbox environment lets you ensure the correct handling of all authentication outcomes 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 simulate the different authentication results, use the following sandbox simulations.

State Simulation string How to simulate in Sandbox
Failure 
{"SandboxSimulation":{"PaymentAuthenticationStatus":{"State":"Failure"}}}

CustomerInitiatedTransactions
Specify this value in the SellerNote of the SellerOrderAttributes in the Charge API

MerchantInitiatedTransactions
Specify this value in the SellerNote of the SellerOrderAttributes in the Setup API
Abandoned 
{"SandboxSimulation":{"PaymentAuthenticationStatus":{"State":"Abandoned"}}}

CustomerInitiatedTransactions
Specify this value in the SellerNote of the SellerOrderAttributes in the Charge API

MerchantInitiatedTransactions
Specify this value in the SellerNote of the SellerOrderAttributes in the Setup API
NotSupported 
{"SandboxSimulation":{"PaymentAuthenticationStatus":{"State":"NotSupported"}}}

CustomerInitiatedTransactions
Specify this value in the SellerNote of the SellerOrderAttributes in the Charge API

MerchantInitiatedTransactions
Specify this value in the SellerNote of the SellerOrderAttributes in the Setup API

Test your integration

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

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:   EU  JP  UK  US

Submit your skill to certification

Once your skill is built and tested, it's time to submit your skill for certification. Before doing this

  • please ensure you meet all certification requirements that apply.
  • double check, if you handle the CertificationTestTransaction reasonCode to ensure certification tests don't make you ship certification orders or cause other kinds of side effects.
  • lastly, ensure you have added correct Privacy Policy and Terms of Use URLs to your skill.

For merchants in the EU or the UK, we highly recommend to use the Just certify option and manually publish your skill when both skill and your Amazon Payments merchant account are certified, respectively verified. To learn more about this option, visit Test and Submit Your Skill for Certification

Last updated: Dec 29, 2022