Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

Payment Declines and Processing Errors

In this section

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 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 as a result 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. 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. Ttry 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.
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 user request. To prevent a poor user experience, we recommend that you add retry logic in this case. 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. To prevent a poor user experience, we recommend that you add retry logic in this case.

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

(US and EU only)

MISSING_PERMISSIONS_TO_ACCESS_RESOURCE None No corrective action needed. Amazon Pay will automatically send permission cards to the user'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 user hasn't 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 in Ask customers to turn on Amazon Pay permissions in your skill.
Runtime error
403
ACCESS_DENIED Access to this resource has been denied. 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 in Ask customers to turn on Amazon Pay permissions in your skill.

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

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, permissions cards need to be sent to the customer's Alexa app:

  • In the EU and US, Amazon Pay automatically sends the permission cards so you don't need to manage this.
  • In JP, you need to send permission cards manually.

You can proactively request permissions early in your skill before setup or charge. If you have implemented Buyer ID, 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 as soon as a customer enters a charge flow or at the time of skill launch if your skill only offers charge scenarios.


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 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 user 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 user's account is not valid, so 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 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 user, 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 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. 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 or currency, and then try again.
Runtime error
400
PeriodicAmountExceeded Amazon imposes a $500 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 user request. To prevent a poor user experience, we recommend that you add retry logic in this case. 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. To prevent a poor user experience, we recommend that you add retry logic in this case.

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 Settings in {active user}'s Alexa App and turn on Voice Purchasing in Alexa Account. 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.

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

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 are not 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 codes
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 Openstate 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"
}