Amazon Pay for Alexa API Reference


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 guideDE  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.

1
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