worldline Direct
Sign up

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.

Before delving into specific error scenarios, it is recommended to read our dedicated Statuses guide, providing a general overview of all possible transaction/request outcomes.

HTTP response codes

Our Direct API uses standard HTTP response codes to indicate the status of each request made to the system.

Response Code Ranges

Understanding the significance of HTTP response codes is crucial for effective interaction with the Direct API. Below, you can explore the different response code ranges and their implications:

  • 2xx Series: Successful responses, indicating that the request was handled correctly.

  • 4xx Series: Client error responses, signifying issues with the request itself or transaction rejection.

  • 5xx Series: Server error responses, indicating a problem on one of the parties involved in processing your request.

HTTP Response Code

The Direct API uses the following HTTP response codes:

HTTP
Response
Code
Meaning Description
200 Successful Your request was processed correctly.
201 Created Your request was processed correctly and a new resource was created.
The URI of this created resource is returned in the Location header of the response.
400 Bad Request Your request is not correct and cannot be processed.
Please correct the mistake and try again.
402 Payment Rejected Your request was rejected either by us
or one of our downstream partners/acquirers.
403 Not authorized You are trying to do something that is not allowed or that you are not authorised to do.
404 Not found The object you were trying to access could not be found on the server.
409 Conflict Your request resulted in a conflict.
Either you submitted a duplicate request or
you are trying to create something with a duplicate key.
410 Gone The object that you are trying to reach has been removed.
500 Internal Server Error Something went wrong on our end.
502 Bad Gateway We were unable to process a message from a downstream partner/acquirer.
503 Service Unavailable The service that you are trying to reach is temporary unavailable.
Please try again later.


Make sure your application can handle HTTP error codes not included in this list.

Receive information about errors

We distinguish between two types of errors

  • Technical errors: These occur when our platform cannot process a request due to issues with the request itself or 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: These happen when a request is technically correct but is rejected by our platform, the acquirer or issuer.

If you send a request (i.e. CreatePayment/CreateHostedCheckout/GetPaymentDetails) to our platform causing an error, the JSON properties in the response 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 standard HTTP status codes.

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 from your 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)
{
  "errorId": "8c0e1431-4c6c-4fcf-8c58-c8c083730968",
  "errors": [
    {
      "code": "9007",
      "id": "ACCESS_TO_MERCHANT_NOT_ALLOWED",
      "category": "DIRECT_PLATFORM_ERROR",
      "message": "ACCESS_TO_MERCHANT_NOT_ALLOWED",
      "httpStatusCode": 403
    }
  ],
  "status": 403
} 
Technical error (Missing/wrong properties)
{
  "errorId": "4dac7acb-70c1-4917-80cd-068833fd8da5",
  "errors": [
    {
      "errorCode": "50001130",
      "category": "DIRECT_PLATFORM_ERROR",
      "code": "1002",
      "httpStatusCode": 404,
      "id": "UNKNOWN_PAYMENT_ID",
      "message": "UNKNOWN_PAYMENT_ID",
      "propertyName": "paymentId",
      "retriable": false
    }
  ]
} 
Technical error (Wrong payload)
{
  "errorId": "5298814d-ca42-4fd5-926e-ceed1b69fccc",
  "errors": [
    {
      "errorCode": "50001111",
      "category": "DIRECT_PLATFORM_ERROR",
      "code": "1008",
      "httpStatusCode": 400,
      "id": "INVALID_VALUE",
      "propertyName": "order.amountOfMoney"
    }
  ]
}
Transaction exception
...
  "status": "REJECTED",
  "statusOutput": {
    "errors": [
      {
        "errorCode": "50001066",
        "category": "DIRECT_PLATFORM_ERROR",
        "code": "1099",
        "httpStatusCode": 400,
        "id": "INVALID_VALUE",
        "message": "INVALID_VALUE",
        "retriable": false
      }
    ],
...

To address and resolve errors effectively, check out the following sub-chapters:

Fix errors.category

Property value Description/Possible actions
DIRECT_PLATFORM_ERROR

Technical errors referring to unknown/invalid data provided during the request, such as

  • Property values/allowed value range. Check our API reference/the "Integration" tab in the payment method guides for the correct value(s)
  • Data our platform needs to process your request (i.e. hostedCheckoutId/paymentId etc.)
  • API Key/Secret/PSPID sent in request do not match with the data on our platform

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
GetPaymentDetails
GetHostedCheckout
CancelPayment
CapturePayment
CompletePayment

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

  • Has expired.
  • Is under suspicion of fraudulent use.

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

  • To contact your acquirer if you have disproportionately many rejections with this error code.
  • To (re-)assess whether these rejections could be fraudulent by consulting the rating in your Fraud Prevention module.
30141001

Your customer's issuer rejected the transaction because the card

  • Is wrong.
  • Has expired.

Make sure to

  • Your customers use valid cards if you are working with the Server-to-server integration mode.
  • To (re-)assess whether these rejections could be fraudulent, as repeatedly entering invalid card data can be considered fraud attempts. Contact us to configure your Fraud Prevention module for maximum protection and high conversion rates at the same time.
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

  • Select a different payment method for retrying.
  • Amend their shopping cart content to reduce their total. Consider contacting your customers to remind them to complete their purchase at a later time.
30581001

Your customer's issuer rejected the transaction because it does not accept a corporate card for this kind of purchase.

Make sure to

  • Enable your customers to select a different payment method for retrying.
  • Consider contacting your customers to remind them to complete their purchase at a later time.
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

  • Enable your customers to select a different payment method for retrying.
  • Inform your customers about the (security) restrictions associated with the card, allowing them to lift the restrictions.
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:

  • Enable your customers to select a different payment method for retrying.
  • Consider contacting your customers to inform them about the reasons for the rejection and encourage them to complete their purchase at a later time.
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:

  • Enable your customers to select a different payment method for retrying.
  • Resubmit the transaction at a later time.
40001138

Our platform rejected rejected the transaction because at the time of processing we were unable to confirm the identity of the cardholder due to an unexpected failure.

To recover this declined transaction, resubmit the transaction at a later time or suggest another payment method to the cardholder.
Customer details can be found in the Back Office under Operations > View Transactions.

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:

  • Detect the brand of the card correctly/invalid card data before submitting the transaction to our platform.
  • Enable your customers to select a different payment method for retrying.
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
GetPaymentDetails
CapturePayment

CompletePayment

GetHostedCheckout

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

  • Send the correct value(s) as defined in our API reference and in the "Overview" tab for the individual payment methods.
  • Validate that the payment method is active in your account.
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.

RefundPayment

CapturePayment

CompletePayment

Make sure to

  • Check errors.errorCode for details what forbidden action you have tried.
  • Check the transaction status allows the maintenance operation you want to perform.
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 usingServer-to-server integration mode.

Make sure to detect the brand of the card correctly/invalid card data before submitting the transaction to our platform.

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.

Comply to Visa/MasterCard reattempt management

Visa and MasterCard have established a list of specific error codes to address potential fraudulent retries after an initial card decline.

Complying with these rules is crucial to reduce fraud rates and avoid additional fees imposed by Visa/MasterCard through your acquirer. We help you become compliant 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.

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

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 common rejection reasons, Visa/MasterCard might update reasons in the future. If you encounter an error code not listed, 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.

Was this page helpful?

Do you have any comments?

Thank you for your response.