3D Secure

3D secure (Verified by Visa, MasterCard SecureCode) is an additional security step for credit card payments that helps prevent fraud.

3D secure flow is the same between charge and subscription, we are using charge as an example in this tutorial.

Enable 3D secure

By passing secure=1 as an additional parameter in your charge request, a different charge response will be returned. It includes a redirect url which allows you to redirect your customer to the 3D secure form which is provided by the card issuing banks of your customers .

In order to implement 3D secure feature, you will need to do following adjustments:

• Display 3D secure form to your customer and collect secure token.

• Re-submit charge request to finish a payment with 3D secure.

Collect secure token

Once a payment is enrolled into 3D secure payment step, the payer need to verify himself on 3D secure form, it could be his card password or a SMS message containing verification code, etc.

Displaying 3D secure form for your customers is the first step. After that, brick_secure_token and brick_charge_id would be included into the http request object once the payer has completed the 3D secure step, which are needed in second charge request.

The implementation is different depending on your payment form.

If you are using default payment form, this part is handled by default payment form itself. See re-submit charge request to continue.

For merchants who prefer custom payment form, the following steps are required:

• Add secure_redirect_url & secure_return_method

You will need to add the above two additional parameter into your charge request

secure_redirect_url is the url where your customer will be redirected after completing the 3D secure step.

The value of secure_return_method is required to be set as url so that you will get a redirect url rather than a html form.

<?php
$cardInfo = array(
    ... // other charge parameters
    'secure_redirect_url' => 'YOUR-SECURE-REDIRECT-URL',
    'secure_return_method' => 'url'
);
?>

//custom parameters
var custom = {
    ... // your other custome parameters
    'secure_redirect_url':'YOUR-SECURE-REDIRECT-URL',
    'secure_return_method': 'url'
};

... // your other charge parameters
chargemap.put("secure_redirect_url", "YOUR-SECURE-REDIRECT-URL");
chargemap.put("secure_return_method", "url");

curl https://payments.terminal3.com/api/brick/charge \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \
-d "token=[TOKEN]" \
-d "amount=9.99" \
-d "currency=USD" \
-d "email=user@host.com" \
-d "fingerprint=[FINGERPRINT_BY_BRICK.JS]" \
-d "description=TestItem" \
-d "secure_redirect_url=[YOUR_SECURE_REDIRECT_URL]" \
-d "secure_return_method=url"

brick_fingerprint and brick_token of the original request should be embedded into secure_redirect_url, so that they can be subsequently passed into the second charge request. Here is a sample:

secure_redirect_url: http://your-domain/your-secure-redirect-url?brick_token=ot_4ca5cbda3D4af3444759e4934dd25717&brick_fingerprint=satiO3yvBDuPMEZUJep4vKuqVav5VxAT

• Obtain 3D secure form and display it

With 3D secure enabled, you will get a charge response object contains the redirect url. Below is a sample charge response object.

{
  "success":0,
  "secure":{
    "redirect":"https:\/\/payments.terminal3.com\/api\/brick\/redirect\/3Ds\/fe989d17-5632-11e7-bfd3-002590852bf4\/44ea915ab53D78f96b3Dd485e7a5f8d2441572876f7a2eb88f5101cb197adcc9"
  }
}

You can then use it to redirect your customer to 3D secure page. See the next step to continue.

The following additional step are required only if you don’t have secure_return_method included in your original charge request. You will get a html form of 3D Secure instead of redirecting url.

{
  "success":0,
  "secure":{
     "formHTML":"<div><form action=\"https:\/\/payments.terminal3.com\/api\/brick\/secure-test-bank-page?public_key=t_a93Db6bffafdda5c57ab48296fdbba\" method=\"POST\"><input type=\"hidden\" name=\"PaReq\" value=\"to_validate_this\"><input type=\"hidden\" name=\"MD\" value=\"t34451493976105_test\"><input type=\"hidden\" name=\"TermUrl\" value=\"https:\/\/payments.terminal3.com\/api\/brick\/secure-payment?public_key=a3Dff98c34722f0e130a68e6b4c9da56&secure_redirect_url=http%3A%2F%2Fpaymentwall.com%2Fbrick%2F3Dsecure%3Fbrick_token%3Dot_4ca5cbda3D4af3444759e4934dd25717%26brick_fingerprint%3DsatiO3yvBDuPMEZUJep4vKuqVav5VxAT\"><\/form><\/div>"
  }
}

Simply obtian the value of formHTML attribute, embed it into your payment page and submit it directly, the 3D secure form will be displayed in a new tab as a result.

<script>
  document.getElementById("3Ds_form_container").getElementsByTagName("form")[0].submit();
  // 3Ds_form_container is the place where 3D secure form is embedded in
</script>

• Handle 3D secure details on your backend

brick_secure_token and brick_charge_id will be sent to secure_redirect_url via POST each time a payer comfirmed the 3D secure payment step, you can now continue with next step.

Re-submit charge request

Payments with 3D secure enabled requires another charge request with below two parameters included in.

As these two parameters have been passed to your backend, you can easily add them directly in second charge request.

<?php
$cardInfo = array(
    ... // your original charge request parameters
);

if (isset($parameters['brick_charge_id']) AND isset($parameters['brick_secure_token'])) {
    $cardInfo['charge_id'] = $parameters['brick_charge_id'];
    $cardInfo['secure_token'] = $parameters['brick_secure_token'];
}
?>

// We are using Express framework in this sample

//custom parameters
var custom = {
    secure: 1
};

var parameters = req.body;
if (parameters.brick_charge_id&&parameters.brick_secure_token){
    custom.charge_id = parameters.brick_charge_id;
    custom.secure_token = parameters.brick_secure_token;
}

var charge = new Paymentwall.Charge(
    0.5, //price
    'USD', //currency code
    'description', //description of the product
    req.body.email, // user's email which can be gotten by req.body.email
    req.body.brick_fingerprint, // fingerprint which can be gotten by req.body.brick_fingerprint
    req.body.brick_token, //one-time token
    custom 
);

LinkedHashMap<String,String> chargemap = new LinkedHashMap<String, String>();

... // your original charge request parameters

if (request.getParameter("brick_charge_id")!=null &&request.getParameter("brick_secure_token")!=null){
    chargemap.put("charge_id", request.getParameter("brick_charge_id"));
    chargemap.put("secure_token",request.getParameter("brick_secure_token"));
}

curl https://payments.terminal3.com/api/brick/charge \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \
-d "token=[TOKEN]" \
-d "amount=9.99" \
-d "currency=USD" \
-d "email=user@host.com" \
-d "fingerprint=[FINGERPRINT_BY_BRICK.JS]" \
-d "description=TestItem" \
-d "secure_redirect_url=[YOUR_SECURE_REDIRECT_URL]" \
-d "charge_id=[BRICK_CHARGE_ID]" \
-d "secure_token=[BRICK_SECURE_TOKEN]"

Next step

That’s it. Your payment system now should be able to handle payments with 3D secure enabled, below links might be helpful for you:

• Test your payment system with Brick sandbox enviroment.

• Submit your project for review to go live your project.