1 General procedures and security settings
   1.1 API user
   1.2 Request form
   1.3 Security
      1.3.1 Encryption
      1.3.2 IP address
      1.3.3 SHA signature
   1.4 Response parsing
2 Request a new order
   2.1 Request URL
   2.2 Request parameters
   2.3 Test page
   2.4 Excluding specific payment methods
   2.5 Order request using 3-D Secure
   2.6 Split credit/debit cards
   2.7 Processing transactions with stored credentials
3 Order response
   3.1 Duplicate request
4 Direct Maintenance
   4.1 Maintenance request
      4.1.1 Request URL
      4.1.2 Request parameters
      4.1.3 Test page
   4.2 Maintenance response
   4.3 Duplicate request
5 Direct Query
   5.1 Query request
      5.1.1 Request URL
      5.1.2 Request parameters
      5.1.3 Test page
   5.2 Query response
      5.2.1 Transactions processed with e-Commerce (hosted payment page)
   5.3 Possible response statuses
   5.4 Direct Query as fallback
6 Data Controller privacy policy request
   6.1 Query request
      6.1.1 Request URL
      6.1.2 Request-parameters
      6.1.3 Test-page
   6.2 Query response
7 Payment method exceptions
   7.1 Direct Debits
      7.1.1 Direct Debits AT
      7.1.2 Direct Debits DE (ELV)
      7.1.3 Direct Debits NL
   7.2 Payment methods with only maintenance via DirectLink
8 3-D Secure v1.0
   8.1 Introduzione
   8.2 Flusso della transazione 3-D mediante DirectLink
      8.2.1 Parametri di richiesta aggiuntivi
      8.2.2 Campi restituiti aggiuntivi
      8.2.3 Commenti
9 3-D Secure v2.1
   9.1 Introduction
   9.2 Flusso della transazione 3-D mediante DirectLink
      9.2.1 Parametri di richiesta aggiuntivi
      9.2.2 Campi restituiti aggiuntivi
      9.2.3 3-D Secure v2.1 MasterCard+
      9.2.4 Commenti
   9.3 Esclusioni ed esenzioni del 3DSv2
      9.3.1 3DSv2 ed esclusioni
      9.3.2 SCA e Flusso frictionless / challenge del 3DS
      9.3.3 Indicazione del flusso preferito
      9.3.4 Esenzioni di 3DS

1 General procedures and security settings

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

1.1 API user

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 Ingenico ePayments 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).

1.2 Request form

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.

1.3 Security

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

1.3.1 Encryption

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.

1.3.2 IP address

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.

1.3.3 SHA signature

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 (Ingenico ePayments 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.

1.4 Response parsing

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.

2 Request a new order

2.1 Request URL

  • The request URL in the TEST environment is https://ogone.test.v-psp.com/ncol/test/orderdirect.asp.
  • The request URL in the PRODUCTION environment is https://secure.ogone.com/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.

2.2 Request parameters

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

FieldDescriptionFormatMandatory
PSPID Your affiliation name in our system. AN, 30 Yes
ORDERID Your unique order number (merchant reference). AN, 40 Yes
USERID Name of your application (API) user. Please refer to the User Manager documentation for information on how to create an API user. AN, 20 (min 2) Yes
PSWD Password of the API user (USERID). AN Yes
AMOUNT Amount to be paid, MULTIPLIED BY 100 as the format of the amount must not contain any decimals or other separators. N, 15 Yes
CURRENCY ISO alpha order currency code, for example: EUR, USD, GBP, CHF, etc. AN, 3 Yes
CARDNO Card/account number. AN, 21 Yes
ED Expiry date. MM/YY or MMYY Yes
COM Order description. AN, 100 No
CN Customer name. AN, 35 Yes
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 AN, 50 No
SHASIGN Signature (hashed string) to authenticate the data (see SHA-IN Signature). AN, 128 Yes
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. N, 5 Yes
ECOM_PAYMENT_
CARD_VERIFICATION
Alternative to CVC: date of birth / issue number / etc. (depending on country/bank) N, 5 No
OWNERADDRESS Customer’s street name and number. AN, 50 No
OWNERZIP Customer’s postcode. AN, 10 No
OWNERTOWN Customer’s town/city name. AN, 40 No
OWNERCTY Customer’s country, e.g. BE, NL, FR, etc. AN, 2 No
OWNERTELNO Customer’s telephone number. AN, 30 No
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 Ingenico ePayments 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.
A, 3 Yes
WITHROOT Adds a root element to our XML response. Possible values: ‘Y’ or empty. Y or <empty> No
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'. AN No
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 (!)

N, 2 No
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)
N, 2 No

     


The following parameters are relevant within the scope of the Credential-on-File guideline (COF) by the payment schemes Visa / MasterCard. Detailed information on their usage can be found in dedicated chapter Processing transactions with stored credentials.

FieldDescriptionFormatMandatory
COF_INITIATOR* Credential-on-file initiator
Possible values:
  • CIT: A transaction initiated by a cardholder
  • MIT: A transaction initiated by a merchant
AN No
COF_SCHEDULE* Credential-on-files scheduled (or unscheduled)
Possible values:
  • SCHED: A scheduled transaction
  • UNSCHED: An unscheduled transaction
AN No
COF_TRANSACTION* Credential-on-file transaction
Possible values:
  • FIRST: A scheduled transaction
  • SUBSEQ: Subsequent series of transaction
AN No
COF_RECURRING_EXPIRY* End date : date of the last scheduled payment of a series currently available in TEST only
Date YYYYMMDD (i.e. 20190914)
No
COF_RECURRING_FREQUENCY* Days between payments for a scheduled series. currently available in TEST only
Numeric between 2 and 4 digits (i.e. 31, 031 or 0031)
No

* Please send the parameter values according to the format as defined in the table. Otherwise the transaction will be blocked by our system.

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


Complying with your customer’s choice of brand for co-badged cards

In some cases, a credit card of an international scheme (ie Visa / MasterCard) is also issued for a second, local payment method. Such credit cards are called co-badged cards. 

If you offer local payment methods on top of the international schemes, you need to offer your customers to choose between the brands a co-badged card is issued for.

To do so, make sure that


2.3 Test page

Our test page to send order requests in DirectLink can be found here: https://ogone.test.v-psp.com/ncol/test/testodl.asp.

2.4 Excluding specific payment methods

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.

2.5 Order request using 3-D Secure

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.

2.6 Split credit/debit cards

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 Ingenico ePayments account. Go to Split Credit/Debit Cards for more information.

2.7 Processing transactions with stored credentials

Credential-on-file (COF) transaction uses existing card details that are already stored by merchants to process the payment. Before initiating a credential-on-file (COF) transaction, the cardholder will first need to authorize the merchant to store the card details. Credential-on-file (COF) mostly applies to recurring payments and states whether the payment is initiated by a cardholder or merchant.

There are two types of credential-on-file (COF) transactions: cardholder-initiated transaction (CIT) or merchant-initiated transaction (MIT). Cardholder-initiated transaction (CIT) will always need to take place before initiating merchant-initiated transaction (MIT).

A cardholder-initiated transaction (CIT) is a transaction where the cardholder is involved in the transaction and personally authenticates the transaction, by means of a signature, 3D-Secure appliance, or presenting IDs.

Example of a cardholder-initiated transaction (CIT):

A cardholder buys a train ticket online and makes a payment. He/She makes the payment with his/her credit card and is being asked to authenticate and authorize the payment. At the same, the cardholder is also asked if he/she wants to save the credit card information related to this payment. If the cardholder agrees, this information can then be re-used in future transactions initiated by the merchant.

A merchant-initiated transaction (MIT) is a transaction initiated by a merchant that acts as a follow-up to a cardholder-initiated transaction (CIT) and a pre-agreed standing order for goods and services purchased by the cardholder. The cardholder does not have to be involved in the transaction.

Example of a merchant-initiated transaction (MIT):

A merchant can automatically initiate a transaction to fulfill a cardholder’s payment on a monthly magazine subscription.

In compliance with the regulations set by Visa and MasterCard for credential-on-file (COF) transaction, new parameters need to be sent to determine the COF transaction.

Impacted if:

  • You are using an Alias
  • You plan to initiate recurring transactions (scheduled or not) after initiating a cardholder-initiated transaction (CIT) for the first time

Required action

By default, these parameters are used in a DirectLink Server-to-Server transaction:

Parameter values COF_INITIATOR-COF_TRANSACTION-COF_SCHEDULE

Description

CIT-FIRST-UNSCHED
Applies when an alias is used or created
CIT-FIRST- SCHED

Applies to a first scheduled payment/subscription

MIT-SUBSEQ-UNSCHED Applies when an alias is used or created
MIT-SUBSEQ-SCHED Applies to installment

The default values are flagged if you don't add any parameters. However, if you want to change it, you can overwrite these default values by sending the new parameters. Do not forget to recalculate the SHA signature as well (click here for more information about SHA signature).

Parameters

Values

Description

COF_INITIATOR CIT A transaction initiated by a cardholder
MIT A transaction initiated by a merchant
COF_SCHEDULE
SCHED A scheduled transaction
UNSCHED An unscheduled transaction
COF_TRANSACTION
FIRST First of a series of transactions

SUBSEQ

Subsequent series of transactions

COF_RECURRING_EXPIRY Date YYYYMMDD (i.e. 20190914) End date : date of the last scheduled payment of a series
COF_RECURRING_FREQUENCY numeric between 2 and 4 digits (i.e. 31, 031 or 0031) Days between payments for a scheduled series.

3 Order response

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.

3.1 Duplicate request

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

4 Direct Maintenance

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.

4.1 Maintenance request

4.1.1 Request URL

  • The request URL in the TEST environment is https://ogone.test.v-psp.com/ncol/test/maintenancedirect.asp.
  • The request URL in the PRODUCTION environment is https://secure.ogone.com/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.

4.1.2 Request parameters

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

4.1.3 Test page

You can test direct maintenance requests here: https://ogone.test.v-psp.com/ncol/test/testdm.asp

4.2 Maintenance response

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.

4.3 Duplicate request

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.

5 Direct Query

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

5.1 Query request

5.1.1 Request URL

  • The request URL in the TEST environment is https://ogone.test.v-psp.com/ncol/test/querydirect.asp
  • The request URL in the PRODUCTION environment is https://secure.ogone.com/ncol/prod/querydirect.asp

Change "test" to "prod"

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

5.1.2 Request parameters

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

5.1.3 Test page

You can test direct query requests here: https://ogone.test.v-psp.com/ncol/test/testdq.asp.

5.2 Query response

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.

5.2.1 Transactions processed with e-Commerce (hosted payment page)

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"/>

5.3 Possible response statuses

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

5.4 Direct Query as fallback

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.

6 Data Controller privacy policy request

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.

6.1 Query request

6.1.1 Request URL

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

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

6.1.2 Request-parameters

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.

6.1.3 Test-page

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

6.2 Query response

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.

<?xml version="1.0" encoding="utf-8"?>
<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>

7 Payment method exceptions

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

7.1 Direct Debits

7.1.1 Direct Debits AT

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)

7.1.2 Direct Debits DE (ELV)

The following table contains the specific parameter values allowing the transmission of ELV transactions via DirectLink. (not Wirecard/Billpay)

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

IBAN: 22 alphanumeric characters

OR

Bank account number + BLZ. Format: XXXXXXXXXBLZYYYYYYYY
XXXXXXXXXX: account number, numeric, 1 to 10 digits.
YYYYYYYY: Bank code (Bankleitzahl), 8 digits.
Yes
CN Bank account holder’s name AN, 35 Yes
ED Expiry date „99/99“ oder „9999“ Yes
MANDATEID Unique mandate reference.
Telego:
If not provided, the platform will take the ORDERID or PAYID
Note: If not provided, easycash will generate a value.

Telego: AN, 35 / Charset: “A-Z a-z 0-9 space /-?:().,'+”)
If not provided, the platform will take the ORDERID or PAYID

Easycash: Format: AN, 27 / Charset: “A-Z a-z 0-9 space /-?:().,'+”)
Note: If not provided, easycash will generate a value.

No
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 (*)
No
OWNERADDRESS Account holder's street name and number AN, 50 Yes
OWNERTOWN Account holder's city/town AN, 40 Yes
OWNERZIP Account holder's postal code AN, 10 Yes
PM Payment method

AN, 25

"Direct Debits DE”

Yes

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

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

7.1.3 Direct Debits NL

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.

8 3-D Secure v1.0

8.1 Introduzione

Il protocollo 3-D Secure permette di identificare il titolare della carta durante la procedura d'acquisto. Il titolare della carta deve essere connesso a Internet durante la procedura di identificazione. 3-D Secure non funziona per i call center o per i pagamenti ricorrenti.

Visa ha implementato il protocollo 3-D Secure con il nome Verified By Visa, MasterCard con il nome SecureCode, JCB con il nome J-Secure e American Express con il nome SafeKey.

Lo scopo dell'integrazione di DirectLink con 3-D Secure è di avviare un pagamento in modalità DirectLink e terminarlo in modalità e-Commerce, se è necessaria l'autenticazione del titolare della carta.

Nel presente documento viene spiegata l'integrazione del protocollo 3-D Secure in DirectLink. Per maggiori informazioni relative a DirectLink o e-Commerce, visitare la pagina DirectLink o la documentazione di e-Commerce.

Il flusso della transazione comprende i seguenti passaggi:

  1. Ci inviate una richiesta di transazione DirectLink contenente una serie di parametri aggiuntivi (cfr. Parametri di richiesta aggiuntivi).
  2. Il sistema riceve il numero di carta contenuto nella richiesta e controlla online se la carta è registrata nella directory VISA/MasterCard/JCB/AmEx (per registrata si intende che il numero di carta può essere identificato, quindi che la carta è una carta 3-D Secure).
  3. Se il titolare della carta è registrato, la risposta alla richiesta di DirectLink contiene uno stato di pagamento specifico e un codice html, da restituire al cliente per avviare il processo di identificazione (cfr. Campi restituiti aggiuntivi). Il blocco di codice html avvia automaticamente il processo di identificazione tra il titolare della carta (cliente) e la banca emittente.
  4. Il titolare della carta si identifica sulla pagina della banca emittente.
  5. Il nostro sistema riceve dall'emittente una risposta sull'identificazione.
  6. Se l'identificazione viene superata, il sistema invia all'acquirente la transazione finanziaria effettiva.
  7. Il risultato dell'identificazione globale e del processo di autorizzazione online viene inviato tramite i canali di feedback della modalità e-Commerce.

Commenti:

  • l'eventuale applicabilità del passaggio della responsabilità della transazione dipende dal contratto dell'acquirente. Si consiglia pertanto di verificare i termini e le condizioni con l'acquirente.
  • Se il titolare della carta non è registrato (nel passaggio 3), riceve la risposta XML standard di DirectLink con il risultato del processo di autorizzazione online.
  • Per ricevere lo stato esatto del pagamento e i codici errore (nel passaggio 7), è necessario implementare il feedback post-vendita online o offline, seguendo le istruzioni fornite nella e-Commercedocumentazione.

8.2.1 Parametri di richiesta aggiuntivi

Oltre ai parametri standard di DirectLink, è necessario inviare i seguenti dati:

Campo Descrizione
FLAG3D

Valore fisso: ‘Y’

Indica il nostro sistema come eseguire un'identificazione 3-D Secure, se necessario.

HTTP_ACCEPT Campo richiesta-intestazione Accetto nel browser del titolare della carta, utilizzato per specificare alcuni tipi di supporti accettati per la risposta. Questo valore è utilizzato dall'emittente per controllare se il browser del titolare della carta è compatibile con il sistema di identificazione dell'emittente. Ad esempio:
Accetto: */*
HTTP_USER_AGENT Campo richiesta-intestazione Utente-Agente nel browser del titolare della carta, contenente informazioni sull'agente utente che genera la richiesta. Questo valore è utilizzato dall'emittente per controllare se il browser del titolare della carta è compatibile con il sistema di identificazione dell'emittente. Ad esempio: Agente utente: Mozilla/4.0 (compatibile, MSIE 6.0, Windows NT 5.0)
WIN3DS Un modo per mostrare al cliente la pagina di identificazione. Valori possibili:
  • MAINW: consente di visualizzare la pagina di identificazione nella finestra principale (valore predefinito).
  • POPUP: consente di visualizzare la pagina di identificazione nella finestra di popup e alla fine di tornare alla finestra principale.
  • POPIX: consente di visualizzare la pagina di identificazione nella finestra di popup e di rimanere nella finestra di popup.
ACCEPTURL URL della pagina Web da mostrare al cliente quando il pagamento è stato autorizzato (o è in attesa di autorizzazione).
DECLINEURL URL al quale viene reindirizzato il cliente al raggiungimento del numero massimo di tentativi di autorizzazione falliti (10 per impostazione predefinita, sebbene il valore possa essere modificato nella pagina Technical Information, nella sezione "Payment retry" della scheda "Global transaction parameters").
EXCEPTIONURL URL della pagina Web da mostrare al cliente se il risultato del pagamento è incerto.
PARAMPLUS Campo in cui inserire vari parametri e i relativi valori che si desidera ricevere nella richiesta post vendita o nel reindirizzamento finale.
COMPLUS Campo in cui inserire un valore che si desidera ricevere nella richiesta post vendita o nell'output.
LANGUAGE Lingua del cliente, ad esempio: “en_US”
Facoltativo
TP Per modificare il layout della pagina "order_A3DS", è possibile inviare un URL/nome di modello con questo parametro. (vedere e-Commerce: Modello dinamico).

Per maggiori informazioni, vedere Feedback sulla transazione.

8.2.2 Campi restituiti aggiuntivi

Se il titolare della carta non è registrato, viene restituita la normale risposta di DirectLink. Se il titolare della carta è registrato, vengono restituiti i seguenti campi (aggiuntivi):

Campo Descrizione
STATUS
Nuovo valore: “46” (in attesa di identificazione)
HTML_ANSWER

Codice html con codifica BASE64 da aggiungere alla pagina html restituita al cliente.

Il tag viene aggiunto come elemento secondario del tag XML globale <ncresponse>. Il campo HTML_Answer contiene un codice HTML da aggiungere alla pagina html restituita al browser del cliente.

Il codice carica automaticamente la pagina identificativa della banca emittente in un popup nella finestra principale, in base al valore del parametro WIN3DS.

Per evitare interferenze tra i tag html inclusi nel contenuto del tag XML HTML_ANSWER, insieme al resto del codice XML restituito come risposta alla richiesta di DirectLink, il contenuto HTML_ANSWER viene codificato con BASE64 dal sistema prima che venga restituita la risposta. Di conseguenza, questo deve essere decodificato con BASE64 prima di essere incluso nella pagina html inviata al titolare della carta.

8.2.3 Commenti

Carte di prova

È possibile usare le seguenti carte di prova per simulare una carta registrata 3-D Secure nel nostro ambiente di prova:

Marchio Numero carta Data di scadenza Password
VISA 4000000000000002 Qualsiasi data futura 11111
MasterCard 5300000000000006 Qualsiasi data futura 11111
American Express 371449635311004 Qualsiasi data futura 11111
Identificazione errata

Se una transazione è bloccata a causa di un errore di identificazione, il risultato della transazione sarà:

STATUS = 0

NCSTATUS = 5

NCERROR = 40001134

9 3-D Secure v2.1

9.1 Introduction

In 2013, la Commissione Europea ha pubblicato una proposta per la versione rivisitata della Direttiva sui servizi di pagamento, nota come PSD2 per semplificare l'elaborazione dei pagamenti e creare le regole e i regolamenti dei servizi di pagamento nell'UE e da allora è nata la necessità di una nuova versione di 3-D Secure, v2.1.

La modifica maggiore consiste nel richiedere ai commercianti di condividere un maggior numero di dati: gli emittenti hanno bisogno di punti dati per migliorare la precisione delle loro decisioni e giungere a uno scenario privo di attriti. Ma siete voi quelli in prima linea nella cattura dei dati. L'approccio di 3DS v2 alla valutazione del rischio è più efficace, ma richiede la modifica dell'intero ecosistema per poter inviare i dati fino all'emittente.

Con l'introduzione di queste nuove regole, i principali reti di carte de pagamento hanno aggiornato il loro logo 3DS. Se sei integrato in DirectLink, significa che gestisci la tua pagina di pagamento, e per questo assicurati di implementare questi nuovi loghi (Visa / Mastercard / JCB /… ).

9.2 Flusso della transazione 3-D mediante DirectLink

Il flusso delle transazioni implica i passi seguenti:

1. Si invia la richiesta DirectLink della transazione, contenente un certo numero di parametri aggiuntivi.

Tali parametri sono organizzati in tre gruppi:

a. Parametri obbligatori da catturare nella pagina di pagamento in cui il titolare della carta sta inserendo i dettagli della carta.

ParametriDescrizioneFormatObbligante
browserAcceptHeader Il contenuto esatto dell’HTTP accetta intestazioni come inviate al commerciante dal browser del titolare di carta di credito. * Tipo dati: String Lunghezza: Variabile, massimo 2.048 caratteri
Valore accettato: Se la lunghezza totale dell’intestazione inviata dal browser supera i 2.048 caratteri, il server 3DS
tronca la porzione in eccesso.
browserColorDepth Valore che rappresenta la profondità in bit della palette di colori per le immagini, in bit per pixel. Ottenuto dal browser del titolare di carta di credito usando la proprietà di profondità del colore dello schermo. Tipo dati: Stringa
Valori accettati:
1 = 1 bit
4 = 4 bit
8 = 8 bit
15 = 15 bit
16 = 16 bit
24 = 24 bit
32 = 32 bit
48 = 48 bit
browserJavaEnabled Booleano che rappresenta la capacità del browser del titolare di carta di credito di eseguire Java. Il valore è restituito dalla proprietà di abilitazione Java del navigatore. Tipo dati: Booleano
Valori accettati:
true
false
browserLanguage Valore che rappresenta la lingua del browser, come definita nel codice IETF BCP47. Restituito dalla proprietà della lingua del navigatore. Tipo dati: Stringa
Lunghezza: Variabile, 1-8 caratteri
browserScreenHeight Altezza totale dello schermo del titolare di carta di credito in pixel. Il valore è restituito dalla proprietà dell’altezza dello schermo. Tipo dati: Int
Tra 0 e 999999
browserScreenWidth Larghezza totale dello schermo del titolare di carta di credito in pixel. Il valore è restituito dalla proprietà della larghezza dello schermo. Tipo dati: Int
Tra 0 e 999999
browserTimeZone Differenza oraria tra l’orario UTC e l’ora locale del browser del titolare di carta di credito, in minuti. Tipo dati: Int Tra -840 e 720
browserUserAgent Contenuto esatto dell’intestazione user-agent HTTP. * Tipo dati: Stringa
Lunghezza: Variabile, massimo 2.048
caratteri
Nota: se la lunghezza totale
dell’user-agent inviato dal browser
supera i 2.048 caratteri, il server 3DS
tronca la porzione in eccesso.
CN Nome del titolare di carta di credito (cliente) Lunghezza: Variabile, massimo 35
Sono ammessi caratteri speciali, ad
eccezione delle virgolette. La maggior
parte degli acquirenti non controlla il
nome del cliente poiché i nomi
possono essere scritti in modi diversi

*HTTP_ACCEPT e HTTP_USER_AGENT non devono essere inviati con browserAcceptHeader e browserUserAgent; diversamente, lo compileremo con i parametri del browser.

Nota: non dimenticare di calcolare i parametri nella firma SHA.

Di seguito è disponibile un esempio di codice Javascript per l’acquisizione di tali parametri.

<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. Parametri aggiuntivi necessari (cfr. Parametri di richiesta aggiuntivi).

c. Parametri opzionali ma consigliati (elenco di parametri) che se inviati avranno influenza positiva sulle velocità di conversione della transazione. In base alle informazioni contenute in tali parametri si potrebbe generare un possibile flusso di autenticazione senza attriti, in cui il titolare della carta non avrà più bisogno di autenticarsi e perciò ci si aspetta un completamento più veloce della transazione. In caso contrario, se non si fornisce nessuno di tali parametri avrà luogo il reindirizzamento relativo alla normale autenticazione.

Sebbene questi parametri siano opzionali, i principali schemi di carte raccomandano vivamente di includere nella richiesta i seguenti parametri, poiché ciò aumenterà le possibilità di un Flusso senza attrito.

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

Il sistema riceve il numero di carta contenuto nella richiesta e controlla online se la carta è registrata nella directory VISA/MasterCard/JCB/AmEx (per registrata si intende che il numero di carta può essere identificato, quindi che la carta è una carta 3-D Secure).

2. In base alla risposta della directory degli schemi, se il titolare della carta è registrato in 3-D Secure e in caso siano stati forniti i parametri aggiuntivi 1.c (Parametri opzionali ma consigliati-elenco di parametri) precedenti si potranno avere due possibili flussi:

2.1. Flusso senza attriti: Il titolare della carta non ha fisicamente bisogno di autenticarsi perché l'autenticazione è avvenuta in background senza il loro contributo. In questo caso, lo spostamento di responsabilità è sulla banca emittente.

2.2. Flusso difficile: Il titolare della carta dovrà autenticarsi ulteriormente.

i. La risposta alla richiesta di DirectLine contiene lo stato di pagamento specifico e il codice html che deve essere fatto tornare al cliente per iniziare il processo di identificazione (vedi i campi aggiuntivi di ritorno). Il blocco del codice html inizia automaticamente il processo di identificazione tra il titolare della carta (il cliente) e la sua banca emittente.

ii. Il titolare della carta si identifica sulla pagina della banca emittente.

iii. Il nostro sistema riceve dall'emittente una risposta sull'identificazione.

iv. Se l'identificazione viene superata, il sistema invia all'acquirente la transazione finanziaria effettiva.

3. Il risultato dell'identificazione globale e del processo di autorizzazione online viene inviato tramite i canali di feedback della modalità e-Commerce.

9.2.1 Parametri di richiesta aggiuntivi

Oltre ai parametri standard di DirectLink, è necessario inviare i seguenti dati:

Campo Descrizione
FLAG3D

Valore fisso: ‘Y’

Indica il nostro sistema come eseguire un'identificazione 3-D Secure, se necessario.

HTTP_ACCEPT Campo richiesta-intestazione Accetto nel browser del titolare della carta, utilizzato per specificare alcuni tipi di supporti accettati per la risposta. Questo valore è utilizzato dall'emittente per controllare se il browser del titolare della carta è compatibile con il sistema di identificazione dell'emittente. *
Ad esempio:
Accetto: */*
HTTP_USER_AGENT Campo richiesta-intestazione Utente-Agente nel browser del titolare della carta, contenente informazioni sull'agente utente che genera la richiesta. Questo valore è utilizzato dall'emittente per controllare se il browser del titolare della carta è compatibile con il sistema di identificazione dell'emittente. *
Ad esempio: Agente utente: Mozilla/4.0 (compatibile, MSIE 6.0, Windows NT 5.0)
WIN3DS Un modo per mostrare al cliente la pagina di identificazione. Valori possibili:
  • MAINW: consente di visualizzare la pagina di identificazione nella finestra principale (valore predefinito).
  • POPUP: consente di visualizzare la pagina di identificazione nella finestra di popup e alla fine di tornare alla finestra principale.
  • POPIX: consente di visualizzare la pagina di identificazione nella finestra di popup e di rimanere nella finestra di popup.
ACCEPTURL URL della pagina Web da mostrare al cliente quando il pagamento è stato autorizzato (o è in attesa di autorizzazione).
DECLINEURL URL al quale viene reindirizzato il cliente al raggiungimento del numero massimo di tentativi di autorizzazione falliti (10 per impostazione predefinita, sebbene il valore possa essere modificato nella pagina Technical Information, nella sezione "Payment retry" della scheda "Global transaction parameters").
EXCEPTIONURL URL della pagina Web da mostrare al cliente se il risultato del pagamento è incerto.
PARAMPLUS Campo in cui inserire vari parametri e i relativi valori che si desidera ricevere nella richiesta post vendita o nel reindirizzamento finale.
COMPLUS Campo in cui inserire un valore che si desidera ricevere nella richiesta post vendita o nell'output.
LANGUAGE Lingua del cliente, ad esempio: “en_US”
Facoltativo
TP Per modificare il layout della pagina "order_A3DS", è possibile inviare un URL/nome di modello con questo parametro. (vedere e-Commerce: Modello dinamico).

*HTTP_ACCEPT e HTTP_USER_AGENT non dovranno essere inviati se vengono inviati browserAcceptHeader e browserUserAgent.

Per maggiori informazioni, vedere Feedback sulla transazione.

9.2.2 Campi restituiti aggiuntivi

Se il titolare della carta non è registrato, viene restituita la normale risposta di DirectLink. Se il titolare della carta è registrato, vengono restituiti i seguenti campi (aggiuntivi):

Campo Descrizione
STATUS
Nuovo valore: “46” (in attesa di identificazione)
HTML_ANSWER

Codice html con codifica BASE64 da aggiungere alla pagina html restituita al cliente.

Il tag viene aggiunto come elemento secondario del tag XML globale <ncresponse>. Il campo HTML_Answer contiene un codice HTML da aggiungere alla pagina html restituita al browser del cliente.

Il codice carica automaticamente la pagina identificativa della banca emittente in un popup nella finestra principale, in base al valore del parametro WIN3DS.

Per evitare interferenze tra i tag html inclusi nel contenuto del tag XML HTML_ANSWER, insieme al resto del codice XML restituito come risposta alla richiesta di DirectLink, il contenuto HTML_ANSWER viene codificato con BASE64 dal sistema prima che venga restituita la risposta. Di conseguenza, questo deve essere decodificato con BASE64 prima di essere incluso nella pagina html inviata al titolare della carta.

9.2.3 3-D Secure v2.1 MasterCard+

Per massimizzare la possibilità di un frictionless flow, MasterCard ha sviluppato l’estensione specifica “MasterCard 2.1+”. Ciò significa che puoi inviare altri tre parametri oltre ai parametri raccomandati.

ParametroNomeDescrizioneFormato
Mpi.merchantFraudRate Tasso di frode commerciale Tasso di frode commerciale nel SEE (tutte le frodi relative alle carte SEE divise per tutti i volumi delle carte SEE) calcolato secondo Standard tecnici normativi (RTS) PSD2.

Assicurati di calcolare il tasso in base al regolamento dell’articolo 19 RTS PSD2, in quanto né MasterCard né noi convalideremo il punteggio.

Lunghezza: massimo 2 caratteri
Formato: intero 1=> 99
Valori accettati:

  • 1 (rappresenta un tasso di frode inferiore o uguale a 1 punto base [bp], pari allo 0,01%)
  • 2 (rappresenta un tasso di frode tra 1 bp + - e 6 bp)
  • 3 (rappresenta un tasso di frode tra 6 bp + - e 13 bp)
  • 4 (rappresenta un tasso di frode tra 13 bp + - e 25 bp)
  • 5 (rappresenta un tasso di frode superiore a 25 bp)

Mpi.secureCorporatePayment Pagamento aziendale sicuro Indica che sono stati utilizzati processi e procedure di pagamento dedicati e che si applica la potenziale esenzione di pagamento aziendale sicuro.
Invia questo campo solo con S se il campo di esenzione dell’acquirente è vuoto, poiché
l’esenzione dell’acquirente e il pagamento sicuro si escludono a vicenda.
Tuttavia, il server di directory (DS) non convaliderà le condizioni nell’estensione. Il DS trasferisce i dati così come inviati.
Puoi facoltativamente indicare se si applicano ai processi e ai protocolli dedicati di cui all’articolo 17 RTS di PSD2, che consentirebbe potenzialmente all’emittente di richiedere l’esenzione del pagamento aziendale sicuro.

Lunghezza: massimo 1 carattere
Formato accettato: booleano
Valore accettato:

  • Y
  • N
Mpi.threeDSRequestorChallengeIndicator Indicatore verifica commerciante Indica se hai richiesto una verifica per questa transazione. Ad esempio:
Per 01-PA, potresti nutrire dubbi su una transazione e ne richiedi la verifica.
Per 02-NPA, una verifica potrebbe essere richiesta quando si aggiunge una nuova carta al portafoglio.

Per autorizzazioni locali/regionali o altre variabili.

Lunghezza: 2 caratteri
Tipo di dati: stringa
Valori accettati:

  • 01 = Nessuna preferenza
  • 02 = Nessuna verifica richiesta
  • 03 = Verifica richiesta: preferenza del commerciante
  • 04 = Verifica richiesta: autorizzazione
  • 05 = Nessuna verifica richiesta [analisi di rischio della transazione già eseguita]
  • 06 = Nessuna verifica richiesta [solo condivisione dati]
  • 07 = Nessuna verifica richiesta [SCA già eseguita]
  • 80-99 = Riservato per l’utilizzo DS

L’invio di questi parametri fornirà a tutte le parti interessate molte più informazioni. Ciò non solo comporterà un numero maggiore di flusso senza attriti, ma anche tassi di approvazione più elevati e meno casi di frode.
Nota: questi parametri aggiuntivi funzionano solo con le transazioni MasterCard. Usarli con qualsiasi altro metodo di pagamento non avrà alcun effetto.

9.2.4 Commenti

Carte di prova

È possibile usare le seguenti carte di prova per simulare una carta registrata 3-D Secure nel nostro ambiente di prova:

Flusso senza attriti
Marchio Numero carta Data di scadenza
VISA 4186455175836497 Qualsiasi data futura
Mastercard
5137009801943438 Qualsiasi data futura
American Express
375418081197346 Qualsiasi data futura

Flusso difficile

Marchio Numero carta Data di scadenza
VISA 4874970686672022 Qualsiasi data futura
Mastercard
5130257474533310 Qualsiasi data futura
American Express
379764422997381 Qualsiasi data futura

Nota: è possibile scaricare più numeri di schede di prova qui.

Identificazione errata

Se una transazione è bloccata a causa di un errore di identificazione, il risultato della transazione sarà:

STATUS = 0

NCSTATUS = 5

NCERROR = 40001134

9.3 Esclusioni ed esenzioni del 3DSv2

9.3.1 3DSv2 ed esclusioni

Con l’introduzione del 3DSv2, l’autenticazione del titolare della carta diventerà obbligatoria per tutti, come definito dalla Seconda direttiva sui servizi di pagamento (2015/2366 PSD2) dell’UE. Tuttavia alcune transazioni sono escluse da questa regola, in presenza dei casi seguenti:

  • Ordini per posta/ordini telefonici
  • Il PSP del beneficiario (ovvero l’acquirente del commerciante) o il PSP del pagatore (ovvero l’emittente del metodo di pagamento dell’acquirente) si trova fuori dalla zona SEE (Spazio Economico Europeo)
  • Carte di pagamento prepagate anonime fino a 150 € (articolo 63)
  • MIT - Merchant Initiated Transactions


9.3.2 SCA e Flusso frictionless / challenge del 3DS

La SCA (Strong Customer Authentication, richiesta di autenticazione forte) fa parte di questo nuovo regolamento. Questa implica la possibilità che l’emittente (la banca del titolare della carta) richieda ulteriori informazioni al titolare della carta. In questo caso il processo di autenticazione condurrà al Flusso challenge (procedura che richiede al titolare della carta di autenticarsi attivamente) invece che al Flusso frictionless (procedura senza autenticazione del titolare della carta).

Ma ai nostri commercianti consentiamo di indicare il flusso preferito. Per far ciò, si inviano parametri aggiuntivi che saranno utilizzati dall’emittente per la valutazione del rischio. In base alla decisione dell’emittente, si potrà eseguire il Flusso frictionless. In alcuni casi, se si applicano specifiche esenzioni si potrebbe anche saltare completamente il 3DS.

9.3.3 Indicazione del flusso preferito

Per indicare la preferenza del Flusso frictionless durante la richiesta di autenticazione, il commerciante potrà inviare il parametro aggiuntivo Mpi.threeDSRequestorChallengeIndicator. In base alla valutazione del commerciante sui rischi di frode, si potranno inviare gli specifici valori (per es. valutazione di basso rischio: 02, rischio di frode aumentato: 03)

Parametro Valori Obbligatorio / Opzionale
Mpi.threeDSRequestorChallengeIndicator 01 = Nessuna preferenza
02 = Nessuna verifica richiesta
03 = Verifica richiesta: preferenza
del commerciante
04 = Verifica richiesta: Autorizzazione
Obbligatorio ( nel caso di una preferenza per un flusso specifico)

Il commerciante può aumentare ancora la possibilità del rapporto Flusso frictionless / conversione, inviando altri campi opzionali.

9.3.4 Esenzioni di 3DS

In alcune transazioni il commerciante potrebbe saltare il 3DS (permettendo il Flusso frictionless) e passare direttamente all’autorizzazione. Questo processo è limitato alle transazioni che sono escluse dalla SCA (come descritto precedentemente) o che possono beneficiare di specifiche esenzioni. Tali esenzioni devono far parte di un accordo tra il commerciante e il suo acquirente. In questi casi, il commerciante indicherà di saltare il processo di autenticazione inviando questi parametri aggiuntivi:

Parametro Valori Obbligatorio / Opzionale
FLAG3D N = Salto del processo di autenticazione 3DS Obbligatorio (in caso di salto del 3DS)
3DS_EXEMPTION_INDICATOR Fornire giustificazioni al salto del 3DS. I valori numerici sono applicabili in base alla transazione

03 = TRA* emittente
04 = esenzione per bassi importi
05 = TRA* Commerciante / Acquirente
06 = Whitelisting
07 = Corporate
08 = Spedizione ritardata
09 = Autenticazione ritardata (portafoglio certificato)
Obbligatorio (in caso di salto del 3DS)
* Analisi rischio della transazione

Ma sarà sempre l’emittente a decidere se si dovrà eseguire il processo di autenticazione. Se l’emittente insiste sul 3DS, la transazione viene rifiutata.