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 account or card not supported. | Return the consumer to the payment method selection step of the checkout to try again with a different card or payment method. |
AMOUNT_NOT_SUPPORTED | Amount value is outside supported range. | Use a valid amount.value within the payment methods min/max limits. |
AUTHENTICATION_FAILED | The consumer failed authentication. | The consumer should contact their issuer or provider to receive more information and resolve the problem. |
BLOCKED_ACCOUNT | ||
CANCELED_BY_CONSUMER | The provider has informed us that the consumer intentionally abandoned the authentication flow. | 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. |
CURRENCY_NOT_SUPPORTED | ||
DUPLICATE_DETECTED | Provider detected a very similar request recently with the same details and amount. | Check and ensure you are not charging/refunding multiple times for the same product. |
EXPIRED_CARD | The card has expired. | Ask the consumer to update/change their card or choose a different payment method. |
EXPIRED_SESSION |
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. |