3D Secure Web Service

The 3D secure 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 DPS merchant plug-in (MPI) through functionality exposed by way of a SOAP web service.

This page covers integration of the 3D secure system in the DPS Web Service interface. For More information on the DPS Web Service in general, please refer to the Web Service page.

Web Service URL

The 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

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, followed by an outline of the relevant operations:


Process Flow


  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. DPS query the enrolment status of the card using their MPI

  4. DPS respond to the Check3dsEnrollment request indicating if the transaction can continue using 3D secure authentication. If applicable, DPS 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 DPS 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.

<form method="POST" action="https://www.mycardsecure.com/acspage/cap.dll?RID=16048&VAA=B">
<input type="hidden" name="PaReq" value="eNp1UttugzAM/RXE+0gosF5kUkFZtT506rp222sUvJatXBqgtPv6JQzW7WFRIvnY1rF9HJie04NxQlk
meeabtkVNAzO/GAw==">
<input type="hidden" name="TermUrl" value="http://localhost:54107/3DSWebService/Default.aspx">
<input type="hidden" name="MD" value="1234">
</form> 

 

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

9. The merchant website makes a SubmitTransaction call with enable3DSecure always equal to "1" and paRes equal to the PaRes value POSTed in the request. 

In the case where 'enrolled' set to 0 and paReq is null/empty, the merchant can set 'enable3dSecure' to '1' and leave the 'paRes' empty when calling SubmitTransaction.

In the case where 'enrolled' set to -1; best practice is to throw an exception and decline the transaction locally as the verification of enrolment may have failed.
 

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


SubmitTransaction

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

Request

Value Description
amount Amount in dd.cc format
billingId Supplied for token billing
cardHolderName Card holder name as found on card
cardNumber Credit card number. No spaces or other delimiters
clientInfo IP address of the user. For use with risk management rules
cvc2 Card security code
cvc2Presence
Indicates information regarding submission of cvc2 value
dateExpiry Expiry date of the card in MMYY format
dpsBillingId Token specified for recurring billing
dpsTxnRef Unique transaction identifier required for refund and completion transactions only
enableAddBillCard Required in order to add a card to the token billing system. "1" = true, "0" = false
enablePaxInfo Used for Airline Reservation Systems
inputCurrency Three digit currency code
merchantReference Primary transaction reference. Free text
paxCarrier Used for Airline Reservation Systems
paxCarrier2 Used for Airline Reservation Systems
paxCarrier3 Used for Airline Reservation Systems
paxCarrier4 Used for Airline Reservation Systems
paxDateDepart Used for Airline Reservation Systems
paxDate2 Used for Airline Reservation Systems
paxDate3 Used for Airline Reservation Systems
paxDate4 Used for Airline Reservation Systems
paxTime1 Used for Airline Reservation Systems
paxTime2 Used for Airline Reservation Systems
paxTime3 Used for Airline Reservation Systems
paxTime4 Used for Airline Reservation Systems
paxLeg1 Used for Airline Reservation Systems
paxLeg2 Used for Airline Reservation Systems
paxLeg3 Used for Airline Reservation Systems
paxLeg4 Used for Airline Reservation Systems
paxClass1 Used for Airline Reservation Systems
paxClass2 Used for Airline Reservation Systems
paxClass3 Used for Airline Reservation Systems
paxClass4 Used for Airline Reservation Systems
paxStopOverCode1 Used for Airline Reservation Systems
paxStopOverCode2 Used for Airline Reservation Systems
paxStopOverCode3 Used for Airline Reservation Systems
paxStopOverCode4 Used for Airline Reservation Systems
paxFareBasis1 Used for Airline Reservation Systems
paxFareBasis2 Used for Airline Reservation Systems
paxFareBasis3 Used for Airline Reservation Systems
paxFareBasis4 Used for Airline Reservation Systems
paxFlightNumber1 Used for Airline Reservation Systems
paxFlightNumber2 Used for Airline Reservation Systems
paxFlightNumber3 Used for Airline Reservation Systems
paxFlightNumber4 Used for Airline Reservation Systems
paxName Used for Airline Reservation Systems
paxOrigin Used for Airline Reservation Systems
paxTicketNumber Used for Airline Reservation Systems
paxTravelAgentInfo Used for Airline Reservation Systems
txnData1 Free text field
txnData2 Free text field
txnData3 Free text field
txnRef Uniquely identifies the transaction request. Must be set in order to run GetStatus
txnType Purchase, Refund, Auth, Complete or Validate
dateStart The Issue date of the customer's credit card, if Issuer requires this field to be present.
issueNumber The Issue Number of the credit card if Issuer requires this field to be present.
enableAvsData Address Verification System property. Values are 1 (Enable Verification), 0 (Disable Verification).
avsAction Address Verification System property. Valid values are 0,1,2 & 3.
avsPostCode Address Verification System property. Post Code that is listed on the customer's bank statement
avsStreetAddress Address Verification System property. Address that is listed on the customer's bank statement.
enable3DSecure Indicates if 3D secure is to be used for the transaction
paRes paRes (Payer authentication response) POSTed back to the TermUrl
clientType Transaction entry point type

Response

Element Description
amount Amount in dd.cc format
authCode Authorization code
authorized Indicates if the transaction was authorized or not. Either False (0) or True (1)
billingId The billingId specified in the request
cardHolderHelpText Any tips or hints for the CardHolder. Usually just the Response Text, associated with the ReCo
cardHolderName Card holder name as found on card
cardHolderResponseDescription A description of the transaction error to help the CardHolder, associated with the ReCo
cardHolderResponseText Response Text of the transaction to help the card holder, associated with the ReCo.
cardName Card type used
cardNumber Truncated card number
currencyId Currency identifier
currencyName Currency code
currencyRate Currency rate
cvc2 Indication of the use of card security code
cvc2ResultCode Contains information regarding verification of cvc2.
dateExpiry Expiry date of the card in MMYY format
dateSettlement Date at which funds will be settled in yyyymmdd format
dpsBillingId Contains the BillingId generated by DPS when adding a card for recurring billing.
dpsTxnRef Unique transaction identifier returned for every transaction. Required input for Refund transactions or Complete transactions.
helpText Any tips or hints for the CardHolder. Usually just the Response Text, associated with the ReCo
merchantHelpText Response Text of the transaction to help the merchant
merchantReference Value specified in the request
merchantResponseDescription A description of the transaction error to help the merchant
merchantResponseText Response Text of the transaction to help the merchant
reco 2 character response code.
responseText Response Text associated with ReCo
retry If true; retry transaction, if false do not retry
statusRequired If true then the result of the transaction could not be determined and you will have to call GetStatus to get the result.
testMode Indicates if the transaction went through test systems
txnRef Value specified in the request
txnType Purchase, Refund, Auth, Complete or Validate