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_DECLINE
INTERNAL_DECLINE
failureCode | Description | Recommended Steps |
---|---|---|
| Capture or Void operation failed because you have not completed a successful Authorization yet, and it has not yet reached the | 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 The best way to avoid this error is to wait for an |
| 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 | Check that there are successful Capture operations under this payment charge, and that the charge status is not |
| 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 |
| 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. |
| The amount added is not valid | The gateway has minimum and maximum values that are accepted in the |
| The added country is either invalid or not supported | Have the consumer fill in the country value again with a valid one. |
| 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. |
| We discarded the payment charge because it was not authorized within the timeout limit for the | 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) |
|
| Review the docs for the payment method in question to ensure you are sending the correct |
| The | Review the docs for the payment method in question to ensure you are sending the correct |
| 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. |
| 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. |
|
| Review the docs for the payment method in question to ensure you are including a valid tax id format. |
| 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. |
| 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. |
| 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. |
| 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. |
| We have detected too many payment attempts from the specified consumer IP address. | Contact your account manager or technical account manager for more information. |
| The card or account has been blocked by PPRO due to suspected fraud or abuse. | Ask the consumer to choose a different payment method. |
| 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. |
| 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. |
| 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. |
| The Payment Agreement failed or has not been properly activated yet. Subsequent payments are not possible. | Check that the Agreement status is |
| 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 |
| Could not find a payment instrument matching the specified | 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. |
| 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. |
| Reservation would make the balance fall below the minimum funds account balance | Contact PPRO to increase the limit amount |
INTERNAL_ERROR
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
PROVIDER_DECLINE
failureCode | Description | Recommended Steps |
---|---|---|
| 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. |
| 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. |
| The amount value is not supported by the provider. | The payment method used has minimum and maximum values that are accepted in the |
| The country value is not supported by the provider | Have the consumer fill in the country value again with a valid one. |
| 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. |
| The CVC/CVV was wrong. | Have the consumer try again by entering the correct CVC/CVV. |
| The card or account number cannot be validated by the issuer. | Have the consumer enter their card number again or try a different card. |
| The card or account | Have the consumer enter their card details again or try a different card. |
| 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. |
| The billing address entered was wrong. | Have the consumer enter the billing address again. |
| The provider has determined the | Have the consumer enter their tax identification number again. If you receive this failure code frequently and consistently, check that |
| Generic decline by the issuer. | The consumer should contact their issuer to receive more information and resolve the problem. |
| Not permitted by the issuer. | The consumer should contact their issuer to receive more information and resolve the problem. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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 in the account. | Ask the consumer to choose a different payment method, card or account. |
| Expired card. | Ask the consumer to update/change their card or choose a different payment method. |
| 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. |
| The provider failed to respond on time. | Retry the request. If you receive this failure code repeatedly, there may be an incident. |
PROVIDER_ERROR
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. |