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. |
BLOCKED_IP | Consumer IP blocked by PPRO due to suspected fraud or abuse. | Show a generic error and contact PPRO support for details. |
CANCELED_BY_CONSUMER | ||
CHARGEBACK_DETECTED | ||
COUNTRY_NOT_SUPPORTED | Country code invalid or unsupported by the payment method. | Re-submit with a valid countryCode value supported by the payment method. |
INTERNAL_ERROR
| failureCode | Description | Recommended steps |
|---|---|---|
INTERNAL_SERVICE_UNAVAILABLE | A PPRO internal service is temporarily down during request processing. This typically indicates a production incident. | The request may have partially completed (e.g., capture triggered but response not received). After recovery, PPRO resolves any side effects and sends webhooks with the final status. |
INTERNAL_PROCESSING_ERROR | A PPRO internal service encountered an unexpected error while handling the request. These are extremely rare. | The request may have partially completed (e.g., capture triggered but response not received). After recovery, PPRO resolves any side effects and sends webhooks with the final status. |
PROVIDER_DECLINE
| failureCode | Description | Recommended steps |
|---|---|---|
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| EXPIRED_CARD | Expired card. | Ask the consumer to update/change their card or choose a different payment method. |
| INCORRECT_BILLING_ADDRESS | The billing address entered was wrong. | Have the consumer enter the billing address again. |
| INCORRECT_CVV | The CVC/CVV was wrong. | Have the consumer try again by entering the correct CVC/CVV. |
| 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. |
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. |