Amazon Pay for Alexa API Reference

In this section

Setup

This method returns the billing agreement ID. Call this operation to set up a billing agreement for a user. 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.

Type: string

ledgerCurrency

Required

The currency of the merchant's ledger account.

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.

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 user shipping address in the response, set this parameter to true.
Not required if a user 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

platformId

Optional

Represents the SellerId of the solution provider that developed the eCommerce platform.

This value is only used by solution providers, for whom it is required. Merchants who create their own custom integration should not provide it. Do not specify the SellerId of the merchant for this request parameter.

If you are a merchant, do not enter a PlatformId.

Type: string

sellerNote

Optional

Represents a description of the billing agreement that is shown in emails to the buyer.

Maximum: 1024 characters

Type: string

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: US, UK, DE

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 user. 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 user (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), please specify the ID of the merchant, not your provider ID.

Type: string

authorizeAttributes

Required

Set the attributes specified in the AuthorizeAttributes table.

Type: authorizeAttributes

For details, see the AuthorizationDetails section of the Amazon Pay API reference guide: US, UK, DE

sellerOrderAttributes

Optional

Includes elements shown to buyers in emails and in their transaction history.

Type: sellerOrderAttributes

For details, see the SellerOrderAttributes section of the Amazon Pay API reference guide: US, UK, DE

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.
Maximum value:
  • US: $150,000
  • UK: £150,000
  • Germany: €150,000

Type: price

sellerAuthorizationNote

Optional

A description for the transaction that is included in emails to the user. Appears only when CaptureNow is set to true.
Maximum value: 255 characters

Type: string

softDescriptor

Optional

The description to be shown on the user's payment instrument statement if CaptureNow is set to true.
The soft descriptor sent to the payment processor is:
"AMZ* <soft descriptor specified here>"
Default value:
"AMZ*<SELLER_NAME> Amazon Pay"
Maximum: 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: AuthorizeAttributes

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: 1 character

Type: string

currencyCode

Required

The currency code in ISO 4217 format, such as USD (dollars), EUR (euros), or GBP (pounds).

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: US, UK, DE

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"
}