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:
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 Demo PSP. |
3 | Demo PSP 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 | Demo PSP 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 . Demo PSP 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 Demo PSP. |
8 | Demo PSP 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, Demo PSP responses with the transaction result and the 3-D Secure process jumps to Stage 11. |
9 | Demo PSP 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 Demo PSP 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": 2026,
"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":2026
},
"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 |