3-D Secure 1.0

Once a transaction is processed with the 3-D Secure 1.0 verification, the customer is always redirected to the Access Control Server form of the card issuing bank (ACS form). The customer should enter a password received from the card issuing bank to authenticate a payment.

The transaction processing with 3-D Secure verification consists of the following steps:

3-D Secure Workflow

Stage	Description
1	The customer submits a purchase request to the merchant's store.
2	The merchant submits a payment or an authorization transaction request to Forte E-commerce.
3	Forte E-commerce checks if the customer's card is enrolled in 3-D Secure 1.0 program.
4	If the card is not enrolled, the request goes to the acquiring bank and the transaction processing status returns to the merchant. The process moves to Stage 10.
5	Forte E-commerce returns a response with the `incomplete` status and parameters as follow: `redirect_url` in the `transaction` section of the response, and `acs_url`, `pa_req`, `md` and `pa_res_url` in the `three_d_secure_verification` section of the response.
6	Now there are two options how to proceed further: Basic The merchant's application routes the customer's device to `redirect_url`. Advanced Before you implement the advanced flow, confirm with your account manager if it is available for you. The flow is designed for those merchants who want more control over a payment process. In this flow the merchant's application builds a form to forward the customer to the card issuing bank for verification, waits the customer back to `TermUrl` provided in the form parameters, and then submits a POST request with the received `PaRes` and `MD` to `pa_res_url`. Forte E-commerce will send the transaction data along with the 3-D Secure values to a processing network and will return a response with the results.
7	The customer gets authorized with 3-D Secure and is forwarded back to Forte E-commerce.
8	Forte E-commerce sends a payment or authorization transaction request with the proper ECI, CAVV and XID 3-D Secure parameters to the acquiring bank. If the merchant opts for the advanced flow on Stage 6, Forte E-commerce responses with the transaction result and the 3-D Secure process jumps to Stage 11.
9	Forte E-commerce forwards the customer's browser to `return_url` (sent in payment or authorization requests) with the transaction UID parameter `uid` attached to the request URL. E.g. if `return_url` is `http://www.example.com/return_here`, the customer's browser is forwarded to `http://www.example.com/return_here?uid=TRANSACTION_UID`
10	The merchant sends a status query request to get the transaction details with its final status.
11	The merchant continues with his workflow to finalize the order, completes the transaction and shows a confirmation page to the customer.

Form to redirect the customer to the ACS form

Merchant's application gets and stores the values of acs_url, pa_req, md and pa_res_url. Then it builds a form using stored values:

<form id="ACSRedirect" action="value_of_acs_url" method="POST">
      <input type="hidden" name="MD" value="value_of_md">
      <input type="hidden" name="TermUrl" value="merchant_application_endpoint">
      <input type="hidden" name="PaReq" value="value_of_pa_req">
      <input type="submit" value="Submit">
</form>

Full form example

<html>
<head>
    <META http-equiv="Content-Language" content="en-US">
    <style>
    .content {
        width: 50%;
        margin: 0 auto;
        text-align: center;
    }

    input[type="submit"] {
        background-color: rgb(92, 184, 92);
        border-bottom-color: rgb(76, 174, 76);
        border-bottom-left-radius: 4px;
        border-bottom-right-radius: 4px;
        border-bottom-style: solid;
        border-bottom-width: 1px;
        border-left-color: rgb(76, 174, 76);
        border-left-style: solid;
        border-left-width: 1px;
        border-right-color: rgb(76, 174, 76);
        border-right-style: solid;
        border-right-width: 1px;
        border-top-color: rgb(76, 174, 76);
        border-top-left-radius: 4px;
        border-top-right-radius: 4px;
        border-top-style: solid;
        border-top-width: 1px;
        color: rgb(255, 255, 255);
        cursor: pointer;
        display: inline-block;
        font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
        font-size: 14px;
        height: 34px;
        line-height: 20px;
        padding-bottom: 6px;
        padding-left: 12px;
        padding-right: 12px;
        padding-top: 6px;
        text-align: center;
        touch-action: manipulation;
        vertical-align: middle;
        white-space: nowrap;
        width: 80px;
        word-spacing: 0px;
        margin-top: 40px;
    }

    img { height: 70px; }
    </style>

</head>
<body>

<div class='content'>
    <p><img src="/images/visa.png"></p>
    <h3>Your card is enrolled in 3-D Secure program</h3>
    <p>You will be redirected to your bank's secure page for 3-D Secure check. Then your transaction will be finished.
If nothing happens, please click Submit button.
</p>

    <form id="ACSRedirect" action="https://dropit.3dsecure.net:9443/PIT/ACS" method="POST">
    <input type="hidden" name="MD" value="454645">
    <input type="hidden" name="TermUrl" value="http://merchantsite.example.com/process/454645">
    <input type="hidden" name="PaReq" value="eJxVUtFy2jAQ/BVP3mPJsrAd5tCMwZkx04lLihsmfTPyBRyKDbIIpF/fE4Gkfds9re5uV4JybRCzOeqDQQUP2PfVCr2mHt0Uk1nE8ySQ0bd0kd+JKJ0kNwpm6Q/cK3hD0zddqwKf+wLYlVIHo9dVaxVUej+eFkomIY9JcaGwRTPNVBAIEYZSxjGwjwq01RZVib31+sYisDMH3R1aa96VFAmwK4GD+a3W1u6GjB2PRx91t6WpZoU+IWDuGNjXKrODQz21OzW1KjfFY/E6nn7P7nmxseMnvho8vP4aP/5ZjYA5BdSVRSV4MOAJj7xADIUcyjtg5zpUW7cHeZB+JLyf84zcfZRg5yaln+cRGf+3BBSzwVa/q0Ry8nNlgKdd1yIp6MInhhp7rcLbbO69dMaz5uTJgYxkfLvUL0GYiOXS7eREwL48TnIXvrYUavy0fI7L+zLPN/Vi/ZzsTbGw6YhsXgRucEOJCs6D82RHgLkW7PLSlOP5UxD677P8BW2Nudo=">
    <input type="submit" value="Submit">
    </form>
    <script type="text/javascript">
    setTimeout(function(){ document.forms["ACSRedirect"].submit(); }, 3000);
    </script>

</div>
</body>
</html>

Request with the 3-D Secure result to the Forte E-commerce system

Send a POST request with the received PaRes and MD to pa_res_url:

{
    "md": "value_of_MD",
    "pa_res": "value_of_PaRes"
}

3-D Secure response parameters

Parameter	Type	Description
ve_status	string	Verification status of the card enrollment in 3-D Secure program.
pa_status	string	Payment authentication status (present only if authentication was performed).
eci	string	Electronic Commerce Indicator. Provides information regarding Merchant protection level against chargebacks requests by the Cardholders or their banks.
xid	string	3-D Secure transaction unique identification code.
cavv	string	Cardholder Authentication Verification Value (present only if the Cardholder has been successfully authenticated).
cavv_algorithm	string	CAVV algorithm (present only if the authentication status is `Y` or `A`).
fail_reason	string	Human readable reason if 3-D Secure authentication failed.
status * required	string	3-D Secure authentication status.

Example of enrollment verification response (Step 3)

{
    "transaction": {
        "amount": 9906,           
        "billing_address": {
            "address": "1st Street",
            "city": "Denver",
            "country": "US",
            "first_name": "Test",
            "last_name": "Test",
            "phone": null,
            "state": "CO",
            "zip": "96002"
        },
        "created_at": "2015-08-06T15:24:48Z",
        "credit_card": {
            "brand": "visa",
            "exp_month": 1,
            "exp_year": 2027,
            "first_1": "4",
            "holder": "John Doe",
            "last_4": "0000",
            "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
            "token": "17192917abfc48d9b3ee3fa2c9c29d7aa64b7ab40040d6eedd48b4557ac4079c"
        },
        "currency": "USD",
        "customer": {
            "device_id": null,
            "email": "john@example.com",
            "ip": "127.0.0.1"
        },
        "description": "Test transaction",
        "id": "454744-32f929708d",
        "language": "en",
        "message": null,
        "redirect_url": "https://gw_domain/process/454744-32f929708d",
        "status": "incomplete",
        "test": true,
        "three_d_secure_verification": {
            "acs_url": "https://dropit.3dsecure.net:9443/PIT/ACS",
            "md": "74652",
            "message": "Authentication Available",
            "pa_req": "eJxVUl1vm0AQ/Cso7+E+OAy21ieFQGRXrR0Hmip9o7CJkWxwjqM4/fXdc+ykfZvZHc3uzh0UW4OY5lgNBjV8w74vX9Br6vlVmKfx12WyCRfJZL1Wt3n2JK403N884KuG32j6pmu18LkvgV0oOZhqW7ZWQ1m9JsuVVnHAI1KcKezRLFMthJRBoFQUAXuvQFvuURfYW69vLAI7cai6obXmTSsZA7sQGMxOb609zBgbx9HHqtvTVPOCPiFgrg3sc5X7waGe7I5NrVePq2ydHb9sdpnIs6UseMw3YnX3o8jmwJwC6tKillyE1Jp4IpxJNQs5sFMdyr3bQ0+nPjW/5ykd916Bgxt0c2nzCbB/K0AhG2yrNx0rMvtggMdD1yIpKKcPDDX2lQ6u09x77oxnzdFToYqUug4kTuU04nFNGzkRsM8Lbxcu+spSpNHjr6eoyIrFYlcPf8r04WcyJuOcjjwL3OCG8pSci9NkR4A5C3Z+Z0rx9CUI/fdV/gLLBLic",
            "pa_res_url": "https://gw_domain/process/454744-32f929708d",
            "status": "incomplete",
            "ve_status": "Y"
        },
        "tracking_id": null,
        "type": "payment",
        "uid": "454744-32e929708d",
        "updated_at": "2015-08-06T15:24:51+00:00"
    }
}

Response example

{
"transaction":{
    "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
    },
    "credit_card":{
        "holder":"John Doe",
        "stamp":"f873e6516da9f61678d918e86c2835e4b4f6ed47506ec9be8abd4967fe4be2d4",
        "brand":"visa",
        "last_4":"1112",
        "first_1":"4",
        "exp_month":1,
        "exp_year":2027
    },
    "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "address":"1st Street",
        "country":"US",
        "city":"Denver",
        "zip":"96002",
        "state":"CO",
        "phone":null
    },
    "three_d_secure_verification":{
        "eci":"05",
        "ve_status":"Y",
        "pa_status":"Y",
        "xid":"2DIMDD08RRE6WVC140GW",
        "cavv":"AAACCEmXU2FoNWGZI5dTAAAAAAA=",
        "cavv_algorithm":"2",
        "message":"Authentication Successful",
        "fail_reason":null,
        "status":"successful"
    },
    "payment":{
        "auth_code":"654321",
        "bank_code":"05",
        "rrn":"999",
        "ref_id":"777888",
        "message":"Authorization was approved (with 3-D Secure)",
        "gateway_id":327,
        "billing_descriptor":"TEST GATEWAY BILLING DESCRIPTOR",
        "status":"successful"
    },
    "uid":"1-310b0da80b",
    "status":"successful",
    "message":"Successfully processed",
    "amount":100,
    "currency":"USD",
    "description":"Test order",
    "type":"payment"
}
}

Verification status of the card enrollment

Status	Description	3-D Secure Available?	Payment completed?
`Y`	Card is enrolled.	Yes	No
`N`	Card is not enrolled.	No	Yes
`U`	Unable to authenticate.	No	Yes
`E`	Enrollment verification error. See fail_reason for details	No	Yes

Payment authentication status

Status	Description	VISA ECI	MC ECI
`Y`	Cardholder was successfully authenticated.	`05`	`02`
`A`	Authentication could not be performed, but a proof of authentication attempt was provided.	`06`	`01`
`N`	Cardholder authentication failed. Authorization request shouldn't be submitted.	-	-
`U`	Authentication could not be performed due to a technical error or other problem. The transaction will be treated as eCommerce. The payment card used for this transaction is deemed ineligible for 3-D Secure processing. The merchant will have to decide if he wants to proceed with an unauthorized payment request or if he should ask the customer for another form of payment.	`05`	`02`
`E`	An error occurred during the authentication process. Authorization request shouldn't be submitted.	-	-

CAVV algorithm

It indicates the algorithm used to generate the authentication CAVV value. This property is determined by the Access Control Server (ACS), and is filled after receiving a response to a Payer Authentication Request (PAReq) and if the authentication status is Y or A. This property contains the one digit value which indicates the algorithm used by the ACS to generate the Cardholder Authentication Verification Value (CAVV). Valid algorithms include:

CAVV Value	Description
`0`	HMAC (as per SET TranStain)
`1`	CVV
`2`	CVV with ATN