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://www.paymentexpress.com/WS/PXWS.asmx
WSDL
The web service description language document for the service is available at https://www.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
- The user enters their card details in the merchant website and POST this information to the merchant's server
- The merchant website calls the Check3dsEnrollment method of the SOAP web service
- DPS query the enrolment status of the card using their MPI
- 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)
- 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)
- 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 - The user authenticates using the 3D secure service
- 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
- The merchant website makes a SubmitTransaction call with enable3DSecure equal to "1" and paRes equal to the PaRes value POSTed in the request.
Operations
Check3dsEnrollment
Refer to: https://www.paymentexpress.com/WSTest/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 | Currecny 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://www.paymentexpress.com/WSTest/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 |
| 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 |
| 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 |