1. Home
2. Integration Solutions
3. Integrations
4. Integrate with Payglobe DirectLink (server-to-server)

1. Introduction

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

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

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

2.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 Payglobe 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.

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

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

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

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

2.3.2 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 (Payglobe 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.

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

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

3. Request a new order

3.1 Request URL

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

3.2 Request parameters

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

     


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

3.3 Test page

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

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

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

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

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

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

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

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

5.1 Maintenance request

5.1.1 Request URL

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

5.1.2 Request parameters

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

Field	Description
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: 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

5.1.3 Test page

You can test direct maintenance requests here: https://test-securepay.eupayglobe.com/ncol/test/testdm.asp

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

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

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

6.1 Query request

6.1.1 Request URL

• The request URL in the TEST environment is https://test-securepay.eupayglobe.com/ncol/test/querydirect.asp
• The request URL in the PRODUCTION environment is https://securepay.eupayglobe.com/ncol/prod/querydirect.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 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

6.1.3 Test page

You can test direct query requests here: https://test-securepay.eupayglobe.com/ncol/test/testdq.asp.

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

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

6.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:

Status	NCERROR	NCSTATUS	Description
88			The query on querydirect.asp failed

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

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

7.1 Query request

7.1.1 Request URL

• The request URL in the TEST environment is

Change "test" to "prod"

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

7.1.3 Test-page

You can test direct query requests here:

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

8. Payment method exceptions

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

8.1 Direct Debits

8.1.1 Direct Debits AT

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

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

8.1.2 Direct Debits DE (ELV)

8.1.3 Direct Debits NL

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

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.

8.2 Payment methods with only maintenance via DirectLink

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.

9. 3-D Secure v1.0

9.1 Introduction

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.

9.2 3-D transaction flow via DirectLink

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.

9.2.1 Extra request parameters

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.

9.2.2 Additional return fields

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.

9.2.3 Comments

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

10. 3-D Secure v2.1

10.1 Introduction

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

10.2 3-D transaction flow via DirectLink

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.

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.

10.2.1 Extra request parameters

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.

10.2.2 Additional return fields

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.

10.2.3 3-D Secure v2.1 MasterCard+

To maximize the chance of a frictionless flow, MasterCard has developed the specific extension “MasterCard 2.1+”. That means that you can send three more parameters on top of the recommended parameters.

Parameter	Name	Description	Format
Mpi.merchantFraudRate	Merchant Fraud Rate	Merchant fraud rate in the EEA (all EEA card fraud divided by all EEA card volumes) calculated as per PSD2 Regulatory Technical Standards (RTS). Make sure to calculate the rate according to PSD2 RTS Article 19 regulation, as neither MasterCard nor we will validate the score.	Length: max 2 characters Format: integer 1=> 99 Values accepted 1 (represents fraud rate less than or equal to 1 basis point [bp], which is 0.01%) 2 (represents fraud rate between 1 bp + - and 6 bps) 3 (represents fraud rate between 6 bps + - and 13 bps) 4 (represents fraud rate between 13 bps + - and 25 bps) 5 (represents fraud rate greater than 25 bps)
Mpi.secureCorporatePayment	Secure Corporate Payment	Indicates  that dedicated payment processes and procedures were used and that potential secure corporate payment exemption applies. Send this field only with Y if the acquirer exemption field is blank, as acquirer exemption and secure payment are mutually exclusive. However, the directory server (DS) will not validate the conditions in the extension. The DS will pass data as sent. You can optionally indicate if they apply to the dedicated processes and protocols as per PSD2 RTS Article 17, which would potentially allow the issuer to claim the secure corporate payment exemption.	Length: max 1 character Format accepted: bolean Value accepted: Y N
Mpi.threeDSRequestorChallengeIndicator	Merchant Challenge Indicator	Indicates whether you request a challenge for this transaction. For example: For 01-PA, you may have concerns about the transaction, and request a challenge. For 02-NPA, a challenge may be necessary when adding a new card to a wallet. For local/regional mandates or other variables.	Length: 2 characters Data Type: String Values accepted: 01 = No preference 02 = No challenge requested 03 = Challenge requested: merchant Preference 04 = Challenge requested: Mandate 05 = No Challenge Requested [transactional risk analysis is already performed] 06 = No Challenge Requested [Data share only] 07 = No Challenge Requested [SCA is already Performed] 80-99 = Reserved for DS use

Sending these parameters will provide all parties involved with much more information. This will not only lead to more frictionless flows, but also to higher approval rates and less fraud cases.
Please note that these additional parameters are only working with MasterCard transactions. Using them with any other payment method will not have any effect

10.2.4 Comments

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

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

Note: More test cards numbers can be downloaded here.

Incorrect identification

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

STATUS = 0

NCSTATUS = 5

NCERROR = 40001134

10.3 Exclusions and exemptions for 3DsV2

10.3.1 3DSv2 and exclusions

With the introduction of 3DSv2, card holder authentication will generally become mandatory as defined by the EU’s Second Payment Services Directive (2015/2366 PSD2). Nevertheless, some transactions are excluded from this rule if one of the following scenarios applies:

• Mail order/telephone order
• One leg journey - Payee's PSP (aka Merchant's acquirer) or Payer's PSP (aka Buyer's payment method issuer) is outside of EEA zone
• Anonymous prepaid cards up to 150€ (article 63)
• MIT - merchant initiated transactions

10.3.2 SCA and 3DS frictionless / challenge flow

Part of this new regulation is the Strong Customer Authentication (SCA). This involves the possibility that the issuer (the card holder’s bank) will ask additional information from the card holder. In such a scenario the authentication process will result in a challenge flow (requiring the card holder to actively authenticate) instead of a frictionless flow (requiring no authentication by the card holder).

However, we offer our merchants the possibility to indicate the preferred flow. This can be achieved by sending additional parameters which will be used by the issuer for risk assessment. Depending on the issuer’s decision, a frictionless flow might take place. In some scenarios 3DS might even be skipped altogether if specific exemptions apply.

10.3.3 Indication of the preferred flow

To indicate the preference for a frictionless flow during the authentication request, the merchant may send the additional parameter Mpi.threeDSRequestorChallengeIndicator. Depending on the merchant’s assessment of the risk of fraud, specific values may be sent (i.e. for low risk assessment: 02, for an increased risk of fraud: 03

Parameter	Values	Mandatory / Optional
Mpi.threeDSRequestorChallengeIndicator	01 = No preference 02 = No challenge requested 03 = Challenge requested: merchant Preference 04 = Challenge requested: Mandate	Mandatory (in case for a preference for a specific flow)

The merchant can further raise the chance of a frictionless flow / conversion rate by sending more optional fields.

10.3.4 Exemptions of 3DS

For some transactions, the merchant might be able to skip 3DS (resulting in a frictionless flow) and go for the authorization directly. This process is limited to transactions which are either excluded from SCA (as described above) or which can benefit from specific exemptions. These exemptions need to be part of an agreement between the merchant and his / her acquirer. In a scenario like this, the merchant will indicate to skip the authentication process by sending these additional parameters:

Parameter	Values	Mandatory / Optional
FLAG3D	N = Skip the 3DS authentication process	Mandatory (in case 3DS should be skipped)
3DS_EXEMPTION_INDICATOR	03 = Issuer TRA* 04 = Low amount exemption 05 = Merchant/Acquirer TRA* 06 = White Listing 07 = Corporate 08 = Delayed Shipment 09 = Delegated authentication (certified wallet)	Mandatory (in case 3DS should be skipped)

* Transaction risk analysis

However, it is still up to the issuer whether an authentication process has to take place. In case the issuer insists on 3DS, the transaction will be declined.