Using 3-D Secure with Remote Integration

Remote Integration supports the option for merchants to use the gateway MPI without needing to install any additional components. This simplifies the work that would otherwise be needed to integrate your systems with an MPI.

There are 3 APIs to be invoked in order to complete the payment

Device data collection
Check enrollment
Authorization

1. Device data collection

Initiate the Payer Authentication Setup service on the server side to get the device collection URL.

API - https://secure.telr.com/gateway/remote_mpi.xml

Request:

<?xml version="1.0" encoding="UTF-8"?>
<remote>
    <method>setup</method>
    <store>12345</store>
    <key>my_api_key</key>
    <tran>
        <type>sale</type>
        <class>ecom</class>
        <cartid>cart1234</cartid>
        <description>Test Remote API</description>
        <currency>AED</currency>
        <amount>1</amount>
        <test>0</test>
    </tran>
    <card>
        <number>1234567891234567</number>
        <expiry>
            <month>09</month>
            <year>2027</year>
        </expiry>
        <cvv>123</cvv>
    </card>
    <browser>
        <agent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)
            Chrome/55.0.2883.87 Safari/537.36</agent>
        <accept>*/*</accept>
    </browser>
    <mpi>
        <returnurl>https://www.merchanturl.com</returnurl>
    </mpi>
    <billing>
        <name>
            <title>Mr</title>
            <first>Test</first>
            <last>User</last>
        </name>
        <address>
            <line1>Digital Park</line1>
            <city>Dubai</city>
            <region>Dubai</region>
            <country>AE</country>
            <zip>001</zip>
        </address>
        <email>[email protected]</email>
        <phone>1234456</phone>
    </billing>
</remote>

Response:


<?xml version="1.0" encoding="UTF-8"?>
<remote>
    <mpi>
        <session>94536e57165d65f166c7ee2da02c7d</session>
        <scheme>VI</scheme>
        <redirecthtml>%3cdiv%20id%3d%22initiate3dsSimpleRedirect%22%3e%0a%3ciframe%20id%3d%22cardinal_collection_iframe%22%20name%3d%22collectionIframe%22%20height%3d%2210%22%20width%3d%2210%22%20style%3d%22display%3a%0anone;%22%3e%3c%2fiframe%3e%0a%3cform%20id%3d%22cardinal_collection_form%22%20method%3d%22POST%22%20target%3d%22collectionIframe%22%20action%3dhttps%3a%2f%2fcentinelapi.cardinalcommerce.com%2fV1%2fCruise%2fCollect%3e%0a%3cinput%20id%3d%22cardinal_collection_form_input%22%20type%3d%22hidden%22%20name%3d%22JWT%22%0avalue%3d%22eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1NTYxMTEzYy05YmRiLTQxZGItOTc5OC05ZDU1YWI0YjkyNWYiLCJpYXQiOjE3MTAzMTkzMDUsImlzcyI6IjVlMjIwMDVmMzU2ZGNlMDNmMGY3ODcyZiIsImV4cCI6MTcxMDMyMjkwNSwiT3JnVW5pdElkIjoiNjRkMjRhNjRmMmZiNTU2MGZiYWIyZTY3IiwiUmVmZXJlbmNlSWQiOiI3ZjI5ZTMyMS0zZWI0LTRiNzQtOGU3NS1kYzRjYzc2YTYwZjAifQ.FOJpV9P6lHhk5HfcqZ07-rmY_tbvM7TtVjVgHWRBNXs%22%3e%0a%3c%2fform%3e%0a%3cscript%20id%3d%22initiate-authentication-script%22%3e%20%0avar%20e%3ddocument.getElementById(%22cardinal_collection_form%22);%20%0aif%20(e)%20%7b%20e.submit();%20if%20(e.parentNode%20!%3d%3d%20null)%20%7b%20e.parentNode.removeChild(e);%20%7d%20%7d%20%0a%3c%2fscript%3e%0a%3c%2fdiv%3e%0a</redirecthtml>
        <action>wait</action>
        <eventURL>https://centinelapi.cardinalcommerce.com</eventURL>
        <trace>4001/2990124/65f166c7</trace>
    </mpi>
</remote>

Parameter	Description
redirectHtml	Device collection URL
action	Possible actions values are 'wait' & 'proceed' wait - ‘eventurl’ received in response can be used to check the device collection has been successfully completed by adding an event listener on ‘eventurl’ before triggering next API proceed - proceed to execute next API
session	Session reference for this transaction. Must be included in the further APIs

How to use Device Collection URL?

Returned Device URL must be injected into hidden Iframe to carry out the device collection. Below is the example showing how to insert the redirect html received from setup authentication response.

    var redirect_html="%3cdiv%20id%3d%22threedsChallengeRedirect%22%20xmlns%3d%22http%3a%2f%2fwww.w3.org%2f1999%2fhtml%22%20style%3d%22height%3a%20100vh%22%3e%0a%3cform%20id%3d%22threedsChallengeRedirectForm%22%20method%3d%22POST%22%20action%3d%22https%3a%2f%2fcentinelapi.cardinalcommerce.com%2fV2%2fCruise%2fStepUp%22%20target%3d%22challengeFrame%22%3e%20%3cinput%20type%3d%22hidden%22%20name%3d%22JWT%22%20value%3d%22eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJlZWIxNzQ5OC02Y2Q2LTQzOWYtYjRmMy1mNDc1YmJkNTk3YTEiLCJpYXQiOjE3MTAzMTk5MDksImlzcyI6IjVlMjIwMDVmMzU2ZGNlMDNmMGY3ODcyZiIsImV4cCI6MTcxMDMyMzUwOSwiT3JnVW5pdElkIjoiNjRkMjRhNjRmMmZiNTU2MGZiYWIyZTY3IiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL2F1dGhlbnRpY2F0aW9uLmNhcmRpbmFsY29tbWVyY2UuY29tL1RocmVlRFNlY3VyZS9WMl8xXzAvQ1JlcSIsIlBheWxvYWQiOiJleUp0WlhOellXZGxWSGx3WlNJNklrTlNaWEVpTENKdFpYTnpZV2RsVm1WeWMybHZiaUk2SWpJdU1pNHdJaXdpZEdoeVpXVkVVMU5sY25abGNsUnlZVzV6U1VRaU9pSTROakJtT0RaaE15MWtaRGcyTFRSaVlqZ3RPVFV4TkMwek5HUmlPRGcwWkRVMU5XWWlMQ0poWTNOVWNtRnVjMGxFSWpvaVlXRXdOMkV4WXpRdE1EWTNPQzAwTkRkbExUZ3pZek10TVRSbE16RTNNVEEwWmpVNElpd2lZMmhoYkd4bGJtZGxWMmx1Wkc5M1UybDZaU0k2SWpBeUluMCIsIlRyYW5zYWN0aW9uSWQiOiJOMnZSTm1pMGFTdUlwY1Y0NzI4MSJ9LCJPYmplY3RpZnlQYXlsb2FkIjp0cnVlLCJSZXR1cm5VcmwiOiJodHRwczovL3d3dy50ZWxyLmNvbSJ9.O5BhI1StOkk6mkq6PIJotNopbD6Cqi3edTF9zE0joQc%22%20%2f%3e%20%3c%2fform%3e%0a%3ciframe%20id%3d%22challengeFrame%22%20name%3d%22challengeFrame%22%20width%3d%22100%25%22%20height%3d%22100%25%22%20%3e%3c%2fiframe%3e%0a%3cscript%20id%3d%22authenticate-payer-script%22%3e%20var%20e%3ddocument.getElementById(%22threedsChallengeRedirectForm%22);%20if%20(e)%20%7b%20e.submit();%20if%20(e.parentNode%20!%3d%3d%20null)%20%7b%20e.parentNode.removeChild(e);%20%7d%20%7d%20%3c%2fscript%3e%0a%3c%2fdiv%3e%0a";
		var txt = document.createElement("textarea");
		txt.innerHTML = redirect_html;
		redirect_html_new = decodeURIComponent(txt.value);
		document.body.innerHTML = redirect_html_new;
		eval(document.getElementById('initiate-authentication-script').text)

2. Check enrollment

To obtain the challenge URL, the Check Enrollment API must be invoked. The response will either contain a challenge URL that will render the cardholder OTP page or confirmation to proceed directly to authorization (frictionless flow).

API - https://secure.telr.com/gateway/remote_mpi.xml

Request:


<?xml version="1.0" encoding="UTF-8"?>
<remote>
    <method>authenticate</method>
    <store>12345</store>
    <key>my_api_key</key>
    <tran>
        <type>sale</type>
        <class>ecom</class>
        <cartid>cart1234</cartid>
        <description>Test Remote API</description>
        <currency>AED</currency>
        <amount>1</amount>
        <test>0</test>
    </tran>
    <card>
        <number>1234567891234567</number>
        <expiry>
            <month>09</month>
            <year>2027</year>
        </expiry>
        <cvv>123</cvv>
    </card>
    <browser>
        <agent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)
            Chrome/55.0.2883.87 Safari/537.36</agent>
        <accept>*/*</accept>
    </browser>
    <mpi>
        <returnurl>https://www.telr.com</returnurl>
    </mpi>
    <billing>
        <name>
            <title>Mr</title>
            <first>Test</first>
            <last>User</last>
        </name>
        <address>
            <line1>Digital Park</line1>
            <city>Dubai</city>
            <region>Dubai</region>
            <country>AE</country>
            <zip>001</zip>
        </address>
        <email>[email protected]</email>
        <phone>1234456</phone>
    </billing>
    <mpi>
        <session>94536e57165d65f166c7ee2da02c7d</session>
    </mpi>
</remote>

Response:


<?xml version="1.0" encoding="UTF-8"?>
<remote>
    <mpi>
        <session>94536e57165d65f166c7ee2da02c7d</session>
        <xid>860f86a3-dd86-4bb8-9514-34db884d555f</xid>
        <scheme>VI</scheme>
        <enrolled>Y</enrolled>
        <redirecthtml>%3cdiv%20id%3d%22threedsChallengeRedirect%22%20xmlns%3d%22http%3a%2f%2fwww.w3.org%2f1999%2fhtml%22%20style%3d%22height%3a%20100vh%22%3e%0a%3cform%20id%3d%22threedsChallengeRedirectForm%22%20method%3d%22POST%22%20action%3d%22https%3a%2f%2fcentinelapi.cardinalcommerce.com%2fV2%2fCruise%2fStepUp%22%20target%3d%22challengeFrame%22%3e%20%3cinput%20type%3d%22hidden%22%20name%3d%22JWT%22%20value%3d%22eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJlZWIxNzQ5OC02Y2Q2LTQzOWYtYjRmMy1mNDc1YmJkNTk3YTEiLCJpYXQiOjE3MTAzMTk5MDksImlzcyI6IjVlMjIwMDVmMzU2ZGNlMDNmMGY3ODcyZiIsImV4cCI6MTcxMDMyMzUwOSwiT3JnVW5pdElkIjoiNjRkMjRhNjRmMmZiNTU2MGZiYWIyZTY3IiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL2F1dGhlbnRpY2F0aW9uLmNhcmRpbmFsY29tbWVyY2UuY29tL1RocmVlRFNlY3VyZS9WMl8xXzAvQ1JlcSIsIlBheWxvYWQiOiJleUp0WlhOellXZGxWSGx3WlNJNklrTlNaWEVpTENKdFpYTnpZV2RsVm1WeWMybHZiaUk2SWpJdU1pNHdJaXdpZEdoeVpXVkVVMU5sY25abGNsUnlZVzV6U1VRaU9pSTROakJtT0RaaE15MWtaRGcyTFRSaVlqZ3RPVFV4TkMwek5HUmlPRGcwWkRVMU5XWWlMQ0poWTNOVWNtRnVjMGxFSWpvaVlXRXdOMkV4WXpRdE1EWTNPQzAwTkRkbExUZ3pZek10TVRSbE16RTNNVEEwWmpVNElpd2lZMmhoYkd4bGJtZGxWMmx1Wkc5M1UybDZaU0k2SWpBeUluMCIsIlRyYW5zYWN0aW9uSWQiOiJOMnZSTm1pMGFTdUlwY1Y0NzI4MSJ9LCJPYmplY3RpZnlQYXlsb2FkIjp0cnVlLCJSZXR1cm5VcmwiOiJodHRwczovL3d3dy50ZWxyLmNvbSJ9.O5BhI1StOkk6mkq6PIJotNopbD6Cqi3edTF9zE0joQc%22%20%2f%3e%20%3c%2fform%3e%0a%3ciframe%20id%3d%22challengeFrame%22%20name%3d%22challengeFrame%22%20width%3d%22100%25%22%20height%3d%22100%25%22%20%3e%3c%2fiframe%3e%0a%3cscript%20id%3d%22authenticate-payer-script%22%3e%20var%20e%3ddocument.getElementById(%22threedsChallengeRedirectForm%22);%20if%20(e)%20%7b%20e.submit();%20if%20(e.parentNode%20!%3d%3d%20null)%20%7b%20e.parentNode.removeChild(e);%20%7d%20%7d%20%3c%2fscript%3e%0a%3c%2fdiv%3e%0a</redirecthtml>
        <action>challenge</action>
        <trace>4000/3197532/65f16923</trace>
    </mpi>
</remote>

Parameter:

Parameter	Description
redirectHtml	challenge URL
action	Possible actions values are 'challenge' & 'proceed' challenge - use ‘redirecthtml’ received in check enrolment response and invoke the iframe form POST in it proceed - its a frictionless flow, proceed to execute next API

How to use challenge URL?

Here is the example how received Challenge URL can be invoked as below -

Note - The invokation should be done in a modal view within 30 seconds, otherwise redirectHtml URL will time out.

    var redirect_html="%3cdiv%20id%3d%22threedsChallengeRedirect%22%20xmlns%3d%22http%3a%2f%2fwww.w3.org%2f1999%2fhtml%22%20style%3d%22height%3a%20100vh%22%3e%0a%3cform%20id%3d%22threedsChallengeRedirectForm%22%20method%3d%22POST%22%20action%3d%22https%3a%2f%2fcentinelapi.cardinalcommerce.com%2fV2%2fCruise%2fStepUp%22%20target%3d%22challengeFrame%22%3e%20%3cinput%20type%3d%22hidden%22%20name%3d%22JWT%22%20value%3d%22eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJlZWIxNzQ5OC02Y2Q2LTQzOWYtYjRmMy1mNDc1YmJkNTk3YTEiLCJpYXQiOjE3MTAzMTk5MDksImlzcyI6IjVlMjIwMDVmMzU2ZGNlMDNmMGY3ODcyZiIsImV4cCI6MTcxMDMyMzUwOSwiT3JnVW5pdElkIjoiNjRkMjRhNjRmMmZiNTU2MGZiYWIyZTY3IiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL2F1dGhlbnRpY2F0aW9uLmNhcmRpbmFsY29tbWVyY2UuY29tL1RocmVlRFNlY3VyZS9WMl8xXzAvQ1JlcSIsIlBheWxvYWQiOiJleUp0WlhOellXZGxWSGx3WlNJNklrTlNaWEVpTENKdFpYTnpZV2RsVm1WeWMybHZiaUk2SWpJdU1pNHdJaXdpZEdoeVpXVkVVMU5sY25abGNsUnlZVzV6U1VRaU9pSTROakJtT0RaaE15MWtaRGcyTFRSaVlqZ3RPVFV4TkMwek5HUmlPRGcwWkRVMU5XWWlMQ0poWTNOVWNtRnVjMGxFSWpvaVlXRXdOMkV4WXpRdE1EWTNPQzAwTkRkbExUZ3pZek10TVRSbE16RTNNVEEwWmpVNElpd2lZMmhoYkd4bGJtZGxWMmx1Wkc5M1UybDZaU0k2SWpBeUluMCIsIlRyYW5zYWN0aW9uSWQiOiJOMnZSTm1pMGFTdUlwY1Y0NzI4MSJ9LCJPYmplY3RpZnlQYXlsb2FkIjp0cnVlLCJSZXR1cm5VcmwiOiJodHRwczovL3d3dy50ZWxyLmNvbSJ9.O5BhI1StOkk6mkq6PIJotNopbD6Cqi3edTF9zE0joQc%22%20%2f%3e%20%3c%2fform%3e%0a%3ciframe%20id%3d%22challengeFrame%22%20name%3d%22challengeFrame%22%20width%3d%22100%25%22%20height%3d%22100%25%22%20%3e%3c%2fiframe%3e%0a%3cscript%20id%3d%22authenticate-payer-script%22%3e%20var%20e%3ddocument.getElementById(%22threedsChallengeRedirectForm%22);%20if%20(e)%20%7b%20e.submit();%20if%20(e.parentNode%20!%3d%3d%20null)%20%7b%20e.parentNode.removeChild(e);%20%7d%20%7d%20%3c%2fscript%3e%0a%3c%2fdiv%3e%0a";
		var txt = document.createElement("textarea");
		txt.innerHTML = redirect_html;
		redirect_html_new = decodeURIComponent(txt.value);
		document.body.innerHTML = redirect_html_new;
		eval(document.getElementById('authenticate-payer-script').text)

3. Authorization

After obtaining the challenge URL and entering the OTP, the transaction processing can be finalized through a remote request to authorize the request. Request must include MPI session ID received in the previous step.

API - https://secure.telr.com/gateway/remote.xml

Request:


<?xml version="1.0" encoding="UTF-8"?>
<remote>
    <store>12345</store>
    <key>my_api_key</key>
    <tran>
        <type>sale</type>
        <class>ecom</class>
        <cartid>cart1234</cartid>
        <description>Test Remote API</description>
        <currency>AED</currency>
        <amount>1</amount>
        <test>0</test>
    </tran>
    <card>
        <number>1234567891234567</number>
        <expiry>
            <month>09</month>
            <year>2027</year>
        </expiry>
        <cvv>123</cvv>
    </card>
    <billing>
        <name>
            <title>Mr</title>
            <first>Test</first>
            <last>User</last>
        </name>
        <address>
            <line1>Digital Park</line1>
            <city>Dubai</city>
            <region>Dubai</region>
            <country>AE</country>
            <zip>001</zip>
        </address>
        <email>[email protected]</email>
        <ip>1.2.3.4</ip>
    </billing>
    <mpi>
        <session>94536e57165d65f166c7ee2da02c7d</session>
    </mpi>
</remote>

Response:


<?xml version="1.0" encoding="UTF-8"?>
<remote>
    <auth>
        <status>A</status>
        <code>212734</code>
        <message>Authorised</message>
        <tranref>040032155495</tranref>
        <cvv>Y</cvv>
        <avs>X</avs>
        <trace>4001/2995618/65f1696c</trace>
    </auth>
    <payment>
        <code>VC</code>
        <description>Visa Credit ending 0002</description>
        <card_end>0002</card_end>
        <card_bin>457828</card_bin>
    </payment>
</remote>

Below table describes the fields in the response message.

Field	Description
status	Authorisation status. A indicates an authorised transaction. Any other value indicates that the request could not be processed.
code	"If the transaction was authorised this contains the authorisation code from" the card issuer. Otherwise it contains a code indicating why the transaction could not be processed.
message	The authorisation or processing error message.
tranref	The payment gateway transaction reference allocated to this request.
cvv	Result of the CVV check: Y = CVV matched OK N = CVV not matched X = CVV not checked "E = Error unable to check CVV"
avs	Result of the AVS check: Y = AVS matched OK "P = Partial match (for example post-code only)" N = AVS not matched X = AVS not checked "E = Error unable to check AVS"

The AVS check is currently only available for cards issued in the United Kingdom, United States of America or Canada.

Implementation best practices

The following points will assist you in implementing 3-D Secure in a way which is compliant with scheme requirements, and most importantly easy for the cardholder to use and therefore complete transactions.

Pre-Authentication message

You should include a brief message to cardholders on the checkout page informing them that they may be required to provide additional authentication details. The message must not say that this will happen, as in some cases the process may continue without an authentication screen. This message should be placed on the page where it is likely the cardholder will notice and read it – for example next to the button that has to be clicked to make the payment.

A recommended pre-authentication message is as follows:

The next screen you see may be payment card verification through your card issuer.

3-D Secure logos

You should display the appropriate 3-D Secure logos (such as Verified by Visa or Mastercard SecureCode) on the payment page as an additional method of indicating to the cardholder that the authentication steps may be required. If also serves to reassure cardholders if the authentication page is displayed as they have already seen the relevant logos within your payment page.

Layout

It is recommended to use a modal view that is rendered on top of the checkout page for the 3-D Secure authentication screen. Full width and full height of modal views should be used on mobile devices.

Points to keep in mind:

Provide enough space so that the 3-D Secure frame can fit. The minimum size required is
250 x 400.
Avoid having a ‘crowded’ screen which could cause confusion
Ensure that the 3-D Secure frame is not pushed out of the viewable area on low resolution
screens. The 3-D Secure frame must be viewable without having to scroll.
There should not be other links or exit points that may distract the cardholder from
completing the 3-D Secure process (such as search options, navigation menus etc).
All page elements must be HTTPS. Never mix HTTP and HTTPS.

Activity indicators

You should display something to the cardholder that lets them know authorisation is in progress. It may take several seconds for the initial cardholder enrolment checks to be undertaken, and you don’t want the cardholder to think that the process has stopped and abort the purchase.

The activity indicators should include some visual movement to reassure the cardholder that the process is continuing.

Activity indicators should be displayed during the initial MPI check to find out if additional authentication is required, and again during the actual authorisation process.

No promotional messages

Visa mandate that merchants must not display promotional messages to cardholders during the payment process, for example messages advertising special offers.