Adding 3D Secure to your XML Integration
PSD2 and Strong Customer Authentication (SCA)
The Payment Services Directive 2 (PSD2) comes into force in 2019 (only applicable in EU) and you might need to be prepared to provide SCA for your payments. Take a closer look at our F.A.Q in case you have more questions.
The 3D Secure 2.0 verification process will require the Card Holder to pass an identity check, and the check result will be sent back to the Merchant's application as a GET request. The GET response will return the MPIREF parameter, which should be included in the XML payment request.
After the merchant application receives the 3D Secure check result, it should send an XML payment request.
If the 3D Secure check was successful (‘A’ Result) the payment request should contain the fields MPIREF, Order ID and Terminal ID and they should be the same as in the 3D Secure request. From 31st December 2020, transaction without a MPIREF will be declined and will not be processed.
The process is described in the flowchart below.
1. A POST request is made to the Worldnet server. The server will handle the user authentication.
2. After authentication, the server will redirect to the URL set in the MPI Receipt URL in the `Selfcare > Settings > Terminal` section with the authentication results passed in the URL.
3. In your integration add the MPIREF code to your XML payment and send a payment load to the XML Request URL. For further details, check XML Payment Features.
4. If the payment is successful, the server will return an approval message.
Part 1. Creating 3DS Request
To simplify 3D Secure integration using the XML payments API, Worldnet provides a simple MPI redirect.
3D SECURE ENABLING
To allow 3D Secure transactions on one of your terminal accounts, this feature and its settings must be configured. Please contact the Worldnet support team in case you need the activation of this feature.
The following resources are the same for all the requests and responses you find in this page:
| TYPE | URL |
|---|---|
| Request URL | https://testpayments.worldnettps.com/merchant/mpi |
3D SECURE LIVE
This URL should be used in test mode only. Please contact the Worldnet support team to receive the live URL.
Use the Request URL and the Request Body Fields to perform a request for this feature.
Request Body Fields
Filter:
| FIELD | REQUIRED | DESCRIPTION |
|---|---|---|
| TERMINALID | Y | A Terminal ID provided by Worldnet. NB - Please contact Worldnet to be issued with a test terminal ID. |
| CARDNUMBER | Y | The payment card number. |
| CARDHOLDERNAME | Y | Required for 3DS 2.0 - The name on the front of the credit card. |
| CARDEXPIRY | Y | 4 digit expiry field (MMYY). |
| CARDTYPE | Y | See Card Types section. |
| AMOUNT | Y | The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts. |
| CURRENCY | Y | A 3 character currency code of the transaction. |
| ORDERID | Y | A unique identifier for the order created by the merchant (Max 24 characters). |
| CVV | N | The security code entered by the card holder. |
| DATETIME | Y | Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS. |
| HASH | Y | A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section. |
Notes and Details About the Request
ND001 - Hash Formation
The general rule to build HASH field is given at the Special Fields and Parameters page. For this specific feature, you should use the following formats:
TERMINALID:ORDERID:CARDNUMBER:CARDEXPIRY:CARDTYPE:AMOUNT:DATETIME:SECRET
ND002 - Data Encoding for Requests
All data sent to us should be correctly encoded using UTF-8 as the character encoding.
The HTML example below shows how to build a form to request Strong Customer Authentication from Worldnet.
<html> <body> <form id="FormID" action="https://testpayments.worldnettps.com/merchant/mpi" method="post"> <label>Terminal ID</label> <input type="text" name="TERMINALID" /> <label>Terminal Secret</label> <input type="text" name="SECRET" /> <label>Order ID</label> <input type="text" name="ORDERID" /> <label>Currency</label> <input type="text" name="CURRENCY" value="EUR" /> <label>Amount</label> <input type="text" name="AMOUNT" /> <label>DateTime</label> <input type="text" name="DATETIME" value="15-3-2006:10:43:01:673" /> <label>Cardholder Name</label> <input type="text" name="CARDHOLDERNAME" /> <label>Card Number</label> <input type="text" name="CARDNUMBER" /> <label>Expiry Date</label> <input type="text" name="CARDEXPIRY" /> <label>CVV</label> <input type="text" name="CVV" /> <label>CardType</label> <input type="text" name="CARDTYPE" /> <label>Hash</label> <input type="text" name="HASH" /><br /> <input id="SubmitID" type="submit" value="Check 3D Secure" /> </form> <script src="https://code.jquery.com/jquery-3.2.1.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/blueimp-md5/2.18.0/js/md5.min.js"></script> <script> // GENERATE HASH TERMINALID+ORDERID+CARDNUMBER+CARDEXPIRY+CARDTYPE+AMOUNT+DATETIME+secret function calcHash() { var hash = md5($("input[name='TERMINALID']").val() + $("input[name='ORDERID']").val() + $("input[name='CARDNUMBER']").val() + $("input[name='CARDEXPIRY']").val() + $("input[name='CARDTYPE']").val() + $("input[name='AMOUNT']").val() + $("input[name='DATETIME']").val() + $("input[name='SECRET']").val()); $("input[name='HASH']").val(hash); } $("input[type='text']").each(function (index) { $(this).on("keyup", calcHash); }); calcHash(); </script> </body> </html>
Part 2. Handling 3D Secure Server Response
If the 3D Secure check was successful, it is time to prepare your integration to handle the Response Body Fields.
Response Body Fields
The response body fields will be:
Filter:
| FIELD | DESCRIPTION |
|---|---|
| RESULT | MPI processing result: A: Approved. D: Declined. |
| MPIREF | MPI reference, this value should be sent in the XML payment request if received from the Worldnet MPI. |
| ORDERID | Original order identifier. |
| STATUS | A: An attempt at authentication was performed (ECI: 06). N: Authentication attempt not performed (ECI: 06). U: Unable to authenticate (ECI: 07 or 06). Y: Authentication attempted and succeeded (ECI: 05). |
| ECI | 05: Full 3D Secure authentication. 06: Issuer and/or cardholder are not enrolled for 3D Secure. 07: 3D Secure authentication attempt failed - numerous possible reasons (Visa only). |
| DATETIME | Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS. |
| HASH | A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section. |
Notes and Details on the Response
ND001 - Hash Formation
The general rule to build HASH field is given at the Special Fields and Parameters page. For this specific feature, you should use the following formats:
RESULT:MPIREF:ORDERID:DATETIME:SECRET
The response will be attached to the MPI Receipt URL. An example of the response can be seen below.
https://MPIRESULTURL.COM?RESULT=A&STATUS=A&ECI=06&MPIREF=d01656cf0ec3e62e3754&ORDERID=25&DATETIME=06-10-2020%3A13%3A19%3A10%3A239&HASH=3ea402c12f7a8cb0afac31cf0429a167
Part 3 and 4 XML Payment Request and Response
Now with the MPIREF available, proceed to the XML Payment Feature for more details on how to proceed with Part 3 and Part 4 of this tutorial or use the quick reference below.
Simple Payment Request
Attach the MPIREF it to your XML Payment load and send it to the XML Request URL.
- Scenario: Simple request, only mandatory fields.
- Terminal: 6491002.
- Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?> <PAYMENT> <ORDERID>115010922465</ORDERID> <TERMINALID>6491002</TERMINALID> <AMOUNT>10</AMOUNT> <CARDNUMBER>4111111111111111</CARDNUMBER> <CARDTYPE>VISA</CARDTYPE> <CARDEXPIRY>0807</CARDEXPIRY> <CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME> <CURRENCY>EUR</CURRENCY> <TERMINALTYPE>1</TERMINALTYPE> <TRANSACTIONTYPE>7</TRANSACTIONTYPE> <CVV>214</CVV> <DATETIME>12-06-2006:11:47:04:656</DATETIME> <MPIREF>d01656cf0ec3e62e3754</MPIREF> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </PAYMENT>
If the payment is successful a return message should be similar to the below:
<?xml version="1.0" encoding="UTF-8"?> <PAYMENTRESPONSE> <UNIQUEREF>JJCVGCTOV3</UNIQUEREF> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>APPROVAL</RESPONSETEXT> <APPROVALCODE>475318</APPROVALCODE> <DATETIME>2005-11-14T12:53:18</DATETIME> <CVVRESPONSE>M</CVVRESPONSE> <HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH> </PAYMENTRESPONSE>