3d secure integration direct API

1. Overview¶

This document gives technical details required for ICS 3D-Secure integration. It specifies required and optional fields sent with transactions and it describes possible responses returned by ICS gateway. Documents intended readers are merchant's technical teams in charge of ICS Gateway integration.

2. 3D Secure steps¶

3D Secure processing diagram

1. Transaction request `(Merchant -> ICS Connectx Gateway)`¶

This is a standard request as described in Transaction API Integration section of this documentation. No additional fields are required to trigger a 3D Secure check. 3D Secure check is enabled/disabled and configured during merchant on-boarding. 3D Secure checks are activated for Sale (NA transaction type indicator) and Preauthorization (AO transaction type indicator) transaction types.

Example Sale JSON request

{
    "icsid": "111111",
    "userid": "111111",
    "storeid": "111111",
    "transtype": "NA",
    "amount": "1.01",
    "currency": "USD",
    "invoice": "custom_order_number",
    "version": "3.0",
    "firstname": "Tester",
    "lastname": "Tester",
    "account": "4111111111111111",
    "expdate": "0619",
    "cvvcode": "123",
    "address": "test_address",
    "city": "Charleston",
    "state": "SC",
    "zip": "85284",
    "phone": "123123123",
    "email": "tester@example.com",
    "country": "USA",
    "ip": "104.50.234.210"
}

2. Transaction response `(ICS Connectx Gateway -> Merchant)`¶

This response will contain either:

a normal transaction response if the card or merchant is not enrolled in 3D Secure
3D Secure response that will contain fields required to create and post a form to the issuing bank ACS (Access Control Server). This will include the ACS url and pareq. The transaction will be in 'Processing' state. See ICS Response Codes for a complete list of possible responses.

Example 3D Secure response from ICS Connectx Gateway

{
    "acs_url": "http://example.com?qq=5D+ml7Td4944d",
    "cardtype": "CC",
    "currency": "HRK",
    "ordernumber": "0000000522",
    "pareq": "jJMmwvm/5sDuopmcmN+V50nXFwfAJw11zQm3jG15D+ml7T6Y9MRS+Dv4/1NvRlOt",
    "resultcode": "11",
    "resultstatus": "Processing",
    "resulttext": "Waiting for 3D secure authentication",
    "status": 1,
    "timestamp": "2018-12-03 10:01:36",
    "timestamp_utc": "2018-12-03 15:01:36",
    "trackingid": "8a2abf7d573947d4944d7742442a717b",
    "transtype": "NA",
    "version": "3.0"
}

3. ACS request (redirection) `(Merchant -> ACS)`¶

Merchant creates an HTML form and posts it to ACS url retrieved from ICS Connectx Gateway response. This redirects the customer to ACS server where a password needs to be entered to authenticate the transaction. The following fields must be present in the form:

PaReq - this is the value returned by ICS Connectx Gateway
TermUrl - an endpoint on the merchant's system where ACS will post back the results of 3D Secure authentication
MD - Merchant Data field. This is an optional field where merchants can send arbitrary data. This filed will be posted back to the merchant on their TermUrl. Use this field to send a unique transaction identifier so that transaction an be easily identified once 3D Secure result is posted back to merchant TermUrl

An example form that can be submitted to the ACS:

<!DOCTYPE html>
<html>
    <head>
        <title>3D Secure form</title>
    <body>
        <form method="post" action="http://example.com?qq=5D+ml7Td4944d">
              <input type="hidden" 
                     name="PaReq" 
                     value="JMmwvm/5sDuopmcmN+V50nXFwfAJw11zQm3jG15D+...">

              <input type="hidden" 
                     name="TermUrl" 
                     value="https://merchant_postback_handler.example.com" >

              input type="hidden" 
                     name="MD" 
                     value="xxxyyyzzz_merchant_transaction_identifier">

              <input type="submit" value="submit">
        </form>
    </body>
</html>

4. ACS response post back `(ACS -> Merchant)`¶

Please note that ACS wil not respond directly to the merchant request sent by the form in the previous step but will instead post the result to the TermUrl once 3D authentication is completed.

ACS posts the 3D Secure authentication result to merchant TermUrl. All the fields contained in the response have to be submitted to ICS Connectx Gateway in the next step of the process. The response will usually contain pares and eci values.

5. Merchant final request `(Merchant -> ICS Connectx Gateway)`¶

Merchant creates a sale 3D (NA3D transaction type indicator) or a preauth 3D (AO3D transaction type indicator) transaction and sends it to ICS Connectx Gateway. This request must contain all the fields received from the ACS in the previous step as well as the tracking id returned by ICS Connectx Gateway to the original request. Mandatory fields are:

icsid - ICS authentication parameter.
userid - ICS authentication parameter.
storeid - ICS authentication parameter.
transtype - Sale 3D (NA3D) or Preauthorization 3D (AO3D) transaction type indicator.
trackingid - Tracking id fo the original sale or preauthorization returned by ICS Connectx Gateway
eci - Eci value returned by ACS (optional)
pares - Pares value returned by ACS
additional_key_name_from_ACS - Andy additional field returned by ACS

Example JSON Sale 3D request:

{
    "icsid": "111111",
    "userid": "111111",
    "storeid": "111111",
    "transtype": "NA3D",
    "trackingid": "8a2abf7d573947d4944d7742442a717b"
    "eci": "02"
    ": "uopmcmN+V50nXFwfAJw11zQm3j..." 
    "additional_key_name_from_ACS": "additional_key_value_from_ACS"
 }

6. ICS Connectx Gateway response¶

ICS Connectx Gateway will respond with a standard response message indicating the status of the transaction. Response order number will be the same as the one given to the original transaction from the first step.

Example JSON Sale 3D approved response:

{
"cardtype": "CC",
"transtype": "NA3D",
"status": 2,
"trackingid": "8a2abf7d573947d4944d7742442a717b",
"resulttext": "Approved",
"resultstatus": "Approved",
"version": "3.00",
"resultcode": "00",
"timestamp": "2018-08-24 03:54:51",
"authcode": "UU05JXUGFQ",
"timestamp_utc": "2016-10-06+06:58:3",
"ordernumber": "custom_order_number"

}

3. 3D Secure testing environment¶

ICS Connectx Gateway provides merchants with a sandbox environment where 3D Secure transactions can be tested with all possible processing scenarios. The sandbox also includes an implementation of ACS so that the entire 3D Secure flow can be tested. 3D Secure Sandbox MIDs can be issued on request during merchant on-boarding.

Test credit cards¶

Test cards listed below will trigger a 3D Secure check if the sandbox MID is configured to use 3D Secure.

Unenrolled cards¶

These cards will trigger a 3D Secure check and report as unenrolled. The transaction will immediately be either approved or declined based on whether the MID is configured to allow transactions with unenrolled cards to continue.

5114870548455847

Enrolled cards¶

These cards will trigger a 3D Secure check and report enrolled. ICS Connectx Gateway will return a 3D response with pareq and ACS url. Merchant can create the form and submit it to the ACS url. The pares and eci fields will be returned to the TermUrl submitted to ACS. Upon posting the final Sale 3D or Preauthorization 3D transaction the ICS Connectx Gateway will respond with an approval or decline based on the card listed below. In case of 3D error (last card in the list) the transaction result will depend on merchant configuration setting indicating whether to continue in such cases

Enrolled resulting in approval¶

5555555555554444
4012888888881881
378282246310005

Enrolled resulting in decline¶

5105105105105100
4111111111111111
371449635398431

Enrolled resulting in 3D error¶

4222222222222