Using 3-D Secure with Remote Integration

Remote Integration allows merchants to use the gateway's MPI without installing any additional components. This simplifies the integration process by removing the need for direct MPI implementation on your servers.

To complete the payment, the following three APIs must be invoked in sequence:

Device data collection
Check enrollment
Authorization

1. Device data collection

Initiate the Payer Authentication Setup service on the server side to obtain 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>
        <width>300</width>
        <height>600</height>
    </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>
        <phone>1234456</phone>
        <ip>IP address</ip>
        <email>cardholder@email.com</email>
    </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 – The eventurl provided in the response should be used to confirm if device collection has completed. You can listen to this URL before proceeding to the next API.

session

Session reference for this transaction. Must be included in the further APIs

How to use Device Collection URL?

The returned device collection URL must be injected into a hidden iframe to perform device fingerprinting.Below is an example demonstrating how to inject the redirecthtml received from the 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 include a challenge URL to display the cardholder’s OTP screen, or indicate a frictionless flow allowing you to proceed directly to authorization.

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>
				<threeds2enabled>1</threeds2enabled>
    </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>
        <width>300</width>
        <height>600</height>
    </browser>
    <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>
        <phone>1234456</phone>
        <ip>IP address</ip>
        <email>cardholder@email.com</email>
    </billing>
    <mpi>
      <session>94536e57165d65f166c7ee2da02c7d</session>
			<returnurl>https://www.telr.com</returnurl>
    </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 the redirecthtml received in the Check Enrollment response and invoke the form POST within an iframe.proceed – Indicates a frictionless flow; continue directly to the next API (authorization).

How to use challenge URL?

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

📘
The invocation must occur within 30 seconds inside a modal view; otherwise, the redirecthtml URL may 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)

Error response format

When an MPI API call fails, the response will include a standardized numeric error code along with a descriptive error message:

<remote>
    <code>5</code>
    <error>Error message corresponding to the error code</error>
    <mpi>
        <trace>4001/1487942/682c2d64</trace>
    </mpi>
</remote>

code : Standardized numeric error code.
error: Description of the error.
trace: Debug trace ID.

You can find the full list of error codes and their meanings in our authorisation response codes reference.

3. Authorization

After the challenge is completed and OTP is entered (if applicable), the transaction can be finalized by calling the Authorization API. The request must include the MPI session ID obtained from 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>cardholder@email.com</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>
        <networktranid>123456789</networktranid>
        <cartid>abc123</cartid>
        <rrn>123456</rrn>
        <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 is authorized, this contains the authorization code returned by 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 matchedN = CVV did not match X = CVV check not performed E = Error occurred during CVV validation
avs	Result of the AVS check: Y = AVS matched OKP = Partial match (for example post-code only) N = AVS not matched X = AVS not checked E = Error unable to check AVS
networktranid	Payment network transaction id
cartid	Unique cartid value which will be passed in request
rrn	Retrieval reference number

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. Avoid stating that authentication will occur, as in some cases the transaction may proceed without showing 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. It also helps reassure cardholders if the authentication screen appears, as they’ve already seen the relevant logos on 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.Visa mandate that merchants must not display promotional messages to cardholders during the payment process, for example messages advertising special offers.