1. Home
  2. integration solutions
  3. Integrations
  4. Integrate with Nexi Payengine DirectLink (server-to-server)

Integrate with Nexi Payengine DirectLink (server-to-server)

Nexi Payengine DirectLink allows you to set up a server-to-server integration with our platform. The customer remains on a page of your own that will securely send the payment data to our servers.

You can also use DirectLink for maintenance of transactions, whether they were initiated in DirectLink or in e.g. e-Commerce mode.

The graph above shows a transaction flow with DirectLink integration.

Using DirectLink, there is no contact between our system and the merchant's (your) customer. Your system transmits all the information required to make the payment directly to our system in an HTTPS POST request. Our system requests the financial transaction (synchronously or asynchronously) to the relevant acquirer and returns the response to your server in XML format. Your programme reads the response and resumes its processing.

You are therefore responsible for collecting and storing your customer's confidential payment details and must guarantee the confidentiality and security of these details by means of encrypted web communication and server security.

In order to store personal and card data, you need to be PCI compliant.

    The following general procedures and security controls are valid for all DirectLink requests: new order requests, maintenance requests and direct queries.

    The graph above shows a step-by-step transaction flow with DirectLink integration.

    An API (Application Program Interface) user is needed to make DirectLink requests.

    In general it's a user specifically designed to be used by an application to make automatic requests to the payment platform.

    You can create an API user in your Nexi Payengine account via "Configuration" > "Users". Select "New user" and fill the required fields.

    To make the new user an API user, make sure to enable the "Special user for API (no access to admin.)" box.

    Creation of an API user

    Even though various user profiles are available for an API user, we strongly recommend you to configure this user with the "Admin" profile.
    If you want to limit the rights for maintenance of transactions (refunds, cancellations etc.), you can still change the user profile to e.g. "Encoder".

    If you are not sure, we recommend you to choose the "Admin" profile, otherwise go to User profiles (User Manager) for more information.

    The password for an API user does not have to be changed regularly. This is more convenient when the password has to be hard-coded into your application. However, we recommend you to change the password from time to time.

    For more information about User types and how to change the API user's password, go to User types (User Manager).

    For new order requests, maintenance requests and direct queries, you must send requests with certain parameters to specific URLs. The new order/maintenance/query parameters must be sent in a POST request as follows:

    PSPID=value1&USERID=value2&PSWD=value3&…

    The type/subtype indicating the Media Type in the Content-Type entity-header field in the POST request needs to be "application/x-www-form-urlencoded".

    DirectLink works in “one request-one reply” mode; each payment is processed individually. Our system handles individual transaction requests via DirectLink and can work synchronously (where this option is technically supported), i.e. we wait for the bank’s reply before returning an XML response to the request.

    When we receive a request on our servers, we check the level of encryption and the IP address which the request was sent from.

    DirectLink is built on a robust, secure communication protocol. The API is a set of instructions submitted with standard HTTPS POST requests. We only allow the merchant to connect to us in secure HTTPS mode.
    There is no need for a client TLS certificate.

    The SHA signature is based on the principle of your (the merchant’s) server generating a unique character string for each order, hashed with the SHA-1, SHA-256 or SHA-512 algorithms. The result of this hash is then sent to us in your order request. Our system reconstructs this signature to check the integrity of the order data sent to us in the request.

    Go to SHA-IN Signature (Nexi Payengine e-Commerce documentation) - the principle is the same in e-Commerce and DirectLink mode.

    For DirectLink, the SHA-IN passphrase needs to be configured in the "Checks for DirectLink" section of the "Data and origin verification" tab in your Technical information page.

    For each request, our system checks the IP address from which the request originates to ensure the requests are being sent from your (the merchant’s) server. In the IP address field in the "Checks for DirectLink" section of the "Data and origin verification" tab in your account's Technical Information page, you must enter the IP address(es) or IP address range(s) of the servers that send your requests.

    If the originating IP address has not been declared in the given IP address field, you will receive the error message “unknown order/1/i/”. The IP address the request was sent from will also be displayed in the error message.

    We will return an XML response to your request. Please ensure that your systems parse this XML response as tolerantly as possible to avoid issues in the future, e.g. avoid case-sensitive attribute names, do not prescribe a specific order for the attributes returned in responses, ensure that new attributes in the response will not cause issues, etc.

    • The request URL in the TEST environment is https://secure.payengine.de/ncol/test/orderdirect.asp.
    • The request URL in the PRODUCTION environment is https://secure.payengine.de/ncol/prod/orderdirect.asp.

    Change "test" to "prod"

    Replace “test” with “prod” in the request URL when you switch to your production account. If you forget to change the request URL, once you start in production with real orders, your transactions will be sent to the test environment and will not be processed by the acquirers/banks.

    The following table contains the request parameters for sending a new order request:

    Field Description
    PSPID

    Your affiliation name in our system.

    Format: AN, 30

    Mandatory
    ORDERID

    Your unique order number (merchant reference).

    Format: AN, 40

    Mandatory
    USERID

    Name of your application (API) user. Please refer to the User Manager documentation for information on how to create an API user.

    Format: AN, 20 (min 2)

    Mandatory
    PSWD

    Password of the API user (USERID).

    Format: AN

    Mandatory
    AMOUNT

    Amount to be paid, MULTIPLIED BY 100 as the format of the amount must not contain any decimals or other separators.

    Format: N, 15

    Mandatory
    CURRENCY

    ISO alpha order currency code, for example: EUR, USD, GBP, CHF, etc.

    Format: AN, 3

    Mandatory
    CARDNO

    Card/account number.

    Format: AN, 21

    Mandatory
    ED

    Expiry date.

    Format: MM/YY or //YY

    Mandatory
    COM

    Order description.

    Format: AN, 100

    Optional
    CN

    Customer name.

    Format: AN, 35

    Mandatory
    EMAIL

    Customer’s email address. If you are requesting 3DSv2.1,  please ensure that the format of the email is valid, otherwise the authentication process will fall back to 3DS 1.0

    Format: AN, 50

    Optional
    SHASIGN

    Signature (hashed string) to authenticate the data (see SHA-IN Signature).

    Format: AN, 128

    Mandatory
    CVC

    Card Verification Code. Depending on the card brand, the verification code will be a 3- or 4-digit code on the front or rear of the card, an issue number, a start date or a date of birth.

    Format: N, 5

    Mandatory

    ECOM_PAYMENT_
    CARD_VERIFICATION

    Alternative to CVC: date of birth / issue number / etc. (depending on country/bank)

    Format: N, 5

    Optional

    OWNERADDRESS

    Customer’s street name and number.

    Format: AN, 50

    Optional
    OWNERZIP

    Customer’s postcode.

    Format: AN, 10

    Optional
    OWNERTOWN

    Customer’s town/city name.

    Format: AN, 40

    Optional
    OWNERCTY

    Customer’s country, e.g. BE, NL, FR, etc.

    Format: AN, 2

    Optional
    OWNERTELNO

    Customer’s telephone number.

    Format: AN, 30

    Optional
    OPERATION

    Defines the type of requested transaction.

    You can configure a default operation (payment procedure) in the "Global transaction parameters" tab, "Default operation code" section of the Technical Information page. When you send an operation value in the request, this will overwrite the default value.

    Possible values:
    • RES: request for authorization
    • SAL: request for direct sale
    • RFD: refund, not linked to a previous payment, so not a maintenance operation on an existing transaction (you can not use this operation without specific permission from your acquirer).

    Optional:

    • PAU: Request for pre-authorization:
      In agreement with your acquirer you can use this operation code to temporarily reserve funds on a customer's card. This is a common practice in the travel and rental industry.
      PAU/pre-authorization can currently only be used on MasterCard and Visa transactions and is supported by selected acquirers. This operation code cannot be set as the default in your Nexi Payengine account.
      Should you use PAU on transactions via acquirers or with card brands that don't support pre-authorization, these transactions will not be blocked but processed as normal (RES) authorizations.

    Format: A, 3

    Mandatory
    WITHROOT

    Adds a root element to our XML response. Possible values: ‘Y’ or empty.

    Format: Y or <empty>

    Optional
    REMOTE_ADDR

    Customer's IP address (for Fraud Detection Module only). If a country check does not need to be performed on the IP address, send 'NONE'.

    Format: AN

    Optional
    RTIMEOUT

    Request timeout for the transaction (in seconds, value between 30 and 90)

    Important: The value you set here must be smaller than the time out value in your system (!)

    Format: N, 2

    Optional
    ECI

    Electronic Commerce Indicator.

    You can configure a default ECI value in your account's Technical information page, "Global transaction parameters" tab, "Default ECI value" section. When you send an ECI value in the request, this will override the default ECI value.

    Possible (numeric) values:
    0 - Swiped
    1 - Manually keyed (MOTO) (card not present)
    2 - Recurring (from MOTO)
    3 - Instalment payments
    4 - Manually keyed, card present
    7 - E-commerce with SSL encryption
    9 - Recurring (from e-commerce)

    Format: N, 2

    Optional

         





    If you process recurring payments, you need to add Credentials-on-file (COF) parameters to your request.

    Check out our Alias Manager (Tokenization) guide to learn everything about COF-transaction processing.


    The list of possible parameters to send can be longer for merchants who have activated certain options/functionalities in their accounts. Please refer to the respective option documentation for more information on extra parameters linked to the option.

    The following request parameters are mandatory in new orders:

    • PSPID and USERID
    • PSWD
    • ORDERID
    • AMOUNT (x 100)
    • CURRENCY
    • CARDNO
    • ED
    • CVC
    • OPERATION


    Our test page to send order requests in DirectLink can be found here: https://secure.payengine.de/ncol/test/testodl.asp.

    If there are payment methods you don't want a customer to be able to pay with, you can use a parameter to do so.
    This is particularly useful for sub-brands, when you want to accept a brand (e.g. MasterCard) but not one of its sub-brands (e.g. Maestro).

    The parameter is the following:

    Field Usage
    EXCLPMLIST List of payment methods and/or credit card brands that should NOT be used.
    Values must be separated by a “;” (semicolon).

    If a customer tries paying with a card linked to a payment method and/or (sub)brand thT you've excluded BY using the EXCLPMLIST parameter, the error message “Card number incorrect or incompatible” will be returned with the NCERRORPLUS return field.

    Our system supports the usage of 3-D Secure with DirectLink.

    Important

    • If you wish to use 3-D Secure with DirectLink, you need to have the D3D option activated in your account.
    • Some acquiring banks require the use of 3-D Secure. Please check with your acquirer if this is the case for you.

    The functionality to split VISA and MasterCard into a debit and a credit payment method allows you to offer them to your customers as two different payment methods (e.g. VISA Debit and VISA Credit), or you can decide only to accept one of both split brands.

    To use the split of credit and debit cards via DirectLink, you need to include the CREDITDEBIT parameter in the fields that you send to the orderdirect.asp page (and therefore also include in the SHA-IN calculation!).

    Field Format
    CREDITDEBIT "C": credit card
    "D": debit card

    Related error: When the buyer selects the debit card method but next enters a credit card number, an error code will be returned: ‘Wrong brand/Payment method was chosen’.

    If the payment is successfully processed with the CREDITDEBIT parameter, the same parameter will also be returned in the XML response, and/or can be requested with a Direct Query. However, whereas the submitted values are C or D, the return values are "CREDIT" or "DEBIT".

    You will also find these return values in transaction overview via "View transactions" and "Financial history", and in reports you may download afterwards.

    Configuration in your account

    The "split" functionality can also be activated and configured per payment method, in your Nexi Payengine account. Go to Split Credit/Debit Cards for more information.


    Check out our Alias Manager (Tokenization) guide to learn everything about COF-transaction processing.

    Our server returns an XML response to a request:

    Example of an XML response to an order request

    <?xml version=”1.0”?>
    <ncresponse orderID=”99999” PAYID=”1111111” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS=”5” ECI=”7” amount="125" currency="EUR" PM="CreditCard" BRAND="VISA"/>

    The following table contains a list of the ncresponse tag attributes:

    Field Description
    ACCEPTANCE Acceptance code returned by acquirer.
    amount Order amount (not multiplied by 100).
    BRAND Card brand or similar information for other payment methods.
    currency Order currency.
    ECI Electronic Commerce Indicator.
    NCERROR Error code.
    NCERRORPLUS Explanation of the error code.
    NCSTATUS First digit of NCERROR.
    orderID Your order reference.
    PAYID Payment reference in our system.
    PM Payment method.
    STATUS Transaction status. (Possible statuses)

    The attribute list may be longer for merchants who have activated certain options (e.g. the Fraud Detection) in their accounts. Please refer to the respective option documentation for further information about additional response attributes linked to the option.

    If you request processing for an already existing (and correctly processed) orderID, our XML response will contain the PAYID corresponding to the existing orderID, the ACCEPTANCE given by the acquirer in the previous processing, STATUS “0” and NCERROR “50001113”.

    A direct maintenance request from your application allows you to:

    • Perform a data capture (payment) of an authorised order automatically (as opposed to manually in the back office);
    • Cancel an authorisation of an order;
    • Renew an authorisation of an order;
    • Refund a paid order.

    Data captures, authorisation cancellations and authorisation renewals are specifically for merchants who have configured their account/requests to perform the authorisation and the data capture in two steps.

    • The request URL in the TEST environment is https://secure.payengine.de/ncol/test/maintenancedirect.asp.
    • The request URL in the PRODUCTION environment is https://secure.payengine.de/ncol/prod/maintenancedirect.asp.

    Change "test" to "prod"

    Replace “test” with “prod” in the request URL when you switch to your production account. If you forget to change the request URL, once you start working with real orders, your maintenance transactions will be sent to the test environment and will not be sent to the acquirers/banks.

    The following table contains the mandatory request parameters for performing a maintenance operation:

    FieldDescription
    AMOUNT Order amount multiplied by 100.

    This is only required when the amount of the maintenance differs from the amount of the original authorisation. However, we recommend its use in all cases.

    Our system will check that the maintenance transaction amount is not higher than the authorisation/payment amount.
    OPERATION

    Possible values:

    • REN: renewal of authorisation, if the original authorisation is no longer valid.
    • DEL: delete authorisation, leaving the transaction open for further potential maintenance operations.
    • DES: delete authorisation, closing the transaction after this operation.
    • SAL: partial data capture (payment), leaving the transaction open for another potential data capture.
    • SAS: (last) partial or full data capture (payment), closing the transaction (for further data captures) after this data capture.
    • RFD: partial refund (on a paid order), leaving the transaction open for another potential refund.
    • RFS: (last) partial or full refund (on a paid order), closing the transaction after this refund.

    Please note that with DEL and DES that not all acquirers support the deletion of an authorisation. If your acquirer does not support DEL/DES, we will nevertheless simulate the deletion of the authorisation in the back office.
    ORDERID You can send the PAYID or the orderID to identify the original order. We recommend the use of the PAYID.
    PAYID
    PSPID Your account's PSPID
    PSWD Password of your API-user
    SHASIGN Signature (hashed string) to authenticate the data (see SHA-IN-signature)
    USERID Your API-user

    Our server returns an XML response to the maintenance request:

    Example of an XML response to a direct maintenance request
    <?xml version=”1.0”?>
    <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="91" amount="125" currency="EUR"/>

    The following table contains a list of the ncresponse tag attributes:

    Field Description
    ACCEPTANCE Acceptance code returned by acquirer
    AMOUNT Order amount (not multiplied by 100)
    CURRENCY Order currency
    NCERROR Error code
    NCERRORPLUS Explanation of the error code
    NCSTATUS First digit of NCERROR
    ORDERID Your order reference
    PAYID Payment reference in our system
    PAYIDSUB The history level ID of the maintenance operation on the PAYID
    STATUS Transaction status (Possible statuses)

    The standard ncresponse tag attributes are the same as those for the XML reply to a new order, except for the extra attribute PAYIDSUB.

    If maintenance is requested twice for the same order, the second request will theoretically be declined with an error “50001127” (This order is not authorised), because the initial successful transaction will have changed the order status.

    A direct query request from your application allows you to query the status of an order automatically (as opposed to manually in the back office). You can only query one payment at a time, and you will only receive a limited amount of information about the order.

    If you need more details about the order, you can look up the transaction in the back office or perform a manual or automatic file download (see Consult your transactions and Batch).

    • The request URL in the TEST environment is https://secure.payengine.de/ncol/test/querydirect.asp
    • The request URL in the PRODUCTION environment is https://secure.payengine.de/ncol/prod/querydirect.asp

    Change "test" to "prod"

    Replace “test” with “prod” in the request URL when you switch to your production account.

    The following table contains the mandatory request parameters to perform a direct query:

    Field
    		 Description
    ORDERID
    You can send the PAYID or the ORDERID to identify the original order. We recommend the use of the PAYID.
    PAYID
    PAYIDSUB
    		 You can indicate the history level ID if you use the PAYID to identify the original order (optional).
    PSPID
    		 Your account's PSPID
    PSWD
    		 Password of your API-user
    USERID
    		 Your API-user

    You can test direct query requests here: https://secure.payengine.de/ncol/test/testdq.asp.

    Our server returns an XML response to the request:

    Example of an XML response to a direct query

    <?xml version=”1.0”?>
    <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="9" ECI=”7” amount="125" currency="EUR" PM="CreditCard" BRAND="VISA" CARDNO="XXXXXXXXXXXX1111" IP="212.33.102.55"/>

    The following table contains a list of the ncresponse tag attributes:

    Field
    		Usage
    ACCEPTANCE Acceptance code returned by acquirer
    amount Order amount (not multiplied by 100)
    BRAND Card brand or similar information for other payment methods
    CARDNO The masked credit card number
    currency Order currency
    ECI Electronic Commerce Indicator
    IP Customer’s IP address, as detected by our system in a 3-tier integration, or sent to us by the merchant in a 2-tier integration
    NCERROR Error code
    NCERRORPLUS Explanation of the error code
    NCSTATUS First digit of NCERROR
    orderID Your order reference
    PAYID Payment reference in our system
    PAYIDSUB The history level ID of the maintenance operation on the PAYID
    PM Payment method
    STATUS Transaction status

    The standard ncresponse tag attributes are identical to those for the XML reply to a new order, except for the additional attributes PAYIDSUB, CARDNO and IP.

    The attribute list may be longer for merchants who have activated certain options (e.g. the Fraud Detection) in their accounts. Please refer to the respective option documentation for more information on extra response attributes linked to the option.

    If the transaction whose status you want to check was processed with e-Commerce (hosted payment page), you may also receive the following additional attributes (providing you sent these fields with the original e-Commerce transaction).

    Field
    		Description
    complus*
    		 A value you wanted to have returned
    (paramplus content)*
    		 The parameters and their values you wanted to have returned

    *Please check the Variable feedback parameters (e-Commerce documentation).

    Example of an XML response to a direct query for an e-Commerce transaction

    <ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="9" amount="125" currency="EUR" PM="CreditCard" BRAND="VISA" CARDNO="XXXXXXXXXXXX1111" IP="212.33.102.55" COMPLUS="123456789123456789123456789" SessionID="126548354" ShopperID="73541312"/>

    The STATUS field will contain the status of the transaction (see Possible statuses).

    Only the following status is specifically related to the query itself:

    StatusNCERRORNCSTATUS Description
    88 The query on querydirect.asp failed

    The response times for a DirectLink transaction request are generally a few seconds; however, some acquirers may have longer response times.

    If you haven't received a response from our system after 30 seconds, you can send a request to querydirect.asp, asking for the status of your most recent transaction sent to orderdirect.asp. If you receive an immediate reply containing a non-final status for the transaction, there might be issues on the acquirer's end.

    If you haven't received an answer to this direct query request after 10 seconds, there might be issues on our end. You can repeat this request to querydirect.asp every 30 seconds until you see you receive a response within 10 seconds.

    Note
    • This check system will only be able to pinpoint issues at our end if there is also a check at your end to verify that requests are leaving your servers correctly.
    • An issue at our end will not always necessarily be caused by downtime, but could also be as a result of slow response times due to database issues for example.
    • Please use these checks judiciously to avoid bombarding our servers with requests, otherwise we might have to restrict your access to the querydirect.asp page.

    Important

    To protect our system from unnecessary overloads, we prohibit system-up checks which involve sending fake transactions or systematic queries, as well as systematic queries to obtain transaction feedback for each transaction.

    Based on GDPR article 12, 13 & 14, a Data Controller has the obligation to inform its end-customers about the future processing of their personal data. Such information should be made specific based on the type of personal data to be filled-in for a specific transaction (e.g.: selected payment method, controller/processor, acquirer, fraud). The result should be available and visible at the moment of the data collection and the cardholder should be offered with a printable and downloadable version of it.

    Per the GDPR policy, you need to display the information to your customer before they validate their transaction. This information should ideally be displayed on the same page as where your customer fills in their card/account credentials.

    The below privacy policy request allows you to retrieve all the information you need to display to your customer about our services in order to be compliant with the GDPR regulation.

    • The request URL in the TEST environment is https://secure.payengine.de/ncol/test/privacy-policy.asp

    • The request URL in the PRODUCTION environment is https://secure.payengine.de/ncol/prod/privacy-policy.asp
    Change "test" to "prod"
    Replace “test” with “prod” in the request URL when you switch to your production account.

    The following table contains the mandatory request parameters to be sent to your customer regarding the usage of their privacy information:

    Field Format
    		 Description
    USERID String Your API-user
    PSWD String Your API-user password
    PSPID
    		 String Your account’s PSPID
    BRAND String (e.g. Visa) Optional: Payment method brand
    You can send this field multiple times to get the result of several brands at once.
    • Sending no brand is the same as sending all your active brands.
    • Empty/wrong formatted brands are ignored.
    LANGUAGE ISO 639-1: Two-letter codes (e.g. FR) Optional: The language in which you want to retrieve the text.
    If not provided, the text will be returned into the merchant configured language.

    You can test direct query requests here: https://secure.payengine.de/ncol/test/privacy-policy.asp

    The following is a list of XML elements and the returned XML responses examples for different outcomes.

    Name Format Description
    Response Complex Root node, always present
    Response.Status String, possible values : Success, SuccessWithWarnings, Error Always present
    Response.Body Complex Present only when Response.Status = Success or SuccessWithWarnings
    Response.Body.Html String / html Empty if Response.Status = SuccessWithWarnings & Response.Warnings.Warning.Code = NoContent
    Response.Errors Complex Present only when Response.Status = Error
    Response.Errors.Error Complex Can occur multiple times inside an <Errors> node
    Response.Warnings Complex Present only when Response.Status = SuccessWithWarnings or Error
    Response.Warnings.Warning Complex Occurs multiple times inside a <Warnings> node
    Response.Errors.Error.Code
    Response.Warnings.Warning.Code    		 String, possible values :
    •Inside an <Error> node : Unauthorized, InternalServerError
    •Inside a <Warning> node : NoContent

    		 Always present in an <Error> or <Warning> node
    Response.Errors.Error.Message
    Response.Warnings.Warning.Message    		 String Optional

    If you face Response.Status=Error, please refer to the Response.Errors.Error to fix it.
    The following are two successful examples:
    1. Example of an XML response for success with warnings. This example displays if no privacy information needs to be disclosed to the customer.
      <Response>
      <Status>SuccessWithWarnings</Status>
      <Warnings>
      <Warning>
      <Code>NoContent</Code>
      </Warning>
      </Warnings>
      <Body>
      <Html/>
      </Body>
      </Response>

    2. Example of an XML response for success with content. The example shows a 2 section display
      <?xml version="1.0" encoding="utf-8"?>
      <Response>
      <Status>Success</Status>
      <Body>
      <Html><![CDATA[<ul><li><h2>Title 1</h2><p>Content 1</p></li><li><h2>Title 2 (VISA, American Express)</h2><p>Content 2</p></li></ul>]]></Html>
      </Body>
      </Response>

    For certain payment methods, the parameter values differ from the standard credit card values.

    The following table contains the specific parameter values allowing the transmission of Direct Debit AT transactions via DirectLink.

    Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
    Field Description Format/Value
    CARDNO

    Bank account number

    AN, 21

    Format: XXXXXXXXXXXBLZYYYYY

    XXXXXXXXXXX: account number, numeric, 11 digits.
    YYYYY: Bank code (Bankleitzahl), 5 digits.
    CN Bank account holder’s name AN, 35
    ED Expiry date
    		 „99/99“ oder „9999“
    OPERATION

    Operation code (Action to be performed)

    A, 3

    Possible values:

    • RES: authorisation
    • SAL/SAS: debit money from the bank account
    • RFD/RFS: refund money (*)
    OWNERADDRESS Address of the account holder AN, 50
    OWNERTOWN City/town of the account holder AN, 40
    OWNERZIP Postal code of the account holder AN, 10
    PM Payment method AN, 25

    “Direct Debits AT”

    (*If the Refund option is available and active, and DTAUS Refunds is available)

    The following table contains the specific parameter values allowing the transmission of Direct Debits NL transactions via DirectLink.

    Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
    Field Description Format/Value
    CARDNO Bank account number Regular Dutch account number: max. 10 alphanumeric characters (if less, left pad with zeros).

    OR

    IBAN account number: max. 35 alphanumeric characters (SEPA)
    CN Bank account holder’s name AN, 35
    ED Expiry date „99/99“ oder „9999“
    OPERATION

    Operation code (Action to be performed)

    A, 3

    Possible values:

    • SAL or SAS: debit money from the bank account
    • RFD or RFS: credit money to the bank account (refund)
    OWNERTOWN City of the bank account holder AN, 40
    PM Payment method

    AN, 25

    “Direct Debits NL”

    Only relevant for SEPA (*) transactions:
    BIC Bank Identifier Code AN, 11
    MANDATEID

    Unique mandate reference.

    Note: If not provided, the ORDERID will be used.

    AN, 35

    No spaces; cannot start or end with a forward slash "/", or contain two consecutive slashes.

    SEQUENCETYPE

    The Direct Debit transaction type

    Note: If not provided, the transactions will be considered as a “one-off” and value "OOFF" will be used.

    		Possible values to indicate the Direct Debit transaction type (AN, 4):
    • "FRST": First collection of a series of Direct Debit instructions
    • "RCUR": Direct Debit instructions where the debtor's authorisation is used for regular Direct Debit transactions initiated by the creditor
    • "FNAL": Final collection of a series of Direct Debit instructions (afterwards same MandateID can't be used anymore)
    • "OOFF": Direct Debit instruction where the debtor's authorisation is used to initiate one single Direct Debit transaction
    SIGNDATE

    Date mandate was signed by the buyer.

    Note: If not provided, the transaction date will be used.

    		 YYYYMMDD

    (*SEPA: Single Euro Payments Area)

    Note: These fields can be returned in the DirectLink XML-response and need to be included in the SHA-IN (and optionally SHA-OUT) calculation.

    For certain payment methods (excluding credit cards), you cannot send new transactions via DirectLink, but you can send certain maintenance operations via DirectLink. This is the case for PostFinance Card, PostFinance E-finance, PayPal Express Checkout and TUNZ.

    When sending maintenance operations, the PM, BRAND, CARDNO and ED fields are not required, so no specific values need to be sent for these payment methods.

    The 3-D Secure protocol enables the cardholder to be identified during the purchasing process. The cardholder needs to be connected to the Internet during the identification process. Thus 3-D Secure does not work for call centre or recurring payments.

    Visa has implemented the 3-D Secure protocol under the name Verified By Visa, MasterCard under the name SecureCode, JCB under the name J-Secure and American Express under the name SafeKey.

    The principle of the integration of DirectLink with 3-D Secure is to initiate a payment in DirectLink mode and end it in e-Commerce mode if a cardholder authentication is requested.

    This document describes the integration of the 3-D Secure protocol in DirectLink. For further information on DirectLink or e-Commerce, go to DirectLink or e-Commerce documentation.

    The transaction flow involves the following steps:

    1. You send us a DirectLink request for the transaction, containing a number of additional parameters (cf. Extra request parameters).
    2. Our system receives the card number in your request and checks online whether the card is registered in the VISA/MasterCard/JCB/AmEx directory (registered means that identification is possible for the card number, i.e. the card is a 3-D Secure card).
    3. If the cardholder is registered, the answer to the DirectLink request contains a specific payment status and html code that has to be returned to the customer to start the identification process (cf. Additional return fields). The block of html code will automatically start the identification process between the cardholder (customer) and his issuing bank.
    4. The cardholder identifies himself on the issuing bank’s page.
    5. Our system receives the identification response from the issuer.
    6. If the identification was successful, our system will submit the actual financial transaction to the acquirer.
    7. You receive the result of the global identification and online authorisation process via e-Commerce mode feedback channels.

    Comments:

    • Whether the liability shift applies or not depends on your acquirer contract. Therefore, we recommend you to check the terms and conditions with your acquirer.
    • If the cardholder is not registered (in step 3), you will receive the standard DirectLink XML response containing the result of the online authorisation process.
    • To receive the exact payment status/error codes (in step 7), you need to implement the online or offline post-sale feedback as described in the e-Commerce documentation.

    Apart from the standard DirectLink parameters, you also need to send the following information:

    Field Description
    FLAG3D

    Fixed value: ‘Y’

    Instructs our system to perform 3-D Secure identification if necessary.
    HTTP_ACCEPT The Accept request header field in the cardholder browser, used to specify certain media types which are acceptable for the response. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. For example:
    Accept: */*
    HTTP_USER_AGENT The User-Agent request-header field in the cardholder browser, containing information about the user agent originating the request. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. For example: User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)
    WIN3DS Way to show the identification page to the customer. Possible values:
    • MAINW: display the identification page in the main window (default value).
    • POPUP: display the identification page in a pop-up window and return to the main window at the end.
    • POPIX: display the identification page in a pop-up window and remain in the pop-up window.
    ACCEPTURL URL of the webpage to show the customer when the payment is authorised. (or waiting to be authorised).
    DECLINEURL URL to which the customer is redirected if the maximum number of failed authorisation attempts has been reached (10 by default, but which can be changed in the Technical Information page, "Global transaction parameters" tab, "Payment retry" section).
    EXCEPTIONURL URL of the webpage to show the customer when the payment result is uncertain.
    PARAMPLUS Field to submit the miscellaneous parameters and their values that you wish to be returned in the post-sale request or final redirection.
    COMPLUS Field to submit a value you wish to be returned in the post-sale request or output.
    LANGUAGE Customer’s language, for example: “en_US”
    Optional
    TP To change the layout of the "order_A3DS" page, you can send a template name/url with this parameter. (go to e-Commerce: Dynamic template).

    For more information, go to Transaction Feedback.

    If the cardholder is not registered, the normal DirectLink response is returned. If the cardholder is registered, the following (additional) fields will be returned:

    Field Description
    STATUS
    		 New value: “46” (waiting for identification)
    HTML_ANSWER

    BASE64 encoded html code to be added in the html page returned to the customer.

    This tag is added as a child of the <ncresponse> global XML tag. The field HTML_Answer field contains HTML code that has to be added in the html page returned to the customer's browser.

    This code will automatically load the issuer bank identification page in a pop-up in the main window, depending on the WIN3DS parameter value.

    To avoid any interference between the html tags included in the content of the HTML_ANSWER XML tag, with the rest of the XML returned as a response to the DirectLink request, the HTML_ANSWER content is BASE64 encoded by our system before returning the response. Consequently, this must be BASE64 DEcoded before it is included in the html page sent to the cardholder.
    Test Cards

    You can use the following test cards to simulate a 3-D Secure registered card in our test environment:

    Brand Card number Expiry date Password
    VISA 4000000000000002 Any date in the future 11111
    MasterCard 5300000000000006 Any date in the future 11111
    American Express 371449635311004 Any date in the future 11111
    Incorrect identification

    If a transaction is blocked due to incorrect identification, the transaction result will be:

    STATUS = 0

    NCSTATUS = 5

    NCERROR = 40001134

    In 2013, the European Commission published a proposal for the revised version of the Payment Services Directive, known as PSD2 to simplify payment processing and create the rules and regulations for payment services in the EU and there began the need for new version of 3-D Secure, v2.1.

    The biggest change is that you, as a merchant, are asked to share more data: issuers are hungry for data points to improve the accuracy of their decision ultimately leading to a frictionless scenario, but you are the ones on the front line capturing the data.

    The 3DS v2 approach to risk evaluation is more effective, but requires the entire ecosystem to change, allowing you to push the data through to the issuer.

    With the introduction of this new guidline, the major card schemes have updated their 3DS logos. As you are creating your own payment page, make sure to implement these new logos (Visa / Mastercard / JCB /… ).

    The transaction flow involves the following steps:

    1. You send us a DirectLink request for the transaction, containing a number of additional parameters.

    These parameter can be devised to three sets:

    a. Mandatory parameters that need to be captured in the payment page where the cardholder is entering the card details.

    Field Description Format Mandatory
    browserAcceptHeader Exact content of the HTTP accept headers as sent to the merchant from the Cardholder’s browser. * Length: Variable, maximum 2048 characters
    Type: String
    If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.    		 Yes
    browserColorDepth Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen color Depth property. Data Type: String
    Values accepted:
    1 = 1 bit
    4 = 4 bits
    8 = 8 bits
    15 = 15 bits
    16 = 16 bits
    24 = 24 bits
    32 = 32 bits
    48 = 48 bits    		 Yes
    browserJavaEnabled Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator java Enabled property. Data Type: Boolean
    Values accepted:
    true
    false    		 Yes
    browserLanguage Value representing the browser language as defined in IETF BCP47. Returned from navigator language property. Length: Variable, 1–8 characters
    Data Type: String    		 Yes
    browserScreenHeight Total height of the Cardholder’s screen in pixels. Value is returned from the screen height property. Data Type: Int
    Between 0 and 999999    		 Yes
    browserScreenWidth Total width of the cardholder’s screen in pixels. Value is returned from the screen width property. Data Type: Int
    Between 0 and 999999    		 Yes
    browserTimeZone Time difference between UTC time and the Cardholder browser local time, in minutes. Data Type: Int
    Between -840 and 720    		 Yes
    browserUserAgent Exact content of the HTTP user-agent header. * Length: Variable, maximum 2048 characters Data Type: String
    Note: If the total length of the UserAgent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.    		 Yes
    CN Customer name Length: Variable, maximum 35 characters
    Special characters are allowed, but quotes must be avoided. Most acquirers don’t check the customer name since names can be written in different ways.    		 Yes

    *HTTP_ACCEPT and HTTP_USER_AGENT don't have to be sent with browserAcceptHeader and browserUserAgent, otherwise we will fill it with the browser parameters.

    • All parameter names should be in UPPERCASE (to avoid any case confusion)
    • Please don't forget to calculate the parameters in your SHA signature.

    Please find below a Javascript code example to capture these parameters.

    <script type="text/javascript" language="javascript">

    function createHiddenInput(form, name, value)
    {
    var input = document.createElement("input");
    input.setAttribute("type", "hidden");
    input.setAttribute("name", name);
    input.setAttribute("value", value);
    form.appendChild(input);
    }

    var myCCForms = document.getElementsByName("MyForm");
    if (myCCForms != null && myCCForms.length > 0)
    {
    var myCCForm = myCCForms[0];
    createHiddenInput(myCCForm, "browserColorDepth", screen.colorDepth);
    createHiddenInput(myCCForm, "browserJavaEnabled", navigator.javaEnabled());
    createHiddenInput(myCCForm, "browserLanguage", navigator.language);
    createHiddenInput(myCCForm, "browserScreenHeight", screen.height);
    createHiddenInput(myCCForm, "browserScreenWidth", screen.width);
    createHiddenInput(myCCForm, "browserTimeZone", new Date().getTimezoneOffset());
    }
    </script>

    b. Required additional parameters (cf. Extra request parameters)

    c. Recommended parameters (list of parameters) that if sent will have a positive impact on transaction conversion rates. Based on the information contained in these parameters, a potential frictionless authentication flow may take place, where the cardholder won’t need anymore to authenticate himself and therefore a quicker transaction completing is expected.

    Although these parameters are optional, the major card schemes highly recommend the following parameters to be included in your request, as it will enhance the chance of a frictionless flow:

    ECOM_BILLTO_POSTAL_CITY
    ECOM_BILLTO_POSTAL_COUNTRYCODE
    ECOM_BILLTO_POSTAL_STREET_LINE1
    ECOM_BILLTO_POSTAL_STREET_LINE2
    ECOM_BILLTO_POSTAL_STREET_LINE3
    ECOM_BILLTO_POSTAL_POSTALCODE
    REMOTE_ADDR
    CN
    EMAIL

    Our system receives the card number in your request and checks online whether the card is registered in the VISA/MasterCard/JCB/AmEx directory (registered means that identification is possible for the card number, i.e. the card is a 3-D Secure card).

    2. Based on the schemes directory response and whether additional parameters in 1.c (Recommended parameters - list of parameters) above were provided (given if the cardholder is registered for 3-D Secure), two potential flows are expected if the cardholder is registered:

    2.1. A frictionless flow: The cardholder doesn't physically need to authenticate themselves because the authentication took place in the background without their input. In this case, the liability shift is on the issuing bank.

    2.2. A challenge flow: The cardholder needs to identify himself.

    i. The answer to the DirectLink request contains a specific payment status and an html code that has to be returned to the customer to start the identification process (cf. Additional return fields). The block of html code will automatically start the identification process between the cardholder (customer) and his issuing bank.

    ii. The cardholder identifies himself on the issuing bank’s page.

    iii. Our system receives the identification response from the issuer.

    iv. If the identification was successful, our system will submit the actual financial transaction to the acquirer.

    3. You receive the result of the global identification and online authorisation process via e-Commerce mode feedback channels.

    Understand declined transactions

    PSD2 enhances the transparency of the payment process for you and your customers. This is especially helpful when dealing with status 2 transactions.
    Our feedback parameter CH_AUTHENTICATION_INFO provides you with detailed information from the issuers when they reject your customers' transactions.
    Share this information with your customers to help them understand why their bank declined their transaction.Share this information with your customers to help them understand why their bank declined their transaction. This information might also help you to recover the transaction using our Soft Decline feature.

    To receive CH_AUTHENTICATION_INFO in both the XML response and your redirection URLs, select this parameter in the Back Office via Configuration > Technical information > Transaction feedback > DirectLink > Dynamic parameters and Dynamic e-Commerce parameters respectively. This will also ensure that this information is visible in the transaction overview via Operations > View transactions / Financial history.

    Use CH_AUTHENTICATION_INFO for either possible scenario:

    • If the transaction goes via the frictionless flow, our XML response will contain this parameter. Add the information to your transaction result page accordingly.
    • If the transaction goes via the challenge flow, you receive this parameter via e-Commerce mode feedback channels. As you will not receive the information early enough to modify your redirection URLs accordingly once a transaction is finalised, we recommend flagging "I would like Nexi Payengine to display a short text to the customer on the secure payment page if a redirection to my website is detected immediately after the payment process." in the Back Office via Configuration > Technical information > Transaction feedback > eCommerce > HTTP redirection in the browser. Our platform will then redirect your customers to our intermediate result page showing the information before your customers end up on your redirection URLs eventually.

    Note that not all issuers share information about why they decline transactions. Therefore, in some cases, CH_AUTHENTICATION_INFO is empty.

    Use the following card numbers in our Test environment to simulate an issuer response:
    Amex: 349586710563469
    MasterCard: 5111823134937549
    Visa: 4010759044222272

    Apart from the standard DirectLink parameters, you also need to send the following information:

    Field Description
    FLAG3D

    Fixed value: ‘Y’

    Instructs our system to perform 3-D Secure identification if necessary.
    HTTP_ACCEPT The Accept request header field in the cardholder browser, used to specify certain media types which are acceptable for the response. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. *
    For example:
    Accept: */*
    HTTP_USER_AGENT The User-Agent request-header field in the cardholder browser, containing information about the user agent originating the request. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. *
    For example: User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)
    WIN3DS Way to show the identification page to the customer. Possible values:
    • MAINW: display the identification page in the main window (default value).
    • POPUP: display the identification page in a pop-up window and return to the main window at the end.
    • POPIX: display the identification page in a pop-up window and remain in the pop-up window.
    ACCEPTURL URL of the webpage to show the customer when the payment is authorised. (or waiting to be authorised).
    DECLINEURL URL to which the customer is redirected if the maximum number of failed authorisation attempts has been reached (10 by default, but which can be changed in the Technical Information page, "Global transaction parameters" tab, "Payment retry" section).
    EXCEPTIONURL URL of the webpage to show the customer when the payment result is uncertain.
    PARAMPLUS Field to submit the miscellaneous parameters and their values that you wish to be returned in the post-sale request or final redirection.
    COMPLUS Field to submit a value you wish to be returned in the post-sale request or output.
    LANGUAGE Customer’s language, for example: “en_US”
    Optional
    TP To change the layout of the "order_A3DS" page, you can send a template name/url with this parameter. (go to e-Commerce: Dynamic template).

    *HTTP_ACCEPT and HTTP_USER_AGENT will not need to be sent if send browserAcceptHeader and browserUserAgent.

    For more information, go to Transaction Feedback.

    If the cardholder is not registered, the normal DirectLink response is returned. If the cardholder is registered, the following (additional) fields will be returned:

    Field Description
    STATUS
    		 New value: “46” (waiting for identification)
    HTML_ANSWER

    BASE64 encoded html code to be added in the html page returned to the customer.

    This tag is added as a child of the <ncresponse> global XML tag. The field HTML_Answer field contains HTML code that has to be added in the html page returned to the customer's browser.

    This code will automatically load the issuer bank identification page in a pop-up in the main window, depending on the WIN3DS parameter value.

    To avoid any interference between the html tags included in the content of the HTML_ANSWER XML tag, with the rest of the XML returned as a response to the DirectLink request, the HTML_ANSWER content is BASE64 encoded by our system before returning the response. Consequently, this must be BASE64 DEcoded before it is included in the html page sent to the cardholder.

    For general information about 3-D Secure v2, check out our PSD2 guide.
    Learn here how to implement 3-D Secure safely into the payment process.

    The transaction flow involves the following steps:

    1. Your customers go to your check-out pages and finalises the purchase on your payment page
    2. You send us the order information and payment details via a DirectLink request, containing a number of additional parameters
    3. You receive and XML-response from our platform. It instructs you how to proceed with the payment. Based on the response, these scenarios are possible:
      1. 3-D Secure frictionless flow authentication: Your customers use a 3-D Secure enrolled card. The 3-D Secure v2 parameters in your request prove to be sufficient for the authentication step. Depending on the issuer, our platform might return the additional field HTML_ANSWER and a specific payment status (STATUS=46). HTML_ANSWER contains a BASE-64 encoded code block, featuring an intermediate page (the so-called METHODURL) with information about the status of the request.
        The flow continues at step 8
      2. 3-D Secure challenge flow authentication: Your customers use a 3-D Secure enrolled card. They need to identify themselves as the rightful card owners. The XML contains the additional field HTML_ANSWER and a specific payment status (STATUS=46). HTML_ANSWER contains a BASE-64 encoded code block, featuring a browser redirection to the issuer
    4. Add the decrypted code block from the additional field HTML_ANSWER to your cardholder’s browser. Your cardholder is automatically redirected to her/his issuing bank for authentication
    5. The cardholder identifies herself/himself. Our system receives the result from the issuer
    6. Based on the result, two scenarios are possible:
      • If the identification was unsuccessful, we redirect the card holder to the DECLINEURL, ending the flow. You receive the result via e-Commerce mode feedback channels.
      • If the identification was successful, we submit the actual financial transaction to the acquirer to process the transaction
    7. We return the payment result to you. Depending on the acquirer’s result, we redirect the card holder to either the ACCEPTURL / DECLINEURL / EXCEPTIONURL. You receive the result via e-Commerce mode feedback channels.
    8. If the transaction was successful, you can deliver the goods / services

    DirectLink with 3-D Secure v2 transaction flowThis graph describes the DIRECTLINK (DPR/D3D) + Fraud transaction flow

    Whether a liability shift applies or not if 3-D Secure is not rolled out, depends on your acquirer contract. Therefore, we recommend you check the terms and conditions with your acquirer.

    11.2 Send 3-D Secure v2 request

    To process transactions with 3-D Secure, send a set of mandatory, recommended and optional parameters to our platform.
    These parameters need to be included in the SHA-calculation.

    Capture and send parameters

    You need to capture the 3DS-specific mandatory / recommended / optional parameters on your payment page.
    Find here a Javascript code block you can use to capture the browser information.

    <script type="text/javascript" language="javascript">
    function createHiddenInput(form, name, value)
    {
    var input = document.createElement("input");
    input.setAttribute("type", "hidden");
    input.setAttribute("name", name);
    input.setAttribute("value", value);
    form.appendChild(input);
    }

    var myCCForms = document.getElementsByName("MyForm");
    if (myCCForms != null && myCCForms.length > 0)
    {
    var myCCForm = myCCForms[0];
    createHiddenInput(myCCForm, "browserColorDepth", screen.colorDepth);
    createHiddenInput(myCCForm, "browserJavaEnabled", navigator.javaEnabled());
    createHiddenInput(myCCForm, "browserLanguage", navigator.language);
    createHiddenInput(myCCForm, "browserScreenHeight", screen.height);
    createHiddenInput(myCCForm, "browserScreenWidth", screen.width);
    createHiddenInput(myCCForm, "browserTimeZone", new Date().getTimezoneOffset());
    }
    </script>

    Send these 3-D Secure-specific parameters along with the other DirectLink mandatory parameters. Our platform will process your request and provide you with a response.

    Understand declined transactions

    PSD2 enhances the transparency of the payment process for you and your customers. This is especially helpful when dealing with status 2 transactions.
    Our feedback parameter CH_AUTHENTICATION_INFO provides you with detailed information from the issuers when they reject your customers' transactions.
    Share this information with your customers to help them understand why their bank declined their transaction. This information might also help you to recover the transaction using our Soft Decline feature.

    To receive CH_AUTHENTICATION_INFO in both the XML response and your redirection URLs, select this parameter in the Back Office via Configuration > Technical information > Transaction feedback > DirectLink > Dynamic parameters and Dynamic e-Commerce parameters respectively. This will also ensure that this information is visible in the transaction overview via Operations > View transactions / Financial history.

    Use CH_AUTHENTICATION_INFO for either possible scenario:

    • If the transaction goes via the frictionless flow, our XML response will contain this parameter. Add the information to your transaction result page accordingly.
    • If the transaction goes via the challenge flow, you receive this parameter via e-Commerce mode feedback channels. As you will not receive the information early enough to modify your redirection URLs accordingly once a transaction is finalised, we recommend flagging "I would like Nexi Payengine to display a short text to the customer on the secure payment page if a redirection to my website is detected immediately after the payment process." in the Back Office via Configuration > Technical information > Transaction feedback > eCommerce > HTTP redirection in the browser. Our platform will then redirect your customers to our intermediate result page showing the information before your customers end up on your redirection URLs eventually.

    Note that not all issuers share information about why they decline transactions. Therefore, in some cases, CH_AUTHENTICATION_INFO is empty.

    Use the following card numbers in our Test environment to simulate an issuer response:
    Amex: 349586710563469
    MasterCard: 5111823134937549
    Visa: 4010759044222272

    Process platform response

    If the transaction goes via the frictionless flow, the response contains the standard parameters with the final transaction feedback. This marks the end of the flow.
    If the transaction goes via the challenge flow, the response contains additional parameters. To roll out the authentication to your customers, you need process the additional data provided as described here:

    Field Description
    STATUS New value: “46” (waiting for identification)
    HTML_ANSWER BASE64 encoded html code to be added in the html page returned to the customer.
    This tag is added as a child of the <ncresponse> global XML tag. The field HTML_Answer field contains HTML code that has to be added in the html page returned to the customer's browser.
    This code will automatically load the issuer bank identification page in a pop-up in the main window, depending on the WIN3DS parameter value.
    To avoid any interference between the html tags included in the content of the HTML_ANSWER XML tag, with the rest of the XML returned as a response to the DirectLink request, the HTML_ANSWER content is BASE64 encoded by our system before returning the response. Consequently, this must be BASE64 Decoded before it is included in the html page sent to the cardholder.

    If the identification was unsuccessful, we redirect the card holder to the DECLINEURL, ending the flow. You receive the result via e-Commerce mode feedback channels.

    If the identification was successful, we submit the actual financial transaction to the acquirer.

    Depending on the acquirer’s result, we redirect the card holder to either the ACCEPTURL / DECLINEURL / EXCEPTIONURL. You receive the result via e-Commerce mode feedback channels.

    11.3 Test cards

    You can use the following test card to simulate a 3-D Secure registered card in our test environment:

    Frictionless Flow
    Brand Card number Expiry date
    VISA 4186455175836497 Any date in the future
    Mastercard 5137009801943438 Any date in the future
    American Express 375418081197346 Any date in the future
    Carte Bancaire 4150557357382737 Any date in the future

    Challenge Flow
    Brand Card number Expiry date
    VISA 4874970686672022 Any date in the future
    Mastercard 5130257474533310 Any date in the future
    American Express 379764422997381 Any date in the future
    Carte Bancaire 4150550997933993 Any date in the future

    More test cards numbers can be downloaded here.

    If a transaction is blocked due to incorrect identification, the transaction result will be:

    STATUS = 2

    NCERROR = 40001134

    11.4 Exclusions and exemptions for 3DSv2

    Some transactions are excluded from SCA. If any of your transactions are among them, 3-D Secure will not be rolled out. For more information which type of transaction they are, consult our dedicated guide here. 

    You can request to omit 3-D Secure in two ways

    1. Authentication by selecting the appropriate values for Mpi.threeDSRequestorChallengeIndicator and 3DS_EXEMPTION_INDICATOR
      Parameter Values
      Mpi.threeDSRequestorChallengeIndicator Length: 2 characters
      Data Type: String
      Values accepted:
      • 01 = No preference
      • 02 = No challenge requested - use this value for low amount transactions (below 30 euros)
      • 03 = Challenge requested: merchant Preference
      • 04 = Challenge requested: Mandate - use this value when setting up a recurring transaction with your customer or when retrying the transaction after soft decline
      • 05 = No Challenge Requested [transactional risk analysis is already performed] use this value if your acquirer agreed on TRA exemptions with you
      • 07 = No Challenge Requested [SCA is already Performed] use this value when you do the SCA on your side, has to be approved by your acquirer
      3DS_EXEMPTION_INDICATOR Length: 2 characters
      Data Type: String
      Values accepted:
      • 03 = Issuer TRA*
      • 04 = Low amount exemption (below 30 euros)
      • 05 = Merchant/Acquirer TRA*
      • 06 = White Listing
      • 07 = Corporate
      • 08 = Delayed Shipment
      • 09 = Delegated authentication (certified wallet)


      * Transaction risk analysis

      Check out the authentication log in the Back Office and search for “TransStatus = I” to see if the issuer has granted the exemption. However, you will loose the liability shift in a case of a fraudulent transaction

    2. Authorisation by selecting the appropriate 3DS_EXEMPTION_INDICATOR and FLAG3D
      To skip 3-D secure altogether, send the following parameters:

      Parameter Values
      FLAG3D

      N = Skip the 3DS authentication process
      3DS_EXEMPTION_INDICATOR Length: 2 characters
      Data Type: String
      Values accepted:
      • 03 = Issuer TRA*
      • 04 = Low amount exemption (below 30 euros)
      • 05 = Merchant/Acquirer TRA*
      • 06 = White Listing
      • 07 = Corporate
      • 08 = Delayed Shipment
      • 09 = Delegated authentication (certified wallet)


      * Transaction risk analysis

      However, it is still up to the issuer whether an authentication process must take place. In case the issuer insists on 3DS, the transaction will be declined with error code 40001139.
      If transaction is accepted without 3-D Secure, you will loose the liability protection.

      When your customers are setting up a new recurring payment with you, under the PSD2 rules, the first transaction always have to be strongly authenticated. Submit all the relevant 3DS parameters, COF parameters together with Mpi.threeDSRequestorChallengeIndicator=04. This will make sure that the issuer is aware of this request and will approve the transaction

    Frictionless / challenge flow

    If you do not want to request an exemption but rely on the issuers rolling out a frictionless flow and keep your liability protection, send some additional parameters.
    Sending these parameters for these schemes raise the chance for a frictionless flow:

    • Carte Bancaire (if you are on low risk merchant program, they are strongly required)
      ECOM_BILLTO_POSTAL_CITY
      ECOM_BILLTO_POSTAL_COUNTRYCODE
      ECOM_BILLTO_POSTAL_STREET_LINE1
      ECOM_BILLTO_POSTAL_POSTALCODE
      EMAIL
      Mpi.HomePhone.countryCode
      Mpi.HomePhone.subscriber or Mpi.MobilePhone.subscriber
      Mpi.shippingIndicator
      REMOTE_ADDR

    • MasterCard
      ECOM_BILLTO_POSTAL_CITY
      ECOM_BILLTO_POSTAL_COUNTRYCODE
      ECOM_BILLTO_POSTAL_STREET_LINE1
      ECOM_BILLTO_POSTAL_POSTALCODE
      EMAIL
      Mpi.HomePhone.countryCode
      Mpi.HomePhone.subscriber or Mpi.MobilePhone.subscriber
      ADDMATCH
      REMOTE_ADDR

    You can even increase the chance of a frictionless flow and a higher conversion rate by sending more optional parameters.

    Soft Decline

    A typical flow of a soft declined transaction looks like this:

    1. In your first request, send FLAG3D=N together with the appropriate value for 3DS_EXEMPTION_INDICATOR and no further authentication parameter. This way you indicate that you wish to skip 3-D Secure. The transaction might be accepted already now.
      If it is rejected by your customer’s bank because it insists on 3-D Secure, we will indicate this in the feedback parameter by sending NCERROR=40001139. The transaction will be put in status 2.
    2. To recover this declined transaction, resubmit the transaction by sending the following parameters to our platform
      1. The standard request for e-Commerce / DirectLink parameters as sent in your first request as a new order
      2. FLAG3D=Y to indicate 3-D Secure needs to be rolled out
      3. The 3DSv2 authentication parameters as described here
      4. Mpi.threeDSRequestorChallengeIndicator=04 to indicate that your customer’s bank insists on 3-D Secure following the Soft Decline

    Your customer will have to pass the 3-D Secure authentication during this second request. Finally, the transaction will reach either status 2 or 9. This depends on both whether your customer passed the authentication and the payment is accepted by both your and your customer’s bank.

    Soft Decline is currently available for payment methods Visa, MasterCard, American Express and Carte Bancaire.

    11.5 Move from v2.1 to v2.2

    The upcoming new version of 3-D Secure (v2.2) will provide you with even more possibilities to optimise your integration.

    Parameter Values

    BROWSERJAVASCRIPTENABLED

    This boolean indicates whether your customers have enabled JavaScript in their browsers when making a purchase.

    Depending on its value, the following applies

    • TRUE: the following parameters will remain mandatory

      BROWSERJAVAENABLED
      BROWSERSCREENHEIGHT
      BROWSERSCREENWIDTH
      BROWSERTIMEZONE
      BROWSERACCEPTHEADER
      BROWSERUSERAGENT
      BROWSERLANGUAGE

    • FALSE: the following parameters are not mandatory anymore:
      BROWSERCOLORDEPTH
      BROWSERJAVAENABLED
      BROWSERSCREENHEIGHT
      BROWSERSCREENWIDTH
      BROWSERTIMEZONE

      These parameter remain mandatory:

      BROWSERACCEPTHEADER
      BROWSERUSERAGENT
      BROWSERLANGUAGE

    Data Type: Boolean

    Values accepted:
    • TRUE
    • FALSE

    If you do not send this parameter, we prepopulate this value depending on the other parameters available.
    On top of BROWSERJAVASCRIPTENABLED, v2.2 offers enhanced / new parameters for making your transactions even more secure:

    To process transactions with 3-D Secure, send a set of mandatory and optional parameters to our platform.

    The table gives you an overview on the different parameters and their purpose for the authentication process.
    These parameters need to be included in the SHA-calculation.

    Parameter category Parameter Description / Possible values
    Mandatory

    FLAG3D

    Fixed value: ‘Y’

    Instructs our system to perform 3-D Secure identification if necessary.

    HTTP_ACCEPT*

    The Accept request header field in the cardholder browser, used to specify certain media types which are acceptable for the response. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. *
    For example:
    Accept: */*

    HTTP_USER_AGENT*

    The User-Agent request-header field in the cardholder browser, containing information about the user agent originating the request. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. *

    For example: User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)

    ACCEPTURL

    URL of the webpage to show the customer when the payment is authorised. (or waiting to be authorised).

    DECLINEURL

    URL to which the customer is redirected if the maximum number of failed authorisation attempts has been reached (10 by default, but which can be changed in the Technical Information page, "Global transaction parameters" tab, "Payment retry" section).

    EXCEPTIONURL

    URL of the webpage to show the customer when the payment result is uncertain.

    LANGUAGE

    Customer’s language, for example: “en_US”
    Optional

    TP

    To change the layout of the "order_A3DS" page, you can send a template name/url with this parameter.

    PARAMPLUS

    Field to submit the miscellaneous parameters and their values that you wish to be returned in the post-sale request or final redirection.

    COMPLUS

    Field to submit a value you wish to be returned in the post-sale request or output.

    WIN3DS

    Way to show the identification page to the customer. Possible values:

    • MAINW: display the identification page in the main window (default value)
    • POPUP: display the identification page in a pop-up window and return to the main window at the end
    • POPIX: display the identification page in a pop-up window and remain in the pop-up window

    After sending these parameters, our platform will process your request and provide you with a response

    Process platform response

    If your customer’s card is not registered for 3-D Secure, the response contains the standard parameters with the final transaction feedback. This marks the end of the flow.
    If your customer’s card is registered for 3-D Secure, the response contains additional parameters. To roll out the authentication to your customers, you need process the additional data provided as described here:

    Field Description
    STATUS New value: “46” (waiting for identification)
    HTML_ANSWER BASE64 encoded html code to be added in the html page returned to the customer.
    This tag is added as a child of the <ncresponse> global XML tag. The field HTML_Answer field contains HTML code that has to be added in the html page returned to the customer's browser.
    This code will automatically load the issuer bank identification page in a pop-up in the main window, depending on the WIN3DS parameter value.
    To avoid any interference between the html tags included in the content of the HTML_ANSWER XML tag, with the rest of the XML returned as a response to the DirectLink request, the HTML_ANSWER content is BASE64 encoded by our system before returning the response. Consequently, this must be BASE64 Decoded before it is included in the html page sent to the cardholder.

    If the identification was unsuccessful, we redirect the card holder to the DECLINEURL, ending the flow. You receive the result via e-Commerce mode feedback channels.

    If the identification was successful, we submit the actual financial transaction to the acquirer.

    Depending on the acquirer’s result, we redirect the card holder to either the ACCEPTURL / DECLINEURL / EXCEPTIONURL. You receive the result via e-Commerce mode feedback channels.

    Test cards

    You can use the following test cards to simulate a 3-D Secure registered card in our test environment:

    Brand Card number Expiry date Password
    VISA 4000000000000002 Any date in the future 11111
    MasterCard 5300000000000006 Any date in the future 11111
    American Express 371449635311004 Any date in the future 11111

    More test cards numbers can be downloaded here.

    If a transaction is blocked due to incorrect identification, the transaction result will be:

    STATUS = 2

    NCERROR = 40001134

    FAQs

    In your Nexi Payengine account menu, you can easily lookup your transactions by choosing "Operations" and then clicking either "View transactions" or "Financial history", depending on the type of transaction results you're looking for.

    By default you can send goods or deliver your service once a transaction has reached the status "9 - Payment requested". However, although status 5 is a successful status, it's only a temporary reservation of an amount of money on the customer's card. A transaction in status 5 still needs to be confirmed (manually or automatically) to proceed to the status 9, which is the final successful status for most payment methods.

    You can easily refund a payment with the "Refund" button in the order overview of a transaction (via View transactions). If your account supports it, you can also make refunds with a DirectLink request or with a Batch file upload (for multiple transactions).

    Please note that the Refunds option has to be enabled in your account.

    If you want to check specific details of an order/transaction or perform maintenance on transactions, you should use View transactions. "Financial history" is the most convenient to periodically check incoming and outgoing funds.

    You can only perform refunds on transactions which have already received status 9 for at least 24 hours. A cancellation or deletion can be done within approximately 24 hours after final status has been received (status 9 or 5).

    To know the cut-off time of the acquirer, we recommend you to check directly with our Customer Care department.