Copy of PPRO failure codes

In the Errors representation section, we introduced the failure object and its key fields: failureType, failureCode, providerFailureCode, failureMessage and isRetryable. These fields are returned when a request is valid and successfully processed by the API, but an error or decline occurs later in the flow, causing the operation to fail.

This page provides an overview of all PPRO failureCode values and guidance on how to interpret and handle them during your integration.

INTERNAL_DECLINE

FailureCode	Description	Recommended steps
`AGREEMENT_INACTIVE`	Payment Agreement not yet active or failed during setup.	Ensure the Agreement status is `ACTIVE` before creating payments. Handle activation webhooks properly.
`AGREEMENT_REVOKED`	Payment Agreement revoked by the consumer or merchant.	Verify Agreement status before reuse. Stop future payments under revoked agreements.
`AMOUNT_NOT_SUPPORTED`	Amount value is invalid or outside supported range.	Use a valid `amount.value` within the payment methods min/max limits.
`BLOCKED_ACCOUNT`	Account or card blocked by PPRO due to suspected fraud or abuse.	Ask the consumer to select a different payment method.
`BLOCKED_BIN`	BIN (first 6–8 digits) blocked by PPRO due to high risk or chargebacks.	Ask the consumer to select a different payment method.
`BLOCKED_EMAIL`	Consumer email blocked by PPRO due to suspected fraud or abuse.	Verify the consumer’s identity before allowing further payment attempts, and ask them to use a different verified email address or payment method.

failureCode	Description	Recommended Steps
`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_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.
`NO_AUTHORIZED_AMOUNT`	The Capture or Void operation failed because no successful Authorization has been completed, and the payment charge has not reached the `CAPTURE_PENDING` state.	Wait for an `AUTHORIZATION_SUCCEEDED` webhook before attempting capture or void. The webhook provides the current status of the payment charge: • If the status is `CAPTURED`, the charge has already been captured automatically. • If the status is `CAPTURE_PENDING`, you can safely submit a capture or void request.
`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)
`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.
`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.

`INTERNAL_ERROR`

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_DECLINE`

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_ERROR`

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.