Standard failure codes

In our error representation guide, we introduced the failure object and the data fields failureType, failureCode, providerFailureCode and failureMessage. These are used when you make a valid API request, but an error or decline occurs further along in the payment process which causes the operation to fail.

This page will give you an overview of all PPRO-standard failureCode values, and how to handle them when you encounter them during processing.

List of Failure Codes

Internal Declines

failureCode	Description	Recommended Steps
`NO_AUTHORIZED_AMOUNT`	Capture or Void operation failed because you have not completed a successful Authorization yet, and it has not yet reached the `CAPTURE_PENDING` state.	Ensure that you are following all steps necessary to complete an authorization with the payment method in question. Some payment methods require the consumer to go through an extra authentication step before we can authorize the amount. Refer to the guides page for your payment method for help on how to handle the respective`authenticationMethods`, or learn about our authentication method types here. The best way to avoid this error is to wait for an `AUTHORIZATION_SUCCEEDED` webhook from PPRO. It will contain the current status of the payment charge. If the current status is `CAPTURED`, the charge has already been captured automatically. If the status is `CAPTURE_PENDING`, then you can make a capture request without running into this error.
`EXCEEDS_REFUNDABLE_AMOUNT`	The refund operation failed because there are no captures yet, or the allowable amount has already been fully refunded. Refunds can only be processed when in the `CAPTURED` state.	Check that there are successful Capture operations under this payment charge, and that the charge status is not `REFUNDED`.
`EXCEEDS_AUTHORIZED_AMOUNT`	The capture or void amount exceeds the remaining authorized amount.	You've already full captured the charge, so no further capture requests are necessary. Check that your integration is not accidentally triggering a capture multiple times. If you are using partial captures, ensure the charge is still in the `CAPTURE_PENDING` state and that the total amount captured so far + the new capture amount is not exceeding the amount authorized.
`EXCEEDS_CAPTURED_AMOUNT`	The refund amount exceeds the remaining captured amount.	Before you make another refund request, check that the total amount of successful Captures, minus the total amount of any existing successful Refunds, are greater than or equal to the amount you are attempting to refund.
`AMOUNT_NOT_SUPPORTED`	The amount added is not valid	The gateway has minimum and maximum values that are accepted in the `amount.value` field. Fill the field with a valid amount and try again.
`COUNTRY_NOT_SUPPORTED`	The added country is either invalid or not supported	Have the consumer fill in the country value again with a valid one.
`REDUNDANT_CONFIRMATION_ATTEMPT`	We received an unnecessary confirmation call for a payment authorization, either because the payment method has synchronous authorization and does not expect a separate confirmation call, or a duplicate confirmation was received.	Review your integration and our individual payment method docs to ensure you are not attempting to confirm authorizations that should be happening synchronously. Generally, this failure shows up on a duplicate authorization under the payment charge and does not affect the original authorization, so impact is minimal.
`PAYMENT_METHOD_TIMEOUT`	We discarded the payment charge because it was not authorized within the timeout limit for the `paymentMethod` specified.	Return the consumer to the payment selection step of the checkout so they can initiate a new payment. (You can see timeout limits for each payment method by referring to the payment method guides in our docs)
`INVALID_PAYMENT_METHOD`	`paymentMethod` not recognized.	Review the docs for the payment method in question to ensure you are sending the correct `paymentMethod` value listed there.
`INVALID_AUTHENTICATION_SETTINGS`	The `authenticationSettings` details are not valid or missing for the specified `paymentMethod`.	Review the docs for the payment method in question to ensure you are sending the correct `authenticationSettings` type and details.
`INVALID_ACCOUNT`	The specified card or account format is not supported by the payment method.	Review the docs for the payment method in question to ensure it supports the type of account you are trying to pay with.
`INVALID_CURRENCY`	The currency is not supported by the payment method or instrument.	Review the docs for the payment method in question to ensure it supports the currency you are trying to pay with.
`INVALID_TAX_ID`	`consumer.taxIdentification` value is not in a valid format for this payment method.	Review the docs for the payment method in question to ensure you are including a valid tax id format.
`INVALID_IP`	The consumer's IP address is in an invalid format or the chosen payment method / provider does not support payments from this IP address.	Review the docs for the payment method in question to ensure the payment method can be used in the country that the consumer is located, and check the API reference to ensure that the IP address is in a valid format.
`HIGH_ACCOUNT_VELOCITY`	We have detected too many payment attempts from the specified card or account.	Contact your account manager or technical account manager for more information. You can ask the consumer to try a different payment method.
`HIGH_BIN_VELOCITY`	We have detected too many payment attempts from the specified BIN range of the card.	Contact your account manager or technical account manager for more information. You can ask the consumer to try a different payment method.
`HIGH_EMAIL_VELOCITY`	We have detected too many payment attempts with the specified email.	Contact your account manager or technical account manager for more information. You can ask the consumer to try a different payment method.
`HIGH_IP_VELOCITY`	We have detected too many payment attempts from the specified consumer IP address.	Contact your account manager or technical account manager for more information.
`BLOCKED_ACCOUNT`	The card or account has been blocked by PPRO due to suspected fraud or abuse.	Ask the consumer to choose a different payment method.
`BLOCKED_BIN`	The bank identification number has been blocked by PPRO due to suspected fraud or high risk of chargebacks.	Ask the consumer to use a different payment method.
`BLOCKED_EMAIL`	The consumer's email address has been blocked by PPRO due to suspected fraud or abuse.	Ask the consumer to use a different payment method with a different email.
`BLOCKED_IP`	The consumer's IP address has been blocked by PPRO due to suspected fraud or abuse.	Present it to the consumer as a generic error. Contact your account manager or technical account manager for more information.
`AGREEMENT_INACTIVE`	The Payment Agreement failed or has not been properly activated yet. Subsequent payments are not possible.	Check that the Agreement status is `ACTIVE` before creating subsequent payments under it, and make sure you are properly consuming the webhooks we send when an Agreement is activated or fails. Creating a Payment Agreement for certain payment methods involves a consumer auth step where they must agree to the mandate in e.g. their bank's app. Refer to the documentation for your payment method of choice for more details.
`AGREEMENT_REVOKED`	The Payment Agreement was revoked by the consumer, or by you at an earlier time. Subsequent payments are not possible.	Check that the Agreement status is `ACTIVE` before creating subsequent payments under it, and make sure you are properly consuming the webhook we send when an Agreement is revoked.
`INSTRUMENT_NOT_FOUND`	Could not find a payment instrument matching the specified `instrumentId` in the request.	Verify that you are storing instrument ids properly after you create a payment or an instrument. If you have multiple merchants / API accounts with PPRO, check that you are not mixing instrument ids from different merchants / accounts.
`GENERIC_DECLINE`	The payment was declined by our upstream processing system but no failure code was sent back.	Retry the payment. If retry attempts are also unsuccessful, ask the consumer to choose a different payment method.
`EXCEEDS_REFUND_LIMIT`	Reservation would make the balance fall below the minimum funds account balance	Contact PPRO to increase the limit amount

Internal Errors

failureCode	Description	Recommended Steps
`INTERNAL_SERVICE_UNAVAILABLE`	Internal PPRO service is currently unavailable. This failure code covers the scenarios where an internal service goes down, i.e. a production incident, while processing a request that was initially accepted. These errors are very rare.	The request may have produced side effects in our system. For example, a capture may have been triggered with the provider, but a PPRO service goes down before we get the response. In this case, we try to resolve the side effects after the incident has been fixed, and send you webhooks after the fact so you are updated on the proper status of the operation.
`INTERNAL_PROCESSING_ERROR`	An internal service could not process a request for some reason and threw this generic error. These are exceptionally rare.	See above.

Provider Declines

failureCode	Description	Recommended Steps
`AUTHENTICATION_FAILED`	There was an error in authenticating the consumer, e.g. via 3DS.	The consumer should contact their issuer to receive more information and resolve the problem.
`CANCELED_BY_CONSUMER`	The provider has informed us that the consumer intentionally abandoned the authentication flow, for example by clicking 'cancel'.	Return the consumer to the payment method selection step of the checkout so they can initiate a new payment.
`AMOUNT_NOT_SUPPORTED`	The amount value is not supported by the provider.	The payment method used has minimum and maximum values that are accepted in the `amount.value` field. In rare cases, the provider may have changed their maximum/minimum amounts before communicating the changes to PPRO. You may need to bring the consumer back to checkout and use a different payment method to process a payment, especially in high/low amounts.
`COUNTRY_NOT_SUPPORTED`	The country value is not supported by the provider	Have the consumer fill in the country value again with a valid one.
`ACCOUNT_NOT_SUPPORTED`	The consumer's bank account is not available e.g. online payments	Return the consumer to the payment method selection step of the checkout to try again with a new account or payment method.
`INCORRECT_CVV`	The CVC/CVV was wrong.	Have the consumer try again by entering the correct CVC/CVV.
`INCORRECT_NUMBER`	The card or account number cannot be validated by the issuer.	Have the consumer enter their card number again or try a different card.
`INCORRECT_HOLDER_NAME`	The card or account `holderName` could not be validated by the issuer.	Have the consumer enter their card details again or try a different card.
`INCORRECT_ISSUER`	The card number/issuer is not within a card number range supported by the provider.	Have the consumer enter their card number again or try a different card.
`INCORRECT_BILLING_ADDRESS`	The billing address entered was wrong.	Have the consumer enter the billing address again.
`INCORRECT_TAX_ID`	The provider has determined the `consumer.taxIdentification` to be incorrect.	Have the consumer enter their tax identification number again. If you receive this failure code frequently and consistently, check that`consumer.taxIdentification` is being collected in the right format. You can refer to our guide for the payment method in question to help you with this.
`IS_GENERIC_DECLINE`	Generic decline by the issuer.	The consumer should contact their issuer to receive more information and resolve the problem.
`IS_NOT_PERMITTED`	Not permitted by the issuer.	The consumer should contact their issuer to receive more information and resolve the problem.
`IS_EXCEEDING_ACCOUNT_LIMIT`	The amount value exceeds the limit on the consumer's account.	The consumer should contact their issuer to receive more information and resolve the problem.
`IS_HIGH_VELOCITY`	The consumer has exceeded the number of attempts allowed by the issuer.	The consumer should contact their issuer to receive more information and resolve the problem.
`SUS_FRAUD`	The payment was declined because the issuer or provider suspects it was fraudulent.	The consumer should not be informed about the reason for the decline, and should see only a generic error message.
`SUS_LOST`	The payment was declined because the consumer's card was reported lost.	The consumer should not be informed about the reason for the decline, and should see only a generic error message.
`SUS_STOLEN`	The payment was declined because the consumer's card was reported stolen.	The consumer should not be informed about the reason for the decline, and should see only a generic error message.
`INSUFFICIENT_FUNDS`	Insufficient funds in the account.	Ask the consumer to choose a different payment method, card or account.
`EXPIRED_CARD`	Expired card.	Ask the consumer to update/change their card or choose a different payment method.
`DUPLICATE_DETECTED`	Provider detected a very similar request recently with the same card data and amount.	Check and ensure you are not charging/refunding multiple times for the same product.
`PAYMENT_METHOD_TIMEOUT`	The provider failed to respond on time.	Retry the request. If you receive this failure code repeatedly, there may be an incident. PPRO will inform you well if we notice that a provider is facing intermittencies

Provider Errors

failureCode	Description	Recommended Steps
`UNRESPONSIVE_ISSUER`	The issuer cannot be contacted/is unavailable.	Retry the request. If you receive this failure code repeatedly, ask the consumer to contact their issuer to receive more information and resolve the problem.
`UNRESPONSIVE_PROVIDER`	The provider cannot be contacted/is unavailable.	Retry the request. If you receive this failure code repeatedly, there may be an incident / unscheduled maintenance being done by the provider. In general, PPRO will inform you if we detect any provider intermittencies.
`PROVIDER_PROCESSING_ERROR`	The provider could not process the request we sent to them. These errors are very rare.	This could be caused either by a bug on the provider side, or a bug in the way PPRO formats the request to the provider. These errors are very rare and we work to get them fixed as soon as possible when they arise.