Amazon Pay for Alexa API Reference

Note: Sign in to the developer console to build or publish your skill.

Warning: Amazon Pay for Alexa Skills is deprecated.

The Amazon Pay Alexa payments functionality you are using through your Alexa skill will be disabled on the following dates: December 31, 2022 in the EU and the UK, January 31, 2023 in Japan, and March 12, 2023 in the US.

For more details, see Deprecated Features.

Setup

This method returns the billing agreement ID. Call this operation to set up a billing agreement for a customer. A valid billing agreement can be used for:

Purchases or payments at any time
Getting customer details
Situations when a checkout amount is not yet known
Recurring payments or subscriptions

Request parameter	Description and type
@type Required	Constant value: SetupAmazonPayRequest Type: string
@version Required	Constant value: 2 Type: string
countryOfEstablishment Required	The country/region in which the merchant has registered as a legal entity when the Amazon Pay account was opened. Allowed values: AT BE CH CY DE DK ES FR HU IE IT JP LU NL PT SE UK US Type: string
ledgerCurrency Required	The currency of the merchant's ledger account, which needs to match the regional currency where the merchant account is registered. Allowed values: EUR GBP JPY (only in Japan) USD Type: string
sellerId Required	The seller ID (also known as merchant ID). Note: If you are an ecommerce provider (solution provider), specify the ID of the merchant, not your provider ID. Type: string
checkoutLanguage Optional	The merchant's preferred language for checkout. Allowed values: de_DE en_GB en_US es_ES fr_FR it_IT ja_JP Type: string
billingAgreementAttributes Optional	The merchant can choose to set the attributes specified in the BillingAgreementAttributes table. For details, see the BillingAgreementAttributes section below. Type: BillingAgreementAttributes
needAmazonShippingAddress Optional	To receive the preferred customer shipping address in the response, set this parameter to true. Not required if a customer shipping address is not required. Type: boolean
sandboxMode Optional	To test in Sandbox mode, set this parameter to true. Default value: false. Type: boolean
sandboxCustomerEmailId Optional	Use this parameter to create a Sandbox payment contract. To use this parameter, first create a Sandbox user account in Seller Central, and then pass the email address associated with that Sandbox user account. Type: string

BillingAgreementAttributes

Request parameter	Description and type
@type Required	Constant value: BillingAgreementAttributes Type: string
@version Required	Constant value: 2 Type: string
billingAgreementType Optional (for use in the EU and UK only)	The intended use of this BillingAgreement. For charge-now use cases, use CustomerInitiatedTransaction. For charge-later use cases, like subscriptions, use MerchantInitiatedTransaction. Allowed values: CustomerInitiatedTransaction MerchantInitiatedTransaction Default value: CustomerInitiatedTransaction Type: enum
subscriptionAmount Optional (for use in the EU and UK only)	The amount charged for the subscription in fixed intervals. Only valid in combination with a billingAgreementType of MerchantInitiatedTransaction. Only specify the subscriptionAmount if it's already known. Type: price Minimum value: 0.01 Maximum value: 150,000.00
sellerBillingAgreementAttributes Optional	Provides more context about the billing agreement that is represented by this Billing Agreement object. Type: SellerBillingAgreementAttributes

SellerBillingAgreementAttributes

Request parameter	Description and type
@type Required	Constant value: SellerBillingAgreementAttributes Type: string
@version Required	Constant value: 2 Type: string
sellerBillingAgreementId Optional	The merchant-specified identifier of this billing agreement. At least one request parameter must be specified. Amazon recommends that you use only the following characters: lowercase (a-z) uppercase (A-Z) numbers (0-9) dash (-) underscore (_) Type: string
storeName Optional	The identifier of the store from which the order was placed. This parameter overrides the default value in Seller Central under Settings > Account Settings. It is shown to the buyer in their emails and transaction history on the Amazon Pay website. Type: string
customInformation Optional	Any additional information that you want to include with this billing agreement. At least one request parameter must be specified. Type: string

Sample payload

{
    "@type":"SetupAmazonPayRequest",
    "@version":"2",
    "sellerId": "A00776781C_EXAMPLE_ID",
    "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":true,
    "sandboxMode":true,
    "sandboxCustomerEmailId":"testuseraccount@amazon.com"
}

Response elements

Element name	Description
billingAgreementDetails	For details, see the BillingAgreementDetails section of the Amazon Pay API reference guide: DE JP UK US

Sample response payload

{
    "billingAgreementDetails":{ 
        "billingAgreementId":"C01-0000002-0000003",
        "creationTimestamp":"2018-03-24T00:31:57.352Z",
        "destination":{ 
            "addressLine1":"1234 Main Street",
            "city":"CUPERTINO",
            "countryCode":"US",
            "name":"Jane Doe",
            "phone":"1111122222",
            "postalCode":"90000",
            "stateOrRegion":"CA"
        },
        "billingAddress":{ 
            "addressLine1":"1234 Main Street",
            "city":"Seattle",
            "countryCode":"US",
            "name":"Jane Doe",
            "phone":"1111122222",
            "postalCode":"98104",
            "stateOrRegion":"WA" 
        },
        "checkoutLanguage":"en_US",
        "billingAgreementStatus":"OPEN",
        "releaseEnvironment":"SANDBOX"
    } 
}

Charge

This operation triggers Alexa to confirm the purchase amount and send a confirmation card to the customer. This operation can be used when the purchase amount is known and the user is present and interacting with the skill in real time.

Request parameter	Description and type
@type Required	Constant value: ChargeAmazonPayRequest Type: string
@version Required	Constant value: 2 Type: string
billingAgreementId Required	The billing agreement created for the customer (can be a Sandbox ID for testing). Type: string
paymentAction Required	Use the applicable payment action: AUTHORIZE — you want to confirm the order and authorize a certain amount, but you don't want to capture at this time. AUTHORIZEANDCAPTURE — you want to confirm the order, authorize for the given amount, and capture the funds. Type: enum
sellerId Required	The seller ID (also known as merchant ID). Note: If you are an ecommerce provider (solution provider), specify the ID of the merchant, not your provider ID. Type: string
authorizeAttributes Required	Set the attributes specified in the AuthorizeAttributes table. For details, see the AuthorizationDetails section of the Amazon Pay API reference guide: DE JP UK US Type: authorizeAttributes
sellerOrderAttributes Optional	Includes elements shown to buyers in emails and in their transaction history. For details, see the SellerOrderAttributes section of the Amazon Pay API reference guide: DE JP UK US Type: sellerOrderAttributes

Sample payload

{
    "@type":"ChargeAmazonPayRequest",
    "@version":"2",
    "sellerId":"A00776781C_EXAMPLE_ID",
    "billingAgreementId":"C01-5918790-0000000",
    "paymentAction":"AUTHORIZEANDCAPTURE",
    "authorizeAttributes":{
        "@type":"AuthorizeAttributes",
        "@version":"2",
        "authorizationReferenceId":"fv01gtgpu8cam7p4s0000000",
        "authorizationAmount":{
            "@type":"Price",
            "@version":"2",
            "amount":"10.99",
            "currencyCode":"USD"
        },
        "transactionTimeout":0,
        "sellerAuthorizationNote":"Test Seller Authorization Note"
    },
    "sellerOrderAttributes":{
        "@type":"SellerOrderAttributes",
        "@version":"2",
        "sellerOrderId":"",
        "storeName":"TestStoreName",
        "customInformation":"Test Custom Information",
        "sellerNote":"Test Seller Note"
    }
}

AuthorizeAttributes

Represents the amount that you want to authorize against the customer as well as some helpful information for the authorize operation.

Request parameter	Description and type
@type Required	Constant value: AuthorizeAttributes Type: string
@version Required	Constant value: 2 Type: string
authorizationReferenceId Required	Your identifier for this authorization transaction. This identifier must be unique for all of your authorization transactions. Use only the following characters: lowercase a-z uppercase A-Z numbers 0-9 dash (-) underscore (_) Maximum value: 32 characters Type: string
authorizationAmount Required	The amount to be authorized. Minimum value: 0.01 Maximum value: 150,000.00 Type: price
sellerAuthorizationNote Optional	A description of the transaction that is included in emails to the customer. Appears only when CaptureNow is set to true. Maximum value: 255 characters Type: string
softDescriptor Optional	The description to be shown on the customer's payment instrument statement if CaptureNow is set to true. The soft descriptor sent to the payment processor is: "AMZ<soft descriptor specified here> pay.amazon.com" Default value: "AMZ<SELLER_NAME> pay.amazon.com" Maximum value: 16 characters Type: string
transactionTimeout Optional	The maximum number of minutes allocated for the Authorize operation call to be processed, after which the authorization is automatically declined and you can't capture funds against the authorization. The default value for Alexa transactions is 0. To speed up checkout time for voice users, we recommend that you not change this value. Type: string

SellerOrderAttributes

Provides more context about an order that is represented by an Order Reference object.

Request parameter	Description and type
@type Required	Constant value: SellerOrderAttributes Type: string
@version Required	Constant value: 2 Type: string
sellerOrderId Optional	The merchant-specified identifier of this order. This is shown to the buyer in their emails and transaction history on the Amazon Pay website. Although it is recommended, Amazon does not require this value to be unique. We recommend that you use only the following characters: lowercase a-z uppercase A-Z numbers 0-9 dash (-) underscore (_) Type: string
storeName Optional	The identifier of the store from which the order was placed. This overrides the default value in Seller Central under Settings > Account Settings. It is shown to the buyer in their emails and transaction history on the Amazon Pay website. Type: string
customInformation Optional	Any additional information that you want to include with this order reference. Maximum value: 1024 characters Type: string
sellerNote Optional	Represents a description of the order that is shown in emails to the buyer. Maximum value: 1024 characters Type: string

Price

Request parameter	Description and type
@type Required	Constant value: Price Type: string
@version Required	Constant value: 2 Type: string
amount Required	The currency amount. The number of decimal places must be appropriate for the currency code specified. A period is the only valid decimal separator for the amount value. Minimum: 0.01 Type: string
currencyCode Required	The currency code in ISO 4217 format, such as EUR (euros), GBP (pounds), JPY (yen), or USD (dollars). Type: string

Response elements

Element name	Description
amazonOrderReferenceId	The order reference identifier.
authorizationDetails	For details, see the AuthorizationDetails section of the Amazon Pay API reference guide: DE JP UK US

Sample response payload

{
    "authorizationDetails":{
        "authorizationAmount":{
            "amount":"10.99",
            "currencyCode":"USD"
        },
        "capturedAmount":{
            "amount":"10.99",
            "currencyCode":"USD"
        },
        "softDescriptor":"AMZ*Test Seller",
        "expirationTimestamp":"2018-05-23T07:10:22.522Z",
        "idList":["S01-8245791-0000000-C000000"],
        "softDecline":false,
        "authorizationStatus":{
            "lastUpdateTimestamp":"2018-04-23T07:10:22.522Z",
            "reasonCode":"MaxCapturesProcessed",
            "state":"Closed"
        },
        "authorizationFee":{
            "amount":"0.00",
            "currencyCode":"USD"
        },
        "captureNow":true,
        "sellerAuthorizationNote":"TestSellerAuthorizationNote",
        "creationTimestamp":"2018-04-23T07:10:22.522Z",
        "amazonAuthorizationId":"S01-8245791-0000000-A000000",
        "authorizationReferenceId":"fv01gtgpu8cam7p4s30000000"
    },
    "amazonOrderReferenceId":"S01-8245791-0000000"
} 

Buyer ID

How to use buyer ID

When a customer enables your skill, the skill needs to obtain Amazon Pay permission consent from the customer to get their Amazon Pay buyer ID.

Each request sent to your skill includes an API access token (apiAccessToken) that encapsulates the permissions granted to your skill. You need to retrieve this token and include it in the HTTP authorization header of the request for getting the Amazon Pay buyer ID.

The apiAccessToken is nested in the System object, which is nested in the Context object. To see the full body of the request, refer to Request Format.

{
  "version": "1.0",
  "session": {},
  "context": {
    "AudioPlayer": {
      "playerActivity": "IDLE"
    },
    "Display": {},
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.1111111-2222-3333-4444-5555555"
      },
      "user": {
        "userId": "amzn1.ask.account.XXXXXXXXXX",
        "accessToken": "Atza|<accessToken>"
      },
      "device": {},
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "<aipToken>"
    }
  },
  "request": {}
}

This example shows how you access the apiAccessToken in your request handler. This sample code uses the Alexa Skills Kit SDK for Node.js (v2).

const thirdPartySkillIntentHandler = {
    //...
    handle(handlerInput){
     
        var apiAccessToken = handlerInput.requestEnvelope.context.System.apiAccessToken;
        // ...
    }
};

When making the request for getting Amazon Pay buyer ID, include the access token in an Authorization header in this format:

Bearer < ACCESS_TOKEN >

where < ACCESS_TOKEN > is the value of the apiAccessToken field from the Alexa request message, as shown in this example:

Authorization: Bearer AxThk...

API reference

You can call the HTTP GET request with endpoint, path, and authentication header as specified below. To fetch the buyer id on server side securely, send the access token from your client to your server using HTTPS, and then from server side, call the buyer id endpoint using that access token.

Region	Endpoint
NA	pay-api.amazon.com
EU and UK	pay-api.amazon.eu
JP	pay-api.amazon.jp

Path: /live/v1/buyer/id

Request headers

Header	Description and type
Authorization Required	A current access token in the format: `Bearer <your access token>` Type: string

Sample requests and responses

Sample request message

Host: pay-api.amazon.com
Accept: application/json
Authorization: Bearer AxThk... 
GET https://pay-api.amazon.com/live/v1/buyer/id

Successful response message example

HTTP/1.1 200 OK
Host: pay-api.amazon.com
Content-Type: application/json
{
    "buyerId" : "amznl.account.K2LI23KL2LK2"
}

Successful response headers

Header	Description
Content-Type	application/json

Successful response parameters

Parameter	Description and type
buyerId	Persistent ID specific to a customer and merchant Type: string

Buyer address

How to use buyer address

The Buyer Address API returns the buyer's default shipping address. You can call this API anytime in your skill.

We recommend that you call this API before you call Setup or Charge if you want to use the shipping address to:

Determine if you can deliver to their address
Calculate shipping and taxes to include in the order total

API reference

You can call the HTTP GET request with endpoint, path, and authentication header as specified below. To fetch the buyer address on server side securely, send the access token from your client to your server using HTTPS, and then from server side, call the buyer address endpoint using that access token.

Region	Endpoint
NA	pay-api.amazon.com
EU and UK	pay-api.amazon.eu
JP	pay-api.amazon.jp

Path

Live - /live/v1/buyer/addresses
Sandbox - /sandbox/v1/buyer/addresses

Request headers

Live

Header	Description and type
Authorization Required	A current access token in the format: `Bearer <your access token>` Type: string

Sandbox

Header	Description and type
Authorization Required	A current access token in the format: `Bearer <your access token>` Type: string
x-amz-pay-sandbox-email-id Required	Email address for the Sandbox user account: Type: string

Request query parameters

Header	Description and type
sellerId Required	Your seller ID Type: string

Sample requests and responses

Sample request message

Host: pay-api.amazon.com
Accept: application/json
Authorization: Bearer AxThk... 
GET https://pay-api.amazon.com/live/v1/buyer/addresses?sellerId=ABC

Successful response message example

{
    "addresses": [
        {
            "address": {
                "addressLine1": "83034 Terry Ave",
                "city": "Seattle",
                "countryCode": "US",
                "name": "Jack Smith",
                "phone": "800-000-0000",
                "postalCode": "98121",
                "stateOrRegion": "WA"
            },
            "addressType": "DefaultOneClickShippingAddress"
        }
    ]
}

Error codes

Status	Error code	Description
403	Forbidden	The specified merchant account isn't allowed for this request.
400	InvalidRequest	The request is missing a required parameter or is otherwise malformed.
400	InvalidToken	The access token provided is expired, revoked, malformed, or invalid for other reasons.
401	InsufficientScope	The access token provided doesn't have access to the required scope.
500	ServerError	The server encountered a runtime error.
400	InvalidSandboxCustomerEmail	The sandbox email provided is invalid or doesn't belong to the merchant.

In addition to the error code, you receive a JSON payload with more information. This example shows a sample error response.

HTTP/1.1 400 Bad Request
Content-Type: application/json;
{
    "errorCode": "InvalidToken",
    "errorMessage": "The access token provided is expired, revoked, malformed, or invalid for other reasons.",
    "requestId": "bef0c2f8-e292-4l96-8c95-8833fbd559df"
}

Delivery notifications

The Amazon Pay Delivery Tracker API lets you provide shipment tracking information to Amazon Pay so that Amazon Pay can notify buyers on Alexa when shipments are scheduled for delivery and when they're delivered. This API is channel-agnostic. That means that anywhere you use Amazon Pay, you can use the Delivery Tracker API.

Here's what your customer will experience

Customer: Alexa, read my notifications.

Alexa: One new notification, from Amazon Pay. A shipment from [yourstorename] is scheduled to arrive by [date].

Alexa: One new notification, from Amazon Pay. Your shipment from [yourstorename] has been delivered.

To use the Delivery Tracker API, see Setting up delivery notifications in the Amazon Pay automatic payments integration guide.

Last updated: Mar 22, 2023