Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above

1. 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.

Read our dedicated guide to get a general overview about all possible transaction/request statuses

2. 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
status
errors.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)
{
  "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
      }
    ],
...

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

  • 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
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 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
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

4. Comply to Visa/MasterCard reattempt management

Card schemes Visa/MasterCard have defined a list of specific error codes that refer to possible fraudelent 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 cards that have been declined due to a specific group of error codes. We return this specific error in errors.errorCode.

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:

  • Visa: USD 0,10 to USD 0,15
  • MasterCard: EUR 0,50

Direct helps you to comply to this rule by either

  • A) Blocking retries after the first failed try
  • B) Limiting retries within a specific period
  • C) Allowing retries if resubmitted with additional information

A) Block retries after the first failed try over a period of 30 days

errors.errorCode - 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
30571001 - Transaction not permitted to cardholder
33000972 - Stop payment order
33000973 - Revocation of authorization order
33000975 - Revocation of all authorizations order

B) Limit to 15 retries over a period of 30 days

errors.errorCode - Description
30031001 - Invalid merchant
30191001 - Re-enter transaction
30511001 - Not sufficient funds
30591001 - Suspected fraud
30611001 - Exceeds approval amount limit
30621001 - Restricted card (card invalid in region or country)
30651001 - Exceeds withdrawal frequency limit
30751001 - Allowable number of PIN-entry tries exceeded
30781001 - Blocked, first used (Brazil only)
30861001 - Cannot verify PIN
30911001 - Issuer or switch inoperative
30931001 - Transaction cannot be completed – violation of law
30961001 - System malfunction
33000831 - Cash service not available
33000832 - Cash request exceeds issuer or approved limit

C) Allow retries if resubmitted with additional information

errors.errorCode - Description
30541001 - Expired card or expiration date missing
30551001 - PIN incorrect or missing
30701001 - PIN data required (Europe Region only)
30821001 - Negative Online CAM, dCVV, iCVV, or CVV results
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