Troubleshooting
Introduction
When processing transactions on our platform, you will face the task to treat errors accordingly. Depending on your request, you might encounter errors related to
- Rejections from acquirers/issuers
- Our Fraud Prevention tools
- Our platform due to technical issues
- Missing/wrong properties in your request
- Wrong API endpoint your request is sent to
To help you understand and amend these errors, we walk through the most common ones and provide our recommendations.
Receive information about errors
We distinguish between two types of errors
- Technical errors: Our platform could not process the request due to technical issues with your request or on our platform. This could be related to
- A non-existent/wrong API endpoint your request is sent to
- API key/secret/PSPID mismatches with the data on our platform
- Missing/wrong properties in your request
- A wrong payload
- Transaction exceptions: Your request was technically correct, but were rejected by either our platform, the acquirer or issuer
If you send a request (i.e. CreatePayment/CreateHostedCheckout/GetPaymentDetails) to our platform causing an error, the response contains as JSON. The JSON properties will help you find the root cause and find a solution:
Property | Description |
---|---|
errorID |
The unique identifier of your request on our platform. If you need our help to solve the error linked to this request, make sure to add it in your message when contacting us |
errors.category |
Human-readable description of the global error category. This can be both technical errors and transaction exceptions |
errors.code | 4- to 8-digit error code linked to errors.category, indicating the specific error category |
errors.errorCode | 8-digit error code linked to technical errors (for 5xxxxxxx errors) or transaction exceptions |
statuserrors.httpStatusCode |
3-digit error code linked to
|
errors.id | Human-readable description of the specific category the error falls into |
errors.message | Human-readable description of the specific category the error falls into, providing detailed information if available |
errors.propertyName | The property in the request causing the error (i.e. invalid or missing values sent in your request) |
A typical error message depending on the type of error looks like this:
Error type | JSON returned from our platform |
---|---|
Technical error (non-existent/wrong API endpoint) | header content-lenght = 0 |
Technical error (API key/secret/PSPID mismatch) |
|
Technical error (Missing/wrong properties) |
|
Technical error (Wrong payload) |
|
Transaction exception |
|
Check out the following sub-chapters to learn how to act upon errors appropriately:
Fix errors.category
Property value | Description/Possible actions |
---|---|
DIRECT_PLATFORM_ERROR |
Technical errors referring to unknown/invalid data provided during the request, such as
Check properties errors.message/errors.id for detailed information Configure the API Key/Secret correctly and/or send the correct data in your request |
PAYMENT_PLATFORM_ERROR | Various technical errors or transaction exceptions Check properties errors.id/errors.message/errors.errorCode for root cause and possible solutions |
Fix errors.code
Property value | Description/Possible actions |
---|---|
1002 1003 1004 1005 |
You have sent an invalid paymentId for either request: RefundPayment Make sure to send your request to the correct merchantId (your PSPID on our platform)/ environment |
1099 1008 1007 |
You have sent an invalid value for one or more properties in your request. Refer to errors.propertyName to get a list of impacted properties. Make sure to send the correct value(s)/data type/allowed range as defined in our API reference |
9007 |
The API Key/Secret/PSPID sent in request do not match with the data on our platform Make sure to send the correct value(s) and/or configure the API Key/Secret correctly in your PSPID before sending new request |
Fix errors.errorCode
Property value | Description/Possible actions |
---|---|
30001100 |
Your Fraud Prevention module rejected the transaction because the location of the customer is on your blacklist. (Re-)assess which countries have the highest number of these rejections. If it is unlikely that you have genuine customers in this country, keep this country on your blacklist. Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001101 |
Your Fraud Prevention module rejected the transaction because you have a rule blocking transactions with a different IP country to card country. (Re-)assess whether this fraud rule is too strict for your business model, leading to blocking legitimate transactions. If it is unlikely that there is a discrepancy between IP country and card country for legitimate customers, keep this setting. Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001102 |
Your Fraud Prevention module rejected the transaction because you have a rule blocking transactions with the number of countries allowed in transactional data is too high. (Re-)assess whether this fraud rule is too strict for your business model, leading to blocking legitimate transactions. Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001104 |
Your Fraud Prevention module rejected the transaction because the location of the customer is on your blacklist. (Re-)assess in which countries you have genuine customers. If it is unlikely that you have genuine customers in this country, keep this country on your blacklist. Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001105 |
Your Fraud Prevention module rejected the transaction because your customers masked the IP's origin. (Re-)assess whether your business model justifies allowing the use of an anonymous proxy. Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001106 |
Your Fraud Prevention module rejected the transaction because the IP's origin could not be determined. (Re-)assess whether your business model justifies allowing transactions for which your customers' country is unknown. Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001120 |
Your Fraud Prevention module rejected the transaction because the IP is on your blacklist. (Re-)assess whether your business model justifies blocking transactions from this specific IP address (i.e. because of past fraudulent transactions related to this IP). Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001130 |
Your Fraud Prevention module rejected the transaction because the BIN is on your blacklist. (Re-)assess whether your business model justifies blocking transactions with this specific BIN (i.e. because of past fraudulent transactions related to this BIN). Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001140 |
Your Fraud Prevention module rejected the transaction because the card number is on your blacklist. (Re-)assess whether your business model justifies blocking transactions with this specific card number (i.e. because of past fraudulent transactions related to this card number). Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001141 |
Your Fraud Prevention module rejected the transaction because the e-mail address of the customer is on your blacklist. (Re-)assess whether your business model justifies blocking transactions with this specific e-mail address (i.e. because of past fraudulent transactions related to this e-mail address). Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001142 |
Your Fraud Prevention module rejected the transaction because the name of the customer (sent in property order.additionalinput.airlineData.passengers in your CreatePayment / CreateHostedCheckout request) is on your blacklist. (Re-)assess whether your business model justifies blocking transactions with this specific name (i.e. because of past fraudulent transactions related to this name). Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001143 |
Your Fraud Prevention module rejected the transaction because the cardholder name is on your blacklist. (Re-)assess whether your business model justifies blocking transactions with this specific cardholder name (i.e. because of past fraudulent transactions related to this cardholder name). Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001158 |
Your Fraud Prevention module rejected the transaction because you have a rule blocking the number of transactions with the same email address in one day. (Re-)assess whether your business model justifies blocking transactions from a specific e-mail address that is used multiple times in one day (i.e. because of past fraudulent transactions related to this scenario). Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30001180 |
Your Fraud Prevention module rejected the transaction because they had a total risk score exceeding your acceptance threshold. This figure is an indication that a large number of these transactions were blocked fraud attempts. (Re-)assess whether your business model justifies less strict rules if you are concerned that you are blocking legitimate transactions. Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time. |
30031001 |
You acquirer rejected the transaction because your MID (merchant ID) is not working properly. Contact us and your acquirer to make sure that the MID properly set up on our side and your acquirer's side |
30041001 |
Your customer's issuer rejected the transaction because the card
Make sure
|
30051001 |
Your customer's issuer rejected the transaction without disclosing a specific reason. Because of privacy data laws, issuers will provide this rejection reason for most of your declined transactions. Make sure
|
30141001 |
Your customer's issuer rejected the transaction because the card
Make sure to
|
30431001 |
Your acquirer or your customer's issuer rejected the transaction because the card used has been reported as stolen Make sure to put this card on Fraud Prevention module blacklist |
30511001 |
Your customer's issuer rejected the transaction because of insufficient funds for this payment Make sure to enable your customers to
|
30581001 |
Your customer's issuer rejected the transaction because it does not accept a corporate card for this kind of purchase Make sure to
|
30591001 |
Your customer's issuer rejected the transaction because the card used has been used for fraudulent transactions Make sure to put this transaction on Fraud Prevention module blacklist. Our platform will then automatically block any other attempts matching with information associated with this fraudulent transaction Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time |
30621001 |
Your acquirer or your customer's issuer rejected the transaction because of (security) restrictions associated with the card Make sure to
|
30921001 |
Your acquirer rejected the transaction because it does not accept this card for this kind of purchase Make sure to contact your acquirer if you have these kind of rejections on a regular base. You might be able to renegotiate your contract to lift possible acceptance restrictions |
40001134 |
Your acquirer or your customer's issuer rejected the transaction because of a failed 3-D Secure check. This could be related to legitimate authentication failures (i.e. technical problem with your customers' device or network, missing card readers or forgotten PIN codes) or fraud attempts Make sure to
|
40001135 50001081 |
Your acquirer or your customer's issuer rejected the transaction because of a failed 3-D Secure check. This is because the issuer was not available to confirm the identity of the cardholder. This error comes from the issuing bank and is out of your control. However, you can consider the following:
|
40001137 |
Your acquirer or your customer's issuer rejected the transaction because of a missing 3-D Secure check. This is because our platform could not roll out 3-D Secure This error comes from our platform and is out of your control. However, you can consider the following:
|
40001139 |
Your customer's issuer rejected the transaction because you have tried to skip the 3-D Secure check using our Soft Decline mechanism. As the issuer insists on 3-D Secure, the transaction was rejected Make sure to recover the transaction as described in our dedicated guide |
50001054 |
Our platform rejected the transaction because of a mismatch between the brand you defined in property cardPaymentMethodSpecificInput.paymentProductId and the card number in property cardPaymentMethodSpecificInput.card.cardNumber . This error occurs exclusively when using Server-to-server integration mode Make sure to
|
50001087 |
Our platform rejected the transaction because our platform could not roll 3-D Secure check. This is because there was an technical issue with your request Make sure to
|
Fix errors.id
Property value | Description/Possible actions |
---|---|
UNKNOWN_PAYMENT_ID UNKNOWN_REFUND_ID UNKNOWN_PAYOUT_ID UNKNOWN_CAPTURE_ID |
You have sent an invalid value for property paymentId/payoutId for either request: RefundPayment Make sure to
|
UNKNOWN_PRODUCT_ID UNKNOWN_PRODUCT_GROUP_ID UNKNOWN_PRODUCT_IDS UNKNOWN_PRODUCT_GROUP_IDS |
You have sent an invalid value for property paymentProductId / hostedCheckoutSpecificInput.paymentProductFilters in your request Make sure to
|
INVALID_VALUE |
You have sent an invalid value for one or more properties in your request (specified in property errors.propertyName) Make sure to send the correct value(s)/data type/allowed range as defined in our API reference |
ACTION_NOT_ALLOWED_ON_TRANSACTION |
You have sent a request to perform a maintenance operation that is not allowed for this specific transaction for either request Make sure to
|
PAYMENT_PRODUCT_NOT_AVAILABLE |
You have sent a request with a paymentProductId referring to a payment method not active/available in your PSPID Make sure to
|
UNKNOWN_TOKEN_ID |
You have sent a CreatePayment/CreateHostedCheckout request for a recurring payment with an invalid/non-existent token. Make sure the token exists in the PSPID you send the request to. |
CARDNUMBER_PAYMENTPRODUCTID_MISMATCH |
You have sent a CreatePayment request with a mismatch between the brand you defined in property cardPaymentMethodSpecificInput.paymentProductId and the card number in property cardPaymentMethodSpecificInput.card.cardNumber. This error occurs exclusively when using Server-to-server integration mode Make sure to
|
PAYMENT_PRODUCT_NOT_REFUNDABLE |
You have sent a RefundPayment request for a transaction that was processed with a payment method not supporting refunds Make sure to check in the in payment product overview for the respective payment method that it does support refunds |
AUTHENTICATION_FAILURE |
The 3-D Secure identification for this transaction was unsuccessful Make sure to refer to errors.errorCode for the root cause and possible actions |
3. Comply to Visa/MasterCard reattempt management
Card schemes Visa/MasterCard have defined a list of specific error codes that refer to possible fraudulent retries once a card has been declined in the first place.
To reduce the number of such retries (and thereby decrease fraud rates), Visa/MasterCard expect you to limit/prevent retries for these cards.
It is instrumental that you comply to this rule, as Visa/MasterCard charge you additional fees (collected by your acquirer) for any of these retries.
Worldline helps you to comply to this rule by either
for the following groups of error codes:
Our platform might throw 39991001 – "Maximum number of attempts reached for a transaction with same payment number. Our platform will block any new attempt until the waiting period expires".
This platform-specific error code is not directly related to the Visa/MasterCard rules. Our platform throws this error after the maximum number of attempts for a transaction with the same error code. Our platform will block any new attempt within the period defined by Visa/MasterCard. Refer to the original rejection code of previous attempts to learn why the transaction was rejected in the first place.
A) Block retries after the first failed try over a period of 30 days
Error code | Description |
---|---|
30041001 | Pick up card (no fraud) |
30071001 | Pick up card, special condition (fraud account) |
30121001 | Invalid transaction |
30141001 | Invalid account number (no such number) |
30151001 | No such issuer (first 8 digits of account number do not relate to an issuing identifier) |
30411001 | Lost card, pick up |
30431001 | Stolen card, pick up |
33000972 | Stop payment order |
33000973 | Revocation of authorization order |
33000975 | Revocation of all authorizations order |
33000831 | Cash service not available |
33000832 | Cash request exceeds issuer or approved limit |
33000833 | Ineligible for resubmission |
B) Limit retries over a certain period of time
For this group of errors, Visa and MasterCard define different time periods:
- Visa: Limit to 15 retries over a period of 30 days
- MasterCard: Limit to 10 retries over a period of 24 hours
This list contains only the most common rejection reasons for this category. Visa/MasterCard might add or remove rejection reasons in the future. If you encounter an error code not listed in this or any category, the rejection reason is linked to the rule defined by category B.
Error code | Description |
---|---|
30191001 | Re-enter transaction |
30541001 | Expiration data |
30511001 | Not sufficient funds |
30591001 | Suspected fraud |
30611001 | Exceeds approval amount limit |
30621001 | Restricted card (card invalid in region or country) |
30751001 | Allowable number of PIN-entry tries exceeded |
30781001 | Blocked, first used (Brazil only) |
30911001 | Issuer or switch inoperative |
30931001 | Transaction cannot be completed – violation of law |
33000831 | Cash service not available |
33000832 | Cash request exceeds issuer or approved limit |
30541001 | Expired card or expiration date missing |
30551001 | PIN incorrect or missing |
40001139 | Additional customer authentication required (Europe Region only) |
33000835 | Decline for CVV2 failure |
Our platform implements this mechanism for integration modes Hosted Checkout Page and Server-to-server