Alexa Blogs
With Amazon Pay for Alexa Skills, you can sell real-world goods and services such as tickets for movies or concerts, car pick up services, food, and more. You can reach customers around the world through an interaction as natural as voice, powered by a seamless payment processing flow handled by Amazon Pay.
Developers are already using Amazon Pay to bring a variety of real-world products to voice. For example, the British rail operator Virgin Trains is able to sell train tickets to customers directly through their Alexa-enabled device.
After building an engaging voice experience, you’re ready to learn more about monetizing your Alexa skill using Amazon Pay for Alexa Skills. This post will show you how to add Amazon Pay to your skill in just a few simple steps. Before you start, sign-up as an Amazon Pay merchant. Learn more in our guide.
The Amazon Pay for Alexa Skills APIs consist of only two operations - Setup and Charge. We will walk you through both, below.
Setup
Setup will create an agreement between your merchant account and the buyer, called a BillingAgreement, which will be used to charge the customer in a later step. Amazon Pay uses Alexa Skill Connections to have your skill interact with the Amazon Pay services. To initiate the creation of the agreement, we create a matching Connections directive to call the setup operation.
let setupDirective = {
'type': 'Connections.SendRequest',
'name': 'Setup',
'payload': {
'@type': 'SetupAmazonPayRequest',
'@version': '2',
'sellerId': 'AEMGQXXXKD154',
'countryOfEstablishment': 'US',
'ledgerCurrency': 'USD',
'checkoutLanguage': 'en-US',
'needAmazonShippingAddress': true,
'billingAgreementAttributes': {
'@type': 'BillingAgreementAttributes',
'@version': '2',
'sellerNote': 'Thanks for shaving with No Nicks',
'sellerBillingAgreementAttributes': {
'@type': 'SellerBillingAgreementAttributes',
'@version': '2'
}
}
},
'token': 'IK1yRWd8VWfF'
};
First, we define the Connections.SendRequest directive for the Amazon Pay Setup operation. The payload inside the directive defines all Amazon Pay relevant information. The most essential ones are the sellerId, which defines who is initiating the charge, the countryOfEstablishment and ledgerCurrency define how to charge the customer. For definitions of all other fields, refer to our comprehensive guide linked to in the resources section.
You'll notice, we did not define how much to charge yet. This is subject to the Charge operation, if you charge inside your skill, or any other service using our backend APIs, you are charging “offline”.
Adding the directive to your response is fairly simple:
return handlerInput.responseBuilder
.addDirective(setupDirective)
.withShouldEndSession(true)
.getResponse();
Note: the reason we end the session is because the Connection.Request will terminate your skill session and invoke it again with a Connections.Response. If you do not end your session or add a re-prompt, it will result in an error.
To catch the response, simply define a handler for the Connections.Response request
canHandle(handlerInput) {
return handlerInput.requestEnvelope.request.type === "Connections.Response"
&& handlerInput.requestEnvelope.request.name === "Setup";
}
;
The payload of the response will contain the billingAgreementId needed to charge the customer.
Charge
Amazon Pay can help you with a variety of use cases. We classify them as the payment workflows, Charge Now and Charge Later.
Charge Now allows you to sell real-world goods (e.g. tickets, clothing, etc.) and charge the buyer while they are still interacting with your skill. It's a perfect match for one-time purchases where you know the exact charge amount. The starter kit in the “No Nicks” demo skill is an example of Charge Now.
Charge Later allows you to setup a BillingAgreement, which represents the buyer's payment and delivery address preferences, if available, and use this agreement to charge the customer at a later point in time via Amazon Pay backend APIs. It's the perfect match when you don't know the exact order total yet - e.g. for up-sell opportunities, pay-as-you-go scenarios or subscriptions, where a buyer will be charged in regular intervals.
In the chargeNow workflow, you can similarly execute a charge request, using the billingAgreementId received in the setup response.
const billingAgreementId = responsePayload.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': 'ml3qPJG3nC6c65UE',
'authorizationAmount': {
'@type': 'Price',
'@version': '2',
'amount': '9',
'currencyCode': 'USD'
},
'transactionTimeout': 0,
'sellerAuthorizationNote': '',
'softDescriptor': 'No Nicks'
},
'sellerOrderAttributes': {
'@type': 'SellerOrderAttributes',
'@version': '2',
'storeName': 'No Nicks',
'sellerNote': 'Thanks for shaving with No Nicks'
}
},
'token': 'WASv2lk4pdfI'
}
The charge operation requires you to at least specify the total amount and currency to request from the customer. For a full reference, refer to the comprehensive guide in the resources below.
Just like with the setup phase, we'll add the directive to the responseBuilder when preparing the response.
return handlerInput.responseBuilder
.addDirective(directiveObject)
.withShouldEndSession(true)
.getResponse();
Once again, define a handler for the Connections.Response request
canHandle(handlerInput) {
return handlerInput.requestEnvelope.request.type === "Connections.Response"
&& handlerInput.requestEnvelope.request.name === "Charge";
}
The response of the Connections request will tell you if the charge was successful or if there was an issue taking payments.
After a successful purchase, you should send a card to the customer’s Alexa app as an order confirmation, including the order details.
var confirmationCardResponse = 'Your order has been placed.\n' +
'Products: 1 Starter Kit \n' +
'Total amount: $9.00\n' +
'Thanks for shaving with No Nicks\n' +
'www.nonicks.com'
return handlerInput.responseBuilder
.speak( config.confirmationIntentResponse )
.withStandardCard( 'Order Confirmation Details',
confirmationCardResponse, config.logoURL )
.withShouldEndSession( true )
.getResponse( );
With just a few simple steps, you’re able to take payments for real-world products or services in an Alexa skill.
Get started today with integrating Amazon Pay into your Alexa skill and join the growing list of voice-first merchants. We can’t wait to see what you build!
