Payment declines and processing errors

In this section

Alexa errors
Amazon Pay for Alexa Skills errors
Decline handling

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. In order to proceed, the user 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 user's account is not valid, and therefore the billing agreement could not be set up. The user 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 execute this request. For example, this error occurs when a merchant account has been suspended or when registration is not complete. Please contact Merchant Support for assistance in resolving the problem.
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. Please 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. Please 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. Please 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. Please 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 selected 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. Please correct the error (as indicated in the error message), and try again.
Integration error 400	BuyerEqualsSeller	You cannot 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. Please create a user test account, and then try again.
Integration error 403	UnauthorizedAccess	The specified merchant account is not authorized for this request.
Sandbox mode error 400	InvalidSandboxCustomerEmail	The SandboxCustomerEmailId parameter value is not valid. There is no Sandbox user associated with the SandboxCustomerEmailId that was provided. Please 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 user request. We recommend that you add retry logic in this case, to prevent a poor user experience. Otherwise, the user will need to try again.
Runtime error 500	ServiceUnavailable	The service is temporarily unavailable. This prevents the service from responding properly to the user request. We recommend that you add retry logic in this case, to prevent a poor user experience.

Charge errors

The following table lists Charge 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. In order to proceed, the user needs to update the device software and restart the request.
Runtime error 400	InvalidPaymentMethod	There is a problem with the payment method on your account. Please go to Amazon and update your payment method.	The payment method specified in the user's account is not valid. Therefore, the payment could not be processed. The user needs to update payment method settings in their account, and then try again.
Runtime error 403	InvalidAccountStatus	Sorry. Orders cannot 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. Please contact Merchant Support for assistance in resolving the problem.
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. Please 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. Please 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. Please correct the error (as indicated in the error message), and try again.
Integration error 403	UnauthorizedAccess	The specified merchant account is not authorized for this request.
Runtime error 400	InvalidBillingAgreementId	The billing agreement ID that you submitted in this request is not valid. Please specify a valid ID. You can call the Setup API again to get a valid ID for the user.
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 user 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.
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. Please specify a valid authorization amount or currency, and try again.
Runtime error 400	PeriodicAmountExceeded	The billing agreement object that you specified in this request has already been authorized for the specified amount in the specified time period. A new authorization cannot be accepted, because the total authorization amount cannot exceed the specified limit.
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 user request. We recommend that you add retry logic in this case, to prevent a poor user experience. Otherwise, the user will need to try again.
Runtime error 500	ServiceUnavailable	The service is temporarily unavailable, preventing the service from responding properly to the user request. We recommend that you add retry logic in this case, to prevent a poor user experience.

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 user did not provide a voice PIN to verify their approval. Your skill should ask the user to try again.
Runtime error 403	VoicePurchaseNotEnabled	To continue, first go to the Settings tab in {active user}'s Alexa App and turn on Voice Purchasing.	The user has not enabled the voice purchasing feature. There is no action needed from the merchant; an Alexa prompt informs the user of the action needed.

Permissions errors

The following table lists Permissions 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	FORBIDDEN	The authentication token is missing.	Without an authentication token, the merchant's skill cannot declare the permission that is being requested. To resolve the error, get the consentToken from context.System.apiAccessToken and set in Setup/Charge request.
Integration error 403	FORBIDDEN	The authentication token is not valid.	Without a valid authentication token, the merchant's skill cannot declare the permission that is being requested. To resolve the error, get the valid consentToken from context.System.apiAccessToken and set in Setup/Charge request.
Integration error 403	FORBIDDEN	The authentication token has expired.	Without a valid authentication token, the merchant's skill cannot declare the permission that is being requested. To resolve the error, request Amazon Pay permission for the skill on developer portal.
Integration error 403	FORBIDDEN	Access to this resource cannot be requested.	The merchant's skill does not 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 user has not been shown the manage consent page. Your skill should direct the user to the manage consent page. To resolve the error, request a new permissions card by following the instructions on the Alexa Skills Kit website, using the following parameter: 'payments:autopay_consent'.
Runtime error 403	ACCESS_DENIED	Access to this resource has been denied.	The user has seen the manage consent page, but did not grant permissions. To resolve the error, request a new permissions card by following the instructions on the Alexa Skills Kit website, using the following parameter: 'payments:autopay_consent'.

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 execute this request" 
} 
}

Amazon Pay server API errors

See the Amazon Pay API specs for payment error codes.

Decline handling

The following table lists codes, voice prompts, and corrective actions for declines. Strictly speaking, declines are not errors, but like errors, you need to be prepared to handle them properly.

Decline type	Response	User voice prompt
InvalidPayment	AuthorizationStatus.state= Declined; AuthorizationStatus.reasonCode= InvalidPaymentMethod;	There is no valid payment method in your Amazon account. Please go to Amazon and update your payment method.
TransactionTimedOut	AuthorizationStatus.state= Declined; AuthorizationStatus.reasonCode= TransactionTimedOut;	Your payment was unsuccessful. Please go to Amazon and update your payment method.
AmazonRejected	AuthorizationStatus.state= Declined; AuthorizationStatus.reasonCode= AmazonRejected;	Your payment was unsuccessful. Please go to Amazon and update your payment method.
ProcessingFailure	AuthorizationStatus.state= Declined; AuthorizationStatus.reasonCode= ProcessingFailure;	Sorry, something went wrong. Please try again.