Standalone 3D Secure

Standalone 3D Secure

Besides executing 3D Secure with a regular payment, it is also possible to perform a 3D Secure request as a standalone request using Server-to-Server.

NOTE: You must be fully PCI compliant if you wish to perform a standalone 3D Secure request (as it requires you to collect card data).

How it works

1

Send a 3D request

Send a Server-to-Server request to the 3D Secure endpoint.

2

Handle Response

Method Data and Method URL are not always returned by the issuer. It is an optional step, but if it's returned it's important to handle it properly.

3

Get the 3DS status

Based on the details returned make a decision on whether to proceed with the payment.

1. Send a 3D request

Use the /v1/threeDSecure endpoint to initiate a standalone 3D Secure authentication flow.

Make sure that the mandatory browser parameters are collected and submitted with the request.

2. How to handle the responses

Method Data and Method URL are not always returned by the issuer. It is an optional step, but if it's returned it's important to handle it properly. Following steps have to be executed after receiving the the gateway response on the initial request.

1. Collect the necessary data from the response you received in the previous step. All the required data is present in the redirect object.

Example:

"redirect": {
        "url": "https://test.onlinepayments.pt/v1/threeDSecure/execute",
        "parameters": [{
            "name": "name",
            "value": "value"
        }],
        "preconditions": [{
            "origin": "iframe#hidden",
            "waitUntil": "iframe#onload",
            "description": "Hidden iframe post for 3D Secure 2.0",
            "method": "POST",
            "url": "methodURL",
            "parameters": [{
                "name": "threeDSMethodData",
                "value": "methodData"
            }]
        }]
    }

From the redirect object you will need to extract the following fields:

preconditions.url
preconditions.parameters[].name and precondition.parameters[].value - where the parameters object is an array and can have multiple key-value pairs

2. Open a hidden iframe and post the data to the preconditions URL like in the example shown below: 

<form name='' action='preconditions.url' method='POST'>
    <INPUT type='hidden' name='preconditions.parameters[].name' value='preconditions.parameters[].value'>
</form>
<script>
    window.onload = submitForm;
    function submitForm() { downloadForm.submit(); }
</script>

3. Similarly to step 1, take the redirect.url and redirect.parameters[] fields from the response. You will use these fields to request the authentication HTML from the cardholder's bank.

3. Create another iframe where the cardholder will see the authentication request from their bank. Listen and wait for the onLoad() event from the previous step, then redirect the shopper within this iframe to the redirect.url. Make sure you include the key/value pairs from the redirect.parameters[] array.

<form name='' action='redirect.URL' method='POST'>
    <INPUT type='hidden' name='redirect.parameters[].name' value='redirect.parameters[].value'>
</form>
<script>
    window.onload = submitForm;
    function submitForm() { downloadForm.submit(); }
</script>

3. Get the 3D Secure status

Use the /v1/threeDSecure/{id} endpoint to get detailed information about the 3D Secure request.