Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

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.

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

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

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 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 EUR (euros), GBP (pounds), JPY (yen), or USD (dollars).

Type: string

sellerBillingAgreementAttributes

Optional

Provides more context about the billing agreement that is represented by this Billing Agreement object.

Type: SellerBillingAgreementAttributes

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|AAAAAABBBBBBCCCCCC"
      },
      "device": {},
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
    }
  },
  "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

Optional

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://payapi.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

InvalidSandboxEmail

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": "invalid_token",
    "errorMessage": "The access token provided is expired, revoked, malformed, or invalid for other reasons.",
    "requestId": "bef0c2f8-e292-4l96-8c95-8833fbd559df"
}