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.

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.

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

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.

Build your Alexa skill. If you have questions, see this Alexa documentation:

Link your skill with your Amazon Pay account in Seller Central

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:

Click Integration, and then click Alexa.

On the Amazon Pay on Alexa Skills page, click Connect an Alexa skill.

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:

Choose Amazon Pay (Production View) from the Marketplace Switcher drop-down box that you used in step 2.

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.

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.

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.

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.

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

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

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.

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

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

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

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.

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

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.