What is 3DS API?

  Last updated: 


Our 3-D Secure standalone server-to-server solution enables you to have full control over the 3-D Secure authentication process, including redirecting the customer's browser to pages hosted by the Access Control Server (ACS) when step-up authentication is required. Following authentication, you can use the TRU Connect gateway or a third party gateway to process the payment.



  You must contact our Support Team to request a 3DS API test site reference to allow you to begin testing.

  Before you get started, you will need a Web Services username and password to allow us to authenticate your requests.

You can create a Web Services user using our MyST interface. Your system will need to submit this username in every request, along with the password. In our request examples we use a placeholder username and password, which you will need to replace with your own credentials before testing.

If you don’t already have Web Services credentials, click here to learn how to configure this.


Process overview



    Your system submits a THREEDLOOKUP request using Webservices API. The response determines whether the customer's card is enrolled in the 3-D Secure scheme and the version to be used for authentication.

    Your system will be expected to handle the THREEDLOOKUP response. For subsequent steps, you will need to parse the following fields:

    • threedmethodurl, a field returned if 3-D Secure authentication is version 2.1.0 and above, and if deemed necessary by the card issuer. This is used to submit the HTTPS POST in step 2.
    • cachetoken, a unique reference to the authentication process.
    • threedstransactionid, a universally unique transaction identifier assigned by the 3DS Server to identify a single transaction for 3-D Secure version 2.1.0 and higher.
    • threedversion - Identifies the version of 3-D Secure authentication employed.

  2. Method URL

      This step is only required if threedmethodurl is returned in the THREEDLOOKUP response. Otherwise, skip to step 3 below.

    This step is used by an ACS (Access Control Server) to gather the device fingerprint of the customer's browser.

    Your system submits an HTTPS POST to the ACS using the threedmethodurl, including the threedstransactionid (returned in step 1) and threednotificationurl.

    The default threednotificationurl value returned in the THREEDLOOKUP must be overridden with your own endpoint URL. This is used to receive an HTTPS POST from the ACS confirming the completion of the Method URL step.


    This is to initiate the authentication process. Your system submits a THREEDQUERY request using Webservices API containing the following fields:

    • cachetoken, returned in step 1 (THREEDLOOKUP).
    • termurl - The termurl is the endpoint that you define, for the customer's browser to be returned following step-up authentication (click here to learn more about step-up authentication), and also includes the results of the authentication performed.
    • threedscompind, determined by the outcome of step 2 (Method URL). If step 2 was skipped, set value to "U".
    • threedstransactionid from the THREEDLOOKUP response (step 1).

    The THREEDQUERY response determines whether the customer needs to be redirected to verify their identity on the card issuer's ACS. If acsurl is returned, proceed to step 4, otherwise skip to step 5.

  4. Challenge

      Only perform this step if acsurl is returned in THEEDQUERY response.

    If the customer issuing bank requires additional authentication and the customer needs to complete step-up authentication, the acsurl will be returned in the THREEDQUERY response. The customer's browser will need to be redirected to the acsurl. Once completed, the customer's browser will be redirected to the termurl you define in step 3.

      If the customer issuing bank requires deems additional authentication unnecessary, the acsurl will not be returned in the THREEDQUERY response, the payment is considered to be frictionless and you can immediately proceed to step 5, below.


    Your server then submits a THREEDRESULT request using Webservices API, including the parenttransactionreference that references the THREEDQUERY from step 3.

    A THREEDRESULT response will include the authentication result data that you can use to determine whether it is safe to proceed with a payment.

  6. AUTH

    Once the 3-D Secure process has completed, it is now time to process a transaction. Should you wish to proceed with the payment using the TRU Connect gateway, your server submits an AUTH request using Webservices API, including additional fields that you have received in the THREEDRESULT response.


Going live

In order to go live, you will need to sign up and agree to commercial terms for this service. Please contact your Trust Payments representative to discuss signing up for this service.


  Ready to get started?

Use the navigation buttons at the bottom of the page to walk through the setup process.

Next:   Getting started with 3DS API    

Was this article helpful?
0 out of 0 found this helpful