3D Secure Web Service

The 3D Secure (3DS) Web Service allows merchants to accept credit card details within their own interface whilst allowing them to authenticate the user via the 3D Secure system. The merchant website utilises Payment Express Merchant Plug-In (MPI) through functionality exposed by way of our Web Service (SOAP based).

Implementing 3DS in the checkout process allows the liability for fraudulent chargebacks (stolen or counterfeit cards) to shift from the merchant to the card issuer.

The following sections cover the integration of the merchant hosted 3D Secure process with our Web Service API.

Web Service URL

The live endpoint for 3D Secure SOAP Web Service is available at https://sec.paymentexpress.com/WS/PXWS.asmx

WSDL

The Web Service description language document for the service is available at https://sec.paymentexpress.com/WS/PXWS.asmx?WSDL

Testing

For testing, please use the endpoint https://uat.paymentexpress.com/WS/PXWS.asmx

Test WSDL endpoint: https://uat.paymentexpress.com/WS/PXWS.asmx?WSDL

In order to test the web service a merchant will require a merchant account configured and enabled for 3D secure transactions.

The process flow is documented below. Please visit the linked operations to view the details. The specifications of the relevant operations are:

Process Flow

3D Secure Webservice
  1. The user enters their card details in the merchant website and POST this information to the merchant's server
  2. The merchant website calls the Check3dsEnrollment method of the SOAP web service
  3. Payment Express query the enrolment status of the card using their MPI
  4. Payment Express respond to the Check3dsEnrollment request indicating if the transaction can continue using 3D secure authentication. If applicable, Payment Express will also provide a PaReq value and a URL at which the user authentication should take place (acsURL)
  5. The merchant website reads the response from Payment Express and business logic determines if the user is to be directed to the issuer's site for authentication. All of the steps that follow assume that 3D secure authentication is possible (if 3D secure authentication is not possible skip to step 9)
  6. The merchant website POSTs user's browser to the issuer's website (acsURL). POSTed data includes the PaReq received in step 4 above, the URL to which the user should return once authentication has taken place, and an optional property that can be used to help identify the when they return to the website.
Value Description
PaReq Payer authentication request. The value received in the response to the Check3dsEnrollment response
TermUrl The URL to which the user will be directed at the conclusion of 3D secure authentication
MD Optional free text parameter that can be supplied and will be echoed back when the user is directed back to the TermUrl

Below is an example of a form containing all of the necessary input values and the optional 'MD' property.

The ACS will accept POST request content as follows:

PaReq= eNp1UttugzAM/RXE+0gosF5kUkFZtT506rp222sUvJatXBqgtPv6JQzW7WFRIvnY1rF9HJie04NxQlkmeeabtkVNAzO

/GAw==&TermUrl=http://localhost:54107/3DSWebService/Default.aspx&MD=1234

7. The user authenticates using the 3D secure service

8. The user is directed back to the URL specified in the TermUrl input parameter by way of client-side POST. POSTed data includes a value named "PaRes" and "MD" will be returned if supplied in step 6. Please note the PaRes value’s length should generally be much longer than the PaReq value which was returned from the Check3dsEnrollment request. If the PaRes value is shorter in length than the PaReq you may receive a declined transaction response in step 9.

9. Post the SubmitTransaction operation using the WSDL, further details specified here, for 3DS card processing with the paRes value (received from step 8). Enter the paRes value only if received the validenrolled flag and paReq in step 4, otherwise please leave it empty. The transaction result fields such as DpsTxnRef, Reco, ResponseText, AuthCode, in the response result from the SubmitTransaction result should be recorded in the merchant server or database for reporting any issues to Payment Express. This processed transactions information is also available on our transaction records which can be extracted from CSV reports or the Payline payment manager portal.

Value Description
PaRes Payer authentication response. Value to be included in the SubmitTransaction message
MD The value supplied previously if included in the POST parameters in the request

Operations

Check3dsEnrollment

Refer to: https://sec.paymentexpress.com/WS/PXWS.asmx?op=Check3dsEnrollment

Request

The input properties to the Check3dsEnrollment call are outlined below

Element Description
amount Amount in d.cc format
cardNumber Credit card number (no spaces or other delimiters)
dateExpiry Expiry date of the card in MMYY format
txnDescription Description of transaction
txnRef Set by client to uniquely identify transaction
currency Currency code

Response

Element Description
enrolled Indicates if the card holder is or can enroll for 3D secure
paReq Payer authentication request value
acsURL URL at which the card holder can be authenticated

Possible 'enrolled' values are as follows

Value Description
-1 The call has failed for technical reasons - please ensure the SOAP WS request message has correct field values and the API account is valid.
0 The card is not enrolled for 3D secure
1 The card is enrolled for 3D secure
2 The card is not enrolled for 3D secure however the user can be given the opportunity to do so.