Payment Declines and Processing Errors

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.

Alexa errors

The status attribute in the Connections.Response captures the return status. It is an object with an HTTP status code and a message.

Here is a sample response for returned errors:

{
  "type":"Connections.Response",
  "status":{
    "code":"403",
    "message":"UnsupportedClientPlatform"
  },
  "name":"Charge",
  "payload": object,
  "token":"TestToken"
}

Amazon Pay for Alexa Skills errors

Setup errors

The following table lists Setup errors that are handled by Amazon Pay.

Error type and status code	Error code	User voice prompt	Error message and corrective action
Runtime error 403	UnsupportedClientPlatform	Sorry. Something went wrong.	The Alexa device of the user is not supported. To proceed, the customer needs to update the device software and restart the request.
Runtime error 400	InvalidShippingAddress	There is a problem with the shipping address on your account. Please go to Amazon and update your shipping address.	The shipping address specified in the customer's account is not valid, and as a result the billing agreement couldn't be set up. The customer needs to update shipping address settings in their account, and then try again.
Runtime error 403	InvalidAccountStatus	Sorry, I can't place orders with [merchantName] right now.	Your merchant account is not in an appropriate state to fulfill this request. For example, this error occurs when a merchant account has been suspended or when registration is not complete. For help resolving the problem, contact Merchant Support.
Runtime error 429	RequestThrottled	Sorry, something went wrong. Please try again.	Your request has been rejected because the request rate is higher than the allocated throttling limits for this service. Try again later.

The following table lists Setup errors that are handled by the merchant. These errors should be resolved during your integration with Amazon Pay.

Error type and status code	Error code	Error message and corrective action
Integration error 400	InvalidSellerId	The seller ID is not valid. Specify a valid seller ID (also referred to as merchant ID) in the sellerId field. You can find your seller ID in Seller Central on the Integration > MWS Access Key > General Information page.
Integration error 400	UnsupportedCurrency	The ledger currency that you provided is not supported. Specify a valid currency in the ledgerCurrencyCode field. Use a currency code in ISO 4217 format (for example, USD for U.S. dollars, EUR for euros, or GBP for pounds).
Integration error 400	UnsupportedCountryOfEstablishment	The country of establishment that you provided is not supported. Specify a valid country in the countryOfEstablishment field. Use a country code in ISO 3166-2 format. The country you enter should be the same country you chose when you registered for Amazon Pay.
Integration error 400	InvalidParameterValue	`<number>` parameter validation error has been detected; the value `<'value specified'>` at `<parameter name>` failed to satisfy constraint: `<constraint details>`. One or more parameters needed to parse the request are missing or otherwise incorrect. Correct the error (as indicated in the error message), and then try again.
Integration error 400	BuyerEqualsSeller	You can't use the specified account for this transaction. The account that you used for testing the user flow is your merchant account. When testing user flow, you must use a different account. Create a user test account, and then try again.
Integration error 403	UnauthorizedAccess	The specified merchant account is not authorized for this request.
Runtime error 400	InvalidBillingAgreementType	The type of the BillingAgreement specified is not valid. Valid values are: CustomerInitiatedTransaction MerchantInitiatedTransaction Choose the value that matches your payment use case.
Runtime error 400	InvalidSubscriptionAmount	The subscription amount or currency specified is not valid. Specify a valid subscription amount and currency, and then try again.
Integration error 403	ReleaseEnvironmentNotAllowed	Sandbox requests are only allowed in the Development stage. Use the Development version of your skill to make Sandbox requests.
Sandbox mode error 400	InvalidSandboxCustomerEmail	The SandboxCustomerEmailId parameter value is not valid. There is no Sandbox user associated with the SandboxCustomerEmailId that was provided. Use the email address that you specified in the test account that you created in Seller Central, on the Integration > Test Accounts page.
Runtime error 500	InternalServerError	There was an internal server error. The error prevented the service from responding properly to the customer request. To prevent a poor customer experience, we recommend that you add retry logic in this case. Otherwise, the customer will need to try again. Note: This can be caused by missing privacy policy URLs on your skill. Please ensure privacy policy URLs are set for all supported languages.
Runtime error 500	ServiceUnavailable	The service is temporarily unavailable. This prevents the service from responding properly to the customer request. To prevent a poor customer experience, we recommend that you add retry logic in this case.
Runtime error 400	MissingSkillManifestData	Essential data to perform the `Setup` operation is missing. Please ensure privacy policy URLs are set for all languages supported by your skill.

Permissions errors

The following table lists Permission errors, all of which are handled by the merchant.

Error type and status code	Error code	Merchant-facing error message	Corrective action
Integration error 403	MissingPermissionsToAccessResource	None	No corrective action needed. Amazon Pay will automatically send permission cards to the customer's Alexa app to request permissions for both Voice Purchasing and Amazon Pay.
Integration error 403	FORBIDDEN	Access to this resource cannot be requested.	The merchant's skill doesn't declare the permission being requested. To resolve the error, request Amazon Pay permission for the skill on developer portal.
Runtime error 403	ACCESS_NOT_REQUESTED	Access to this resource has not yet been requested.	The customer hasn't been shown the manage consent page. You can either rely on Alexa handling this for you by calling the `Setup` operation or manually handle missing Amazon Pay permissions or Voice Purchase settings.
Runtime error 403	ACCESS_DENIED	Access to this resource has been denied.	The customer hasn't been shown the manage consent page. You can either rely on Alexa handling this for you by calling the `Setup` operation or manually handle missing Amazon Pay permissions or Voice Purchase settings.

Sample response from Amazon Pay:

{
  "type":"Connections.Response",
  "status":{
    "code":"403",
    "message":"InvalidAccountStatus"
  },
  "name":"Charge",
  "payload": {
    "errorCode": "InvalidAccountStatus",
    "errorMessage": "Merchant account is not in an appropriate state to fulfill this request" 
  } 
}

Ask customers to turn on Amazon Pay permissions in your skill

If your customer hasn't turned on Voice Purchasing or Amazon Pay permissions in your skill, this can lead to errors sent to your backend logic. You can proactively request permissions early in your skill before setup or charge or let Alexa handle this for you by calling the Setup operation, regardless if permissions are granted yet.

If you have implemented Buyer ID or Buyer Address, we recommend that you proactively check for permissions. The code sample below shows how to direct your customer to turn on the Amazon Pay permissions. Use this information to handle permissions errors and to request permissions via cards sent to the buyer's Alexa app when needed.

function handleErrors(statusCode, handlerInput ) {
  let errorCode = handlerInput.requestEnvelope.request.payload.errorCode;
  let errorMessage = handlerInput.requestEnvelope.request.payload.errorMessage;

  switch ( errorCode ) {
    case "ACCESS_NOT_REQUESTED":
      return handlerInput.responseBuilder
                .speak('Please enable permission for Amazon Pay in your companion app.)
                .withAskForPermissionsConsentCard([ 'payments:autopay_consent' ])
                .getResponse();
      break;
    default:
      return handlerInput.responseBuilder
            .speak("Error Occured. Error status code " + statusCode + ". Error payload message " + errorMessage  + ".")
            .getResponse();
  }
}

Charge errors

The following table lists Charge errors that Amazon Pay handles.

Error type and status code	Error code	User voice prompt	Error message and corrective action
Runtime error 403	UnsupportedClientPlatform	Sorry. Something went wrong.	The Alexa device of the customer is not supported. To proceed, the customer needs to update the device software and restart the request.
Runtime error 400	InvalidPaymentMethod	There's a problem with the payment method on your account. Please go to Amazon and update your payment method.	The payment method specified in the customer's account is not valid, so the payment could not be processed. The customer needs to update payment method settings in their account, and then try again.
Runtime error 403	InvalidAccountStatus	Sorry. Orders can't be placed with {merchant name} right now.	Your merchant account is not in an appropriate state for this request. For example, this error occurs when a merchant account has been suspended or when registration is not complete. For help resolving this problem, contact Merchant Support.
Runtime error 429	RequestThrottled	Sorry. Something went wrong. Please try again later.	Your request has been rejected because the request rate is higher than the allocated throttling limits for this service. Try again later.

The following table lists Charge errors that are handled by the merchant. These errors should be resolved during your integration with Amazon Pay.

Error type and status code	Error code	Error message and corrective action
Integration error 400	InvalidSellerId	The seller ID is not valid. Specify a valid seller ID (also referred to as a merchant ID) in the sellerId field. You can find your seller ID in Seller Central on the Integration > MWS Access Key > General Information page.
Integration error 400	InvalidParameterValue	`<number>` parameter validation error has been detected; the value `<'value specified'>` at `<parameter name>` failed to satisfy constraint: `<constraint details>`. One or more parameters needed to parse the request are missing or otherwise incorrect. Correct the error (as indicated in the error message), and then try again.
Integration error 403	UnauthorizedAccess	The specified merchant account is not authorized for this request.
Integration error 403	ReleaseEnvironmentNotAllowed	Sandbox requests are only allowed in the Development stage. Use the Development version of your skill to make Sandbox requests.
Runtime error 400	InvalidBillingAgreementId	The billing agreement ID that you submitted in this request is not valid. Specify a valid ID. To get a valid ID for the customer, you can call the Setup API again.
Runtime error 400	InvalidBillingAgreementStatus	You have attempted an operation on a billing agreement object that is in a state where the operation is not allowed. The customer must go to Amazon to update or enter a valid payment method to bring the billing agreement state back to `Open` before you can charge them. If the billing agreement is not `Open`, you might not receive the customer's address.
Runtime error 400	InvalidPaymentAction	The payment action specified is not valid. Valid payment actions are: Authorize AuthorizeAndCapture
Runtime error 400	InvalidAuthorizationAmount	The authorization amount or currency specified is not valid. Specify a valid authorization amount and currency, and then try again.
Runtime error 400	PeriodicAmountExceeded	Amazon imposes a $1,000 limit per calendar month on the amount of funds you can charge a buyer. If you expect to exceed this limit because of an upgrade or the customer's usage, contact Amazon Pay.
Runtime error 403	ProviderNotAuthorized	The provider ID specified is not authorized to participate in this transaction.
Runtime error 400	DuplicateRequest	A request with the specified AuthorizationReferenceId has already been processed with different parameters.
Runtime error 500	InternalServerError	There was an internal server error. The error prevented the service from responding properly to the customer request. To prevent a poor customer experience, we recommend that you add retry logic in this case. Otherwise, the customer needs to try again.
Runtime error 500	ServiceUnavailable	The service is temporarily unavailable, preventing the service from responding properly to the customer request. To prevent a poor customer experience, we recommend that you add retry logic in this case.

Authentication errors

The following table lists authentication errors, all of which Amazon Pay handles, but you can augment the Amazon and Amazon Pay prompts with the merchant skill additions noted. The errors can be a response of a Charge or Setup operation, depending on the BillingAgreementType specified.

Error type and status code	Error code	User voice prompt	Error message and corrective action
Runtime error 401	PaymentAuthenticationFailure	Alexa: Sorry, there was a problem verifying your payment. Merchant skill: Your order has been saved. If you want to complete your purchase later, just say "open [app or website]". [Items] are also available at [URL].	The customer failed to complete the payment authentication challenge, and the payment couldn't be processed. If you can save the order, tell the customer that their order is saved, and encourage them to reopen the skill later to complete the purchase. Or direct users to another location to complete the purchase.
Runtime error 401	PaymentAuthenticationAbandoned	Alexa: Sorry. Your payment can't be completed without verification. Merchant skill: Your order has been saved. If you want to complete your purchase later, just say "Open [skill name]". [Items] are also available at [URL].	The customer abandoned the payment authentication challenge, and the payment couldn't be processed. If you can save the order, tell the customer that their order is saved, and encourage them to reopen the skill later to complete the purchase. Or direct users to another location to complete the purchase.
Runtime error 501	PaymentAuthenticationNotSupported	Alexa: There was a problem verifying payment with your bank. Your payment can't be completed. Merchant skill: You can purchase [items] at [URL].	The provided payment authentication challenge is not supported via Alexa. Direct users to check out at another location, like website or app if available.

Error type and status code

Error code

User voice prompt

Error message and corrective action

Runtime error
401

PaymentAuthenticationFailure

Alexa: Sorry, there was a problem verifying your payment.

Merchant skill: Your order has been saved. If you want to complete your purchase later, just say "open [app or website]". [Items] are also available at [URL].

The customer failed to complete the payment authentication challenge, and the payment couldn't be processed.

If you can save the order, tell the customer that their order is saved, and encourage them to reopen the skill later to complete the purchase. Or direct users to another location to complete the purchase.

Runtime error
401

PaymentAuthenticationAbandoned

Alexa: Sorry. Your payment can't be completed without verification.

Merchant skill: Your order has been saved. If you want to complete your purchase later, just say "Open [skill name]". [Items] are also available at [URL].

The customer abandoned the payment authentication challenge, and the payment couldn't be processed.

Runtime error
501

PaymentAuthenticationNotSupported

Alexa: There was a problem verifying payment with your bank. Your payment can't be completed.

Merchant skill: You can purchase [items] at [URL].

The provided payment authentication challenge is not supported via Alexa. Direct users to check out at another location, like website or app if available.

PIN errors

The following table lists PIN errors, all of which are handled by Amazon Pay.

Error type and status code	Error code	User voice prompt	Error message and corrective action
Runtime error 403	CustomerApprovalFailure	Sorry, I am still having trouble. Visit {active user}'s Alexa app to view or reset the voice code for Voice Purchasing.	The customer didn't provide a voice PIN to verify their approval. Your skill should ask the customer to try again.
Runtime error 403	VoicePurchaseNotEnabled	To continue, first go to Settings in {active user}'s Alexa App and turn on Voice Purchasing in Alexa Account.	The customer hasn't enabled the voice purchasing feature. There is no action needed from the merchant. An Alexa prompt informs the customer of the action needed.

Amazon Pay server API errors

See the Amazon Pay API specs for payment error codes.

Decline handling

Amazon Pay uses the customer's default 1-Click settings for payments. If the customer hasn't set their default 1-Click settings, Amazon Pay automatically prompts the customer to correct their settings in their Alexa App.

Error type and status code	Error code	User voice prompt	Error message and corrective action
Runtime error 400	InvalidShippingAddress	To continue, create a default 1-Click setting for ${activeUser}’s Amazon account. To help, I sent a link to your Alexa app.	There are no default 1-click settings in customer's account. Amazon Pay automatically prompts the customer to update their shipping address.
Runtime error 400	InvalidPaymentMethod	Your default 1-Click payment method needs updating. To help, I sent a link to ${activeUser}’s Alexa app. OR Your 1-Click billing address needs updating. To help, I sent a link to ${activeUser}’s Alexa app. OR This organization doesn't accept your default 1-Click payment method. If you want to change your payment method, I sent a link to ${activeUser}’s Alexa app.	There is no valid default payment method in customer's account. Amazon Pay automatically prompts the customer to update their default 1-Click settings.
Runtime error 400	UnsupportedCustomerAccount	To continue, you need to add an email address to ${activeUser}’s account on {AMAZON_URL}, in Login and Security.	There is no email address associated with customer's account. Amazon Pay automatically prompts the customer to update their email address.

Error type and status code

Error code

User voice prompt

Error message and corrective action

Runtime error
400

InvalidShippingAddress

To continue, create a default 1-Click setting for ${activeUser}’s Amazon account. To help, I sent a link to your Alexa app.

There are no default 1-click settings in customer's account. Amazon Pay automatically prompts the customer to update their shipping address.

Runtime error
400

InvalidPaymentMethod

Your default 1-Click payment method needs updating. To help, I sent a link to ${activeUser}’s Alexa app.

Your 1-Click billing address needs updating. To help, I sent a link to ${activeUser}’s Alexa app.

This organization doesn't accept your default 1-Click payment method. If you want to change your payment method, I sent a link to ${activeUser}’s Alexa app.

There is no valid default payment method in customer's account. Amazon Pay automatically prompts the customer to update their default 1-Click settings.

Runtime error
400

UnsupportedCustomerAccount

To continue, you need to add an email address to ${activeUser}’s account on {AMAZON_URL}, in Login and Security.

There is no email address associated with customer's account.
Amazon Pay automatically prompts the customer to update their email address.

If your customers ask how they can update their default 1-Click settings, direct them to Amazon.com’s instructions here: Change your 1-Click Settings The following table lists codes, voice prompts, and corrective actions for declines. Strictly speaking, declines aren't errors, but you need to be prepared to handle them properly.

Decline type	Response	User voice prompt
InvalidPaymentMethod	`AuthorizationStatus.state= Declined; AuthorizationStatus.reasonCode= InvalidPaymentMethod;`	Your default 1-Click payment method needs updating. To help, I sent a link to {activeUser}'s Alexa app. Amazon Pay automatically prompts the customer to update their payment method.
TransactionTimedOut	`AuthorizationStatus.state= Declined; AuthorizationStatus.reasonCode= TransactionTimedOut;`	Sorry. Your payment can't be completed right now, but you can try later.
AmazonRejected	`AuthorizationStatus.state= Declined; AuthorizationStatus.reasonCode= AmazonRejected;`	Sorry. Your payment can't be completed right now, but you can try later.
ProcessingFailure	`AuthorizationStatus.state= Declined; AuthorizationStatus.reasonCode= ProcessingFailure;`	Sorry. Your payment can't be completed right now, but you can try later.

Billing Agreement states

The following table lists the Billing Agreement states and reason codes.

State	Description	Reason code
Open	Billing Agreement object is valid and the Charge API can be called without constraints.	Not applicable
Suspended	A Billing Agreement object moves to the `Suspended` state when problems with the payment method are preventing Amazon from processing the authorizations.	InvalidPaymentMethod — There were problems with the payment method. Merchants should call the Charge API, irrespective of the status of the Billing Agreement that they received in Setup API. Status is just an indication of the current status of the Billing Agreement, and the Charge API has the capability to handle any buyer account configuration updates (for example, Payment Instrument updated) and move the Billing Agreement to an `Open` state before charging the buyer.

Buyer ID errors

If there is a problem fulfilling your request, you receive an HTTP error. The error codes for an Amazon Pay buyer ID request include:

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.

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

Last updated: Dec 29, 2022