Skip to content

    Response codes

    This guide lists the response codes you'll receive from Netaxept.

    Overview

    You will receives a response message from Netaxept after each operation mentioned in the Payment Flow Outline section. It contains either the response code "OK" or some error code. Response codes are returned to you through API, and can be fetched by using the Query call. They can also be seen in the a web-based Netaxept Admin.

    Make your implementation so that it doesn't rely on the timestamps of different operations but interprets the content of the response message received.

    We recommend you make your payment implementation that after a successful, failed or cancelled payment, the customer is redirected to a separate page informing of the outcome of the payment process.

    Therefore, the redirectURL parameter cannot contain the URL of the "select payment method" page or any other page that is in the middle of the order process. If the customer wants to return directly to the order process after successful, failed or cancelled payment, the webshop must generate a new order for them.

    Response code "OK"

    There are two places in the payment flow when Netaxept may respond with the response code OK. Make sure that these two responses do not get confused.

    Terminal phase is completed succesfully

    After the customer has entered their payment method information in the payment window and passed the possible 3D Secure authentication successfully, they are redirected to the redirectURL specified by the merchant in the Register call. At the end of this URL you will find a responseCode parameter which includes either "OK", "Cancel" or some error code. This specifies whether the terminal process has been completed successfully. It doesn't contain information about the completeness of the actual payment.

    Example: url for a completed terminal phase - line breaks for readability

    http://localhost/Test/?
      transactionId=6c5e402a4ee445ba9f19411f55c75b91&
      responseCode=OK

    Example: url for a payment where the customer clicked "Cancel" on the payment window (line breaks for readability):

    http://localhost/Test/?
      transactionId=6c5e402a4ee445ba9f19411f55c75b91&
      responseCode=Cancel

    Payment is processed successfully

    The response code OK is also returned to the merchant when the transaction has been processed (for example authorized, captured or credited) successfully without errors by using the Process call. In that case, the OK response can be found in the ResponseCode parameter of the ProcessResponse.

    Despite of the successfully authorized and captured transaction, it is recommended to make the Query call before sending goods to the customer to verify that the money has actually been captured. This is due to the response times Netaxept from time to time see from third-party payment methods, such as direct bank payments.

    Example of a response for a successfully processed payment:

    <ProcessResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <AuthorizationId>258460</AuthorizationId>
    <BatchNumber>642</BatchNumber>
    <ExecutionTime>2017-01-24T07:47:28.1900126+01:00</ExecutionTime>

    Decline codes

    Types of declines

    There are two types of declines that can occur on card scheme payments:

    • soft declines
    • hard declines

    This section describes the differences between the two and clarifies how to proceed.

    Soft decline

    A soft decline occurs when the issuing bank approves the payment, but the transaction fails at some other point in the process.

    Examples of when a soft decline may occur:

    • insufficient funds
    • the card activity limit exceeded
    • failures due to either system, technical, or infrastructure issues
    • expired cards

    Hard decline

    A hard decline occurs when the issuing bank does not approve the payment. In other words, hard declines are permanent authorization failures and should not be retried.

    Examples of when a hard decline may occur:

    • possible fraud
    • insufficient available credit
    • lost or stolen card

    Error codes

    If something goes wrong when communicating between your system and Netaxept or in the middle of the payment process, Netaxept declines the transaction and returns an exception. All exceptions are wrapped in the outer Exception tag, with an Error tag inside. The type (xsi:type) of the Error tag indicates which exception it is.

    All exceptions include the message that provides a textual description of what failed. Besides the message, one commonly used exception "BBSException" includes also error code, error source and error message which are available in English.

    Example of an error response for a payment that is already processed:

    <Exception xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Error xsi:type="BBSException">
    <Message>Unable to sale</Message>
    <Result>

    Error sources

    The error codes are divided into groups according to the source. The source is a textual description of which part of the system generated the error code. The source should not be used to drive code; instead, it should only be logged and used as a diagnostic tool if it is unclear why a transaction failed.

    • "Netaxept" or "NTS" (or "01" in the old Netaxept; version 1), if the error occurred in the Netaxept solution.
    • "Issuer" (or "02" in the old Netaxept; version 1), if the error came from the card Issuer or other payment method service provider.
    • "Module" (or "03" in the old Netaxept; version 1)) or "Transport" (or "04" in the old Netaxept; version 1), if the error occurred internally at Nets.
    • "Terminal" (or "05" in the old Netaxept; version 1), if the error occurred as a result of the customer input in the payment window.

    Occasionally, you can see other sources as well, for example the name of a Netaxept’s integration partner, like "Klarna"

    Error codes from Netaxept (Source: Netaxept or 01)

    CodeMeaning
    14Invalid card number
    25Transaction not found
    30“KID invalid” or “Field missing PAN”
    84Original transaction rejected
    86Transaction already reversed
    96Internal failure
    97No transaction
    98Transaction already processed
    99Several errors can result in this error code. Refer to the Response text for details

    Error codes from Issuer (Source: Issuer or 02)

    CodeMeaning
    01Refused by Issuer. You can advise the consumer to contact their Issuer for more information.
    02Refused by Issuer. You can advise the consumer to contact their Issuer for more information.
    03Refused by Issuer because of the invalid merchant.
    04Refused by Issuer.
    05Refused by Issuer.
    06Refused by Issuer.
    07Refused by Issuer.
    08Refused by Issuer.
    10Refused by Issuer.

    Error codes from Netaxept partners, not related to 3D Secure authentication (Source: Module or 03)

    CodeMeaning
    01Timeout experienced.
    06Technical reversal was attempted, due to timeout, but the reversal failed as well.

    Error codes related to the communication between Netaxept and 3D Secure authentication (Source: Transport or 04)

    CodeMeaning
    30Value missing in required field, often resulting in the response text "Ntoa: Taglen err". A rare error that can occur if Visa or MasterCard experiences problems with 3D Secure authentication.

    Error codes / messages originating from Netaxept's payment window (Source: Terminal or 05)

    Netaxept displays error messages to the customer in the payment window, to guide the customer in cases where error situations can be resolved by fixing errors for example in data fields. These error messages will be translated to the language specified by the merchant in the Register call. The error messages may also specify the data field where the error is happening, to direct the customer to resolve the error. The following are the most common error messages shown in the payment window for card payments.

    • Too few digits
    • Expired card
    • Missing bank agreement
    • Too many digits
    • The cardnumber belongs to another card company
    • Contains illegal characters
    • Wrong cardnumber
    • Format error
    • Illegal value
    • Is missing and required
    • Not legal length -Refused by Issuer (Several payment methods may return this error message. In these cases, the Issuer bank or payment method service provider has refused the payment, and the customer can be advised to contact their card Issuer or payment method service provider to resolve the issue).
    • 17: Cancelled by customer
    • 30: Missing customer input

    Error messages without error codes

    Pan Hash not in file: panHash (token) used in subsequent payment has been deleted due to retention criteria.

    Error codes originated from Netaxept's integration partners

    Error messages from Netaxept’s integration partners are documented at their own developer site.

    Error codes related to merchant hosted payment window

    When the merchant uses their own hosted payment window, Netaxept will compose the responseCode parameter returned to the merchant via Query call from the following field names and messages. At the same time, the Operation parameter and the ResponseSource parameter will be set to "Terminal". In the responseCode parameter the field names and messages are concatenated with a ":", and if there are multiple errors, they will be comma-separated.

    Field name:

    • Cardnumber
    • ExpiryMonth
    • ExpiryYear
    • SecurityCode

    Message:

    • TooFewDigits
    • TooManyDigits
    • ContainsIllegalCharacters
    • HasWrongCheckDigit
    • FormatError
    • IllegalValue
    • Required
    • IllegalLength
    • ExpiredCard

    In some cases, the responseCode will be set to "30" when the ResponseSource is set to "Terminal". This is in the situations where Netaxept tries to look up the payment card in its BIN servers but is unable to find it. This can be communicated to the customer as "Illegal card". This case will be extremely seldom in the production environment as the production BIN servers have larger datasets than the ones in the test environment.

    Example of the error message returned to the merchant via Query response:

    <Error>
    <DateTime>2017-08-04T09:46:09.947</DateTime>
    <Operation>Terminal</Operation>
    <ResponseCode>Cardnumber:Required</ResponseCode>

    Examples of the ResponseCode values:

    ExpiryMonth:FormatError Expiry month is formally incorrect. For example, if an expiryDate is set to "1412", it will yield FormatError.

    Cardnumber:TooManyDigits Too many digits in the card number.

    Cardnumber:HasWrongCheckDigit,ExpiryMonth:FormatError A combination of wrong check digit on the card number and expiry month being formally incorrect.

    Error codes related only to version 1 of Netaxept API

    Below you can find error codes from version 1 of Netaxept API. The error response consists of a three-digit number indicating data field, combined with a code indicating the error. For example, if MasterCard CVC2 is missing, the response is 144:7.

    _3-digit number indicating the data field where the error occur:

    CodeMeaning
    137VISA card number
    138VISA expiry month
    139VISA expiry year
    140VISA CVV2
    141MasterCard card number
    142MasterCard expiry month
    143MasterCard expiry year
    144MasterCard CVC2
    145Diners Club card number

    Code indicating the exact error:

    CodeMeaning
    1Too few digits
    2Too many digits
    3Contains illegal characters
    4Has wrong check digit
    5Format error
    6Illegal value
    7Is missing and required
    8Is not of legal length
    9Only a single row should be filled out
    10Expired card
    18Missing bank agreement
    22PAN brand id mismatch

    Proper handling of response codes

    There can be various reasons why payment card schemes decline a transaction. In the section above, we describe the most common issuer response codes and their meanings.

    It is essential to keep in mind that card schemes impose restrictions on the number of times you can attempt a transaction that was previously declined. For instance, if a specific response code is returned, you are not permitted to reattempt the transaction authorization. On the other hand, some transactions can be retried but with a limited number of attempts. Therefore, it is crucial for you to consider this when formulating your retry strategy to ensure compliance with card scheme rules.

    For a comprehensive understanding of managing Visa and Mastercard authorization reattempts, including insights into dealing with excessive authorization-related Netaxept response messages, visit the Managing authorization reattempts page.

    Was this helpful?

    What was your feeling about it?