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. 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 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 |
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:
Optional:
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: 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
|
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”?> |
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
|
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.
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.
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 |
The following are two successful examples:
- 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> - 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:
|
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:
|
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):
|
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. Secure payment with 3-D Secure
For general information about 3-D Secure v2, check out our PSD2 guide.
Learn here how to implement 3-D Secure safely into the payment process.
9.1 DirectLink 3-D Secure v2 transaction flow
The transaction flow involves the following steps:
- Your customer goes to your check-out pages and finalises the purchase on your payment page
- You send us the order information and payment details via a DirectLink request, containing a number of additional parameters
- 2' Optional: We perform a Fraud check
- You receive and XML-response from our platform. Two scenarios are possible:
- If the transaction goes via the frictionless flow, the response contains the standard parameters with the final transaction feedback. This marks the end of the flow
- If the transaction goes via the challenge flow, the response contains the additional field HTML_ANSWER and a specific payment status (STATUS=46). HTML_ANSWER contains a BASE-64 encoded code block
- Add the decrypted code block to your cardholder’s browser. Your cardholder is automatically redirected to her/his issuing bank for authentication
- The cardholder identifies herself/himself. Our system receives the result from the issuer
- Based on the result, two scenarios are possible:
- If the identification was unsuccessful, we redirect the card holder to the DECLINEURL, ending the flow. You receive the result via e-Commerce mode feedback channels.
- If the identification was successful, we submit the actual financial transaction to the acquirer to process the transaction
- We return the payment result to you. Depending on the acquirer’s result, we redirect the card holder to either the ACCEPTURL / DECLINEURL / EXCEPTIONURL. You receive the result via e-Commerce mode feedback channels.
- If the transaction was successful, you can deliver the goods / services
This graph describes the DIRECTLINK (DPR/D3D) + Fraud transaction flow
Whether a liability shift applies or not if 3-D Secure is not rolled out, depends on your acquirer contract. Therefore, we recommend you check the terms and conditions with your acquirer. |
9.2 Send 3-D Secure v2 request
To process transactions with 3-D Secure, send a set of mandatory, recommended and optional parameters to our platform.
These parameters need to be included in the SHA-calculation.
Capture and send parameters
You need to capture the 3DS-specific mandatory / recommended / optional parameters on your payment page.
Find here a Javascript code block you can use to capture the browser information.
<script type="text/javascript" language="javascript">
function createHiddenInput(form, name, value)
{
var input = document.createElement("input");
input.setAttribute("type", "hidden");
input.setAttribute("name", name);
input.setAttribute("value", value);
form.appendChild(input);
}
var myCCForms = document.getElementsByName("MyForm");
if (myCCForms != null && myCCForms.length > 0)
{
var myCCForm = myCCForms[0];
createHiddenInput(myCCForm, "browserColorDepth", screen.colorDepth);
createHiddenInput(myCCForm, "browserJavaEnabled", navigator.javaEnabled());
createHiddenInput(myCCForm, "browserLanguage", navigator.language);
createHiddenInput(myCCForm, "browserScreenHeight", screen.height);
createHiddenInput(myCCForm, "browserScreenWidth", screen.width);
createHiddenInput(myCCForm, "browserTimeZone", new Date().getTimezoneOffset());
}
</script>
Send these 3-D Secure-specific parameters along with the other DirectLink mandatory parameters. Our platform will process your request and provide you with a response.
Understand declined transactions
PSD2 enhances the transparency of the payment process for you and your customers. This is especially helpful when dealing with status 2 transactions.
Our feedback parameter CH_AUTHENTICATION_INFO provides you with detailed information from the issuers when they reject your customers' transactions.
Share this information with your customers to help them understand why their bank declined their transaction.Share this information with your customers to help them understand why their bank declined their transaction. This information might also help you to recover the transaction using our Soft Decline feature.
To receive CH_AUTHENTICATION_INFO in both the XML response and your redirection URLs, select this parameter in the Back Office via Configuration > Technical information > Transaction feedback > DirectLink > Dynamic parameters and Dynamic e-Commerce parameters respectively. This will also ensure that this information is visible in the transaction overview via Operations > View transactions / Financial history.
Use CH_AUTHENTICATION_INFO for either possible scenario:
- If the transaction goes via the frictionless flow, our XML response will contain this parameter. Add the information to your transaction result page accordingly.
- If the transaction goes via the challenge flow, you receive this parameter via e-Commerce mode feedback channels. As you will not receive the information early enough to modify your redirection URLs accordingly once a transaction is finalised, we recommend flagging "I would like Payglobe to display a short text to the customer on the secure payment page if a redirection to my website is detected immediately after the payment process." in the Back Office via Configuration > Technical information > Transaction feedback > eCommerce > HTTP redirection in the browser. Our platform will then redirect your customers to our intermediate result page showing the information before your customers end up on your redirection URLs eventually.
Use the following card numbers in our Test environment to simulate an issuer response:
Amex: 349586710563469
MasterCard: 5111823134937549
Visa: 4010759044222272
Process platform response
If the transaction goes via the frictionless flow, the response contains the standard parameters with the final transaction feedback. This marks the end of the flow.
If the transaction goes via the challenge flow, the response contains additional parameters. To roll out the authentication to your customers, you need process the additional data provided as described here:
Field | Description |
---|---|
STATUS | New value: “46” (waiting for identification) |
HTML_ANSWER | BASE64 encoded html code to be added in the html page returned to the customer. This tag is added as a child of the <ncresponse> global XML tag. The field HTML_Answer field contains HTML code that has to be added in the html page returned to the customer's browser. This code will automatically load the issuer bank identification page in a pop-up in the main window, depending on the WIN3DS parameter value. To avoid any interference between the html tags included in the content of the HTML_ANSWER XML tag, with the rest of the XML returned as a response to the DirectLink request, the HTML_ANSWER content is BASE64 encoded by our system before returning the response. Consequently, this must be BASE64 Decoded before it is included in the html page sent to the cardholder. |
If the identification was unsuccessful, we redirect the card holder to the DECLINEURL, ending the flow. You receive the result via e-Commerce mode feedback channels.
If the identification was successful, we submit the actual financial transaction to the acquirer.
Depending on the acquirer’s result, we redirect the card holder to either the ACCEPTURL / DECLINEURL / EXCEPTIONURL. You receive the result via e-Commerce mode feedback channels.
9.3 Test cards
You can use the following test card to simulate a 3-D Secure registered card in our test environment:
Frictionless Flow | ||
---|---|---|
Brand | Card number | Expiry date |
VISA | 4186455175836497 | Any date in the future |
Mastercard | 5137009801943438 | Any date in the future |
American Express | 375418081197346 | Any date in the future |
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 |
More test cards numbers can be downloaded here. If a transaction is blocked due to incorrect identification, the transaction result will be: |
9.4 Exclusions and exemptions for 3DSv2
Some transactions are excluded from PSD2. If any of your transactions are among them, 3-D Secure will not be rolled out. This also applies to recurring transaction that you initiate. To mark these so-called merchant-initiated transactions (MIT) as such, you need to send additional parameters to our platform.
Frictionless / challenge flow and indication of preferred flow
You can enhance the chance of skipping SCA (resulting in a frictionless flow) by sending the following parameter.
Depending on your assessment of the risk of fraud, you may send specific values (i.e. for low risk assessment: 02, for an increased risk of fraud: 03.
The below parameters are Mandatory (in case for a preference for a specific flow).
Parameter |
Values |
---|---|
Mpi.threeDSRequestorChallengeIndicator |
Length: 2 characters
|
You can even increase the chance of a frictionless flow and a higher conversion rate by sending more optional parameters.
Exemptions of 3DS
To skip 3-D secure altogether, send the following parameters:
Parameter |
Values |
---|---|
FLAG3D | N = Skip the 3DS authentication process |
3DS_EXEMPTION_INDICATOR |
03 = Issuer TRA* * Transaction risk analysis |
However, it is still up to the issuer whether an authentication process must take place. In case the issuer insists on 3DS, the transaction will be declined.
Important Transactions for which 3-D Secure should be skipped can only be processed as authorisations (which will end up in status 5 if they are successful). To receive the funds for these transactions, you will have to capture them at a later point. Successfully captured transaction will reach status 9. |
Soft Decline
A typical flow of a soft declined transaction looks like this:
- In your first request, you send FLAG3DS=N only and no further authentication parameter. This way you indicate that you wish to skip 3-D Secure. The transaction might be accepted already now.
If it is rejected by your customer’s bank because it insists on 3-D Secure, we will indicate this in the feedback parameter by sending NCERROR=40001139. The transaction will be put in status 2. - To recover this declined transaction, resubmit the transaction by sending the following parameters to our platform
- The standard request for e-Commerce / DirectLink parameters as sent in your first request as a new order
- FLAG3DS=Y to indicate 3-D Secure needs to be rolled out
- The 3DSv2 authentication parameters as described here
- Mpi.threeDSRequestorChallengeIndicator=04 to indicate that your customer’s bank insists on 3-D Secure following the Soft Decline
Your customer will have to pass the 3-D Secure authentication during this second request. Finally, the transaction will reach either status 2 or 9. This depends on both whether your customer passed the authentication and the payment is accepted by both your and your customer’s bank.
Soft Decline is currently available for payment methods Visa, MasterCard, American Express and Carte Bancaire. |
Mastercard+ 3DSv2
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 |
|
---|---|
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
|
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
9.5 DirectLink 3-D Secure transaction flow v1.0 (deprecated)
3DSv1 is the first 3 dimensions security protocol by the card schemes, which has been replaced by v2. If you have implemented v2, this section does not apply to you.
We strongly advise you adapt your implementation according to v2 requirements. However, if you are not ready yet, find here the instructions to implement v1.
DirectLink 3-D Secure V1 transaction flow
The transaction flow involves the following steps:
- Your customer goes to your check-out pages and finalises the purchase on your payment page
- You send us the order information and payment details via a DirectLink request, containing a number of additional parameters.
- 2' (Optional): We perform a Fraud check
- You receive and XML-response from our platform
- If your customer’s card is not registered for 3-D Secure, the response contains the standard parameters with the final transaction feedback
- If your customer’s card is registered for 3-D Secure, the response contains the additional field HTML_ANSWER and a specific payment status (STATUS=46). HTML_ANSWER contains a BASE-64 encoded code block
- Add the decrypted code block to your cardholder’s browser. Your cardholder is automatically redirected to her/his issuing bank for authentication
- The cardholder identifies herself/himself. Our system receives the result from the issuer
- Two scenarios are possible
- If the identification was unsuccessful, we redirect the card holder to the DECLINEURL, ending the flow. You receive the result via e-Commerce mode feedback channels.
- If the identification was successful, we submit the actual financial transaction to the acquirer to process the transaction
- We return the payment result to you. Depending on the result, we redirect the card holder to either the ACCEPTURL / DECLINEURL / EXCEPTIONURL. You receive the result via e-Commerce mode feedback channels.
- If the transaction was successful, you can deliver the goods / services
Whether a liability shift applies or not if 3-D Secure is not rolled out, depends on your acquirer contract. Therefore, we recommend you check the terms and conditions with your acquirer. |
Send 3-D Secure v1 request
To process transactions with 3-D Secure, send a set of mandatory and optional parameters to our platform.
The table gives you an overview on the different parameters and their purpose for the authentication process.
These parameters need to be included in the SHA-calculation.
Parameter category | Parameter | Description / Possible values |
Mandatory |
FLAG3D |
Fixed value: ‘Y’ Instructs our system to perform 3-D Secure identification if necessary. |
HTTP_ACCEPT* |
The Accept request header field in the cardholder browser, used to specify certain media types which are acceptable for the response. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. * |
|
HTTP_USER_AGENT* |
The User-Agent request-header field in the cardholder browser, containing information about the user agent originating the request. This value is used by the issuer to check if the cardholder browser is compatible with the issuer identification system. * For example: User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0) |
|
ACCEPTURL |
URL of the webpage to show the customer when the payment is authorised. (or waiting to be authorised). |
|
DECLINEURL |
URL to which the customer is redirected if the maximum number of failed authorisation attempts has been reached (10 by default, but which can be changed in the Technical Information page, "Global transaction parameters" tab, "Payment retry" section). |
|
EXCEPTIONURL |
URL of the webpage to show the customer when the payment result is uncertain. |
|
LANGUAGE |
Customer’s language, for example: “en_US” |
|
Optional |
TP |
To change the layout of the "order_A3DS" page, you can send a template name/url with this parameter. |
PARAMPLUS |
Field to submit the miscellaneous parameters and their values that you wish to be returned in the post-sale request or final redirection. |
|
COMPLUS |
Field to submit a value you wish to be returned in the post-sale request or output. |
|
WIN3DS |
Way to show the identification page to the customer. Possible values:
|
After sending these parameters, our platform will process your request and provide you with a response
Process platform response
If your customer’s card is not registered for 3-D Secure, the response contains the standard parameters with the final transaction feedback. This marks the end of the flow.
If your customer’s card is registered for 3-D Secure, the response contains additional parameters. To roll out the authentication to your customers, you need process the additional data provided as described here:
Field | Description |
STATUS | New value: “46” (waiting for identification) |
HTML_ANSWER | BASE64 encoded html code to be added in the html page returned to the customer. This tag is added as a child of the <ncresponse> global XML tag. The field HTML_Answer field contains HTML code that has to be added in the html page returned to the customer's browser. This code will automatically load the issuer bank identification page in a pop-up in the main window, depending on the WIN3DS parameter value. To avoid any interference between the html tags included in the content of the HTML_ANSWER XML tag, with the rest of the XML returned as a response to the DirectLink request, the HTML_ANSWER content is BASE64 encoded by our system before returning the response. Consequently, this must be BASE64 Decoded before it is included in the html page sent to the cardholder. |
If the identification was unsuccessful, we redirect the card holder to the DECLINEURL, ending the flow. You receive the result via e-Commerce mode feedback channels.
If the identification was successful, we submit the actual financial transaction to the acquirer.
Depending on the acquirer’s result, we redirect the card holder to either the ACCEPTURL / DECLINEURL / EXCEPTIONURL. You receive the result via e-Commerce mode feedback channels.
Test cards
You can use the following test cards to simulate a 3-D Secure registered card in our test environment:
Brand | Card number | Expiry date | Password |
---|---|---|---|
VISA | 4000000000000002 | Any date in the future | 11111 |
MasterCard | 5300000000000006 | Any date in the future | 11111 |
American Express | 371449635311004 | Any date in the future | 11111 |
More test cards numbers can be downloaded here. If a transaction is blocked due to incorrect identification, the transaction result will be: |
FAQs
In your Payglobe account menu, you can easily lookup your transactions by choosing "Operations" and then clicking either "View transactions" or "Financial history", depending on the type of transaction results you're looking for.
Go to Consult your transactions for more information.
By default you can send goods or deliver your service once a transaction has reached the status "9 - Payment requested". However, although status 5 is a successful status, it's only a temporary reservation of an amount of money on the customer's card. A transaction in status 5 still needs to be confirmed (manually or automatically) to proceed to the status 9, which is the final successful status for most payment methods.
Go to Transaction statuses for more information.
You can easily refund a payment with the "Refund" button in the order overview of a transaction (via View transactions). If your account supports it, you can also make refunds with a DirectLink request or with a Batch file upload (for multiple transactions).
Please note that the Refunds option has to be enabled in your account.
Go to Maintain your transactions for more information.
If you want to check specific details of an order/transaction or perform maintenance on transactions, you should use View transactions. "Financial history" is the most convenient to periodically check incoming and outgoing funds.
For more information, go to View transactions vs Financial history.
You can only perform refunds on transactions which have already received status 9 for at least 24 hours. A cancellation or deletion can be done within approximately 24 hours after final status has been received (status 9 or 5).
To know the cut-off time of the acquirer, we recommend you to check directly with our Customer Care department.