3D Secure Authentication

On this page:

Overview

3D Secure authentication is a fraud prevention scheme available to Opayo merchants. In accordance the European Union’s (EU) Second Payment Service Directive (PSD2), all eCommerce transactions where the cardholder is in-session must perform 3D Secure authentication. During 3D Secure authentication, a challenge authentication known as Strong Customer Authentication (SCA) can take place. A Frictionless Authentication may also take place.

Important: You must activate 3D Secure on your account and set it up with your acquirer before transactions can be re-directed to the scheme.

    Activate 3D Secure

    To learn how to activate 3D Secure using MySagePay, read our Using 3D Secure guide and watch our video, MySagePay – activating & adding 3D Secure rules.   

    Submit a 3D Secure Transaction

    Step 1: Submit the transaction request

    For test transactions, submit your transaction registration POST to: https://pi-test.sagepay.com/api/v1/transactions/

    For live transactions, submit your transaction registration POST to: https://pi-live.sagepay.com/api/v1/transactions/

    Important: You must submit the strongCustomerAuthentication object with your initial transaction request.

    The process of obtaining a 3-D Secured authentication for a transaction begins in the same manner as a normal transaction. You will need to generate a merchantSessionKey and a cardIdentifier and then submit a transaction registration POST.

    When you make the transaction registration POST you can override the MySagePay settings for that transaction by using the apply3DSecure field, otherwise the MySagePay settings will be used.

    If we receive a transaction POST which requires 3-D Secure authentication, we will check if the card and the card issuer are enrolled in the 3-D Secure scheme. If they are not enrolled, and you have set rules requiring that they are, the transaction will be rejected and we will provide you with the appropriate response via the status in the 3-D Secure object.

    Here is an example response for this scenario:

    {
    "statusCode": "4026", 
    "statusDetail": "3D-Authentication failed. This vendor's rules require a successful 3D-Authentication.", 
    "transactionId": "EAF65750-EFBF-1423-97E4-68965CCB3189", 
    "status": "Rejected" 
    }

    If those rules aren't in place the transaction will proceed for authorisation without going through 3-D Secure and you will receive the normal transaction response. You will be able to see the outcome of the 3-D Secure via the status field under the 3DSecure object as per the example below:

    {
    "statusCode": "0000",
    "statusDetail": "The Authorisation was Successful.",
    "transactionId": "779941BE-692E-1DD4-989A-64D2A584C763",
    "transactionType": "Payment",
    "retrievalReference": 10059868,
    "bankResponseCode": "00",
    "bankAuthorisationCode": "999777",
    "status": "Ok",
    "3DSecure":
    {
    "status": "NotChecked"
    }

     

    When you have no set rules

    When there are no rules in place, then:

    • The transaction will proceed for authorisation without going through 3D Secure.
    • You will receive the normal transaction response.

    You can find the outcome of the 3D Secure checks via the status field under the 3DSecure object as in the following example:

    {
      "statusCode":"0000",
      "statusDetail":"The Authorisation was Successful.",
      "transactionId":"779941BE-692E-1DD4-989A-64D2A584C763",
      "transactionType":"Payment",
      "retrievalReference":10059868,
      "bankResponseCode":"00",
      "bankAuthorisationCode":"999777",
      "status":"Ok",
      "3DSecure":{
        "status":"NotChecked"
      }
    }

    Step 2: Handling the response and customer redirection

    When the card and the card issuer are enrolled in the 3D Secure scheme, then we will respond with the information needed to complete the 3D Secure authentication. The response can advise of three possible 3D Secure authentication outcomes:

    Frictionless authentication

    When the card issuer has enough cardholder data to authenticate the transaction without the cardholder performing two-factor authentication, then the authentication process is complete. Opayo will respond to you the authentication and authorisation (if rules permit) result.

    Example response for a frictionless authentication outcome:
     {
      "statusCode":"0000",
      "statusDetail":"The Authorisation was Successful.",
      "transactionId":"D4ED06EA-EE0F-A527-FEA4-E61AAB6E6FEB",
      "acsTransId":"43b04fd1-692c-4b76-ac20-a75527ad0a25",
      "dsTranId":"7980e36f-907b-4530-84fd-ccc1f40bf9ae",
      "transactionType":"Payment",
      "retrievalReference":15280,
      "bankResponseCode":"00",
      "bankAuthorisationCode":"999777",
      "paymentMethod":{
        "card":{
          "cardType":"Visa",
          "lastFourDigits":"7067",
          "expiryDate":"0320",
          "cardIdentifier":"B6C3A8D4-F47A-4776-A1FC-7CEA70E1FFFF",
          "reusable":false
        }
      },
      "amount":{
        "totalAmount":41000,
        "saleAmount":41000,
        "surchargeAmount":0
      },
      "currency":"GBP",
      "fiRecipient":{
        
      },
      "status":"Ok",
      "avsCvcCheck":{
        "status":"NotChecked",
        "address":"NotProvided",
        "postalCode":"NotProvided",
        "securityCode":"NotProvided"
      },
      "3DSecure":{
        "status":"Authenticated"
      }
    }

    Challenge authentication

    When the card issuer requires the cardholder to undergo two-factor authentication you:

    • Will receive a cReq field in the response.
    • Must redirect the cardholder to their card issuers site (Access Control Server - ACS) to enter their two-factor authentication credentials.
    • Must POST the response from this step to Opayo. Opayo will then respond with the authentication and authorisation (if rules permit) result.
    Example response for a challenge authentication outcome
    {
      "statusCode":"2021",
      "statusDetail":"Please redirect your customer to the ACSURL to complete the 3DS Transaction",
      "transactionId":"BEB718F6-3ED2-323E-2CB2-B8C83DB2029C",
      "acsTransId":"43b04fd1-692c-4b76-ac20-a75527ad0a25",
      "dsTranId":"7980e36f-907b-4530-84fd-ccc1f40bf9ae",
      "acsUrl":"https://localhost:8252/html_challenge",
      "status":"3DAuth",
      "cReq":"eyJtZXNzYWdlVHlwZSI6IkNSZXEi...V2luZG93U2l6ZSI6IjAxIn0"
    }
    

    When you receive a 3DAuth status from Opayo in the response, build a simple auto-submitting form like the example below. This sends the, creq, the recommended field threeDSSessionData, and the cardholder's browser to the acsUrl.

    We recommend that the threeDSSessionData value contains the value of transactionId so you can keep track of your customer, and the transaction, after they return from the ACS.

    Important: When you forward the cReq field to the acsURL, please ensure you pass the cReq value that we send you in a field called creq (note the lower case 'r'). The ACS will not accept the data if you pass the wrong case.

    You can use threeDSSessionData to pass your session specific data to the card issuers 3D Secure provider (ACS provider) when submitting the cReq  to the acsURL. This data will be returned to your system by the ACS provider when they return the cardholder and cres to your ThreeDSNotificationURL value. The threeDSSessionData helps you to recognise your customer and allows you to continue the transaction flow when they return from the ACS provider. If you don’t have your own session data and need a way to recognise your customer when they return, then it is advisable to use the VPSTxId value that Opayo returns to you with the CReq and that you send to Opayo with the CRes. threeDSSessionData is optional and can only be used during  a 3DSv2 authentication flow.

    The threeDSSessionData must be BASE64 URL encoded, and is limited 1024 bytes in length.

    Example of an auto-submitting form using an iFrame
     <iframe src="/3DRedirect.asp" name="3Diframe">
       <form action="/%24%7BacsUrl%7D" method="post">
         <input type="hidden" name="creq" value="${creq}" />
         <input type="hidden" name="threeDSSessionData" value="${threeDSSessionData}" />
         <p>Please click button below to proceed to 3D secure.</p> <input type="submit" value="Go"/>
       </form>
     </iframe>
    

    Fallback

    When the cardholder or card issuer are not enrolled for 3DSv2, or there is an MPI error communicating to the 3DSv2 service, Opayo will fallback to 3DSv1. In this case, you:

    • Will receive a paReq field in the response.
    • Must redirect the cardholder to their card issuers site (ACS) to enter their authentication credentials.
    • Must POST the response from this step to Opayo. Opayo will then respond with the authentication result only, you will then query for the authorisation result. (Refer to Step 4. Getting the transaction outcome).
    Example response for a fallback outcome
    {
      "statusCode":"2007",
      "statusDetail":"Please redirect your customer to the ACSURL to complete the 3DS Transaction",
      "transactionId":"DFAF9D9A-CD17-A4DF-B5A0-D9A9D88E4468",
      "acsUrl":"https://test.opayo.co.uk/mpitools/accesscontroler?action=pareq",
      "paReq":"eJxVUstuwjAQvPcrolwrxXaeCC1GtB...2WD1jFj8RAZvQztwd7ZIGgAEFNLxu2RcdEY/fsAv12RstM=",
      "status":"3DAuth"
    }

    When you receive our response with a status of 3DAuth, you must return to the cardholder a page or iFrame containing a form with hidden attributes that POSTs the paReq and two additional fields called TermUrl and MD to the 3D Secure provider located at the acsUrl.

    Example of a self-submitting version of the form
    <form id="pa-form" method="post" action="/%5BINSERT%20ACS%20URL%5D%20%20">
      <input type="hidden" name="PaReq" value="[PREVIOUSLY RETURNED PAREQ]">
      <input type="hidden" name="TermUrl" value="[ENDPOINT ON YOUR SERVER WHICH HANDLES RESPONSE FROM 3DSECURE PROVIDER]">   
      <input type="hidden" name="MD" value="[YOUR UNIQUE REFERENCE NUMBER FOR THIS AUTHENTICATION]">  
    </form>    
    <script>document.addEventListener("DOMContentLoaded",function(){var b=document.getElementById("pa-form");b&&b.submit()})</script>

    This sends your customer to their card issuer's 3D Secure authentication page, located at the ascUrl with all of the information needed to perform authentication. This is completed using a full page redirect or inside an iFrame.

    Response Status

    Response statuses

     Status

    Status description

    Ok

    Transaction request completed succesfully

    NotAuthed

    Transaction request was not authorised

    Rejected

    Transaction rejected by your fraud rules

    Malformed

    Missing properties or badly formed body

    Invalid

    Invalid property values supplied

    Error

    An error occured at Opayo

     

    Important: When posting to the acsURL, the parameters in the request body must be specified in PascalCase as follows:

    TermUrl=https://my-merchant-website.com/payment-3d-secure/3d-secure-mpi-response&PaReq=XX&MD=YY

    Step 3: Handling the 3D Secure authentication response from the ACS

    Handling a challenge response outcome

    1. The cardholder completes the 3D-authentication process at the ACS.
    2. The ACS submits the authentication result directly to Opayo.
    3. Opayo responds with an acknowledgement.
    4. When the ACS receives the acknowledgement, it will redirect the cardholder back to the URL you supplied for notificationURL. The redirection contains two fields with values that must be submitted in a HTTP POST to the notificationURL:
      1. threeDSSessionData (which should contain the value of the transactionId, as long as you submitted this value to the ACS)
      2. cres (challenge result - this is the authentication result).
    5. The code in your notificationURL should format a simple HTTPS, server-side POST, and send the cRes and the transactionId to the Opayo 3D Secure callback API listed below.
    Important: When you forward the cres field to Opayo, please ensure you pass the cres value that the ACS sent you, in a field called cRes to Opayo. Note the uppercase R.
    Important: Please note that the paRes or cRes for a transaction has to be provided within 20 minutes from our initial response.

    Opayo 3D Secure callback API

    When Opayo receives the cRes and transactionId from you, it compares them against the already held values:

    • If the values match and the cardholder has passed authentication, Opayo will submit an authorisation request to your acquirer.
    • If the values do not match, then Opayo will return an error and the transaction ends.
    • If the cardholder fails authentication, Opayo will check your rules to determine if authorisation is permitted or not. We advise that you do not continue with authorisation in this case.

    The following is an example authentication result request, where you submit the cRes and transactionId to the Opayo 3D Secure callback API. The transactionId value is passed in the 3D Secure callback API URL:

     { "cRes": "eJylV1tzqkgQfvdXpNxHKuEioKSIW8NFhAgCIipvBAcEERAQ0F+/aEzMyZ7d2rhUUdJtX76vp3sG2D+bXfxQwbwI0+Sli...19CfwGvWEqk" }
    
    Example Authentication response

    In this example authentication result response, the cardholder has successfully authenticated and authorisation is successful:

    {
      "statusCode":"0000",
      "statusDetail":"The Authorisation was Successful.",
      "transactionId":"BEB718F6-3ED2-323E-2CB2-B8C83DB2029C",
      "acsTransId":"43b04fd1-692c-4b76-ac20-a75527ad0a25",
      "dsTranId":"7980e36f-907b-4530-84fd-ccc1f40bf9ae",
      "retrievalReference":15278,
      "bankResponseCode":"00",
      "bankAuthorisationCode":"999777",
      "paymentMethod":{
        "card":{
          "cardType":"Visa",
          "lastFourDigits":"7067",
          "expiryDate":"0320",
          "cardIdentifier":"73B7FA7B-D51E-49F6-9638-C58D5A1C146B",
          "reusable":false
        }
      },
      "amount":{
        "totalAmount":41000,
        "saleAmount":41000,
        "surchargeAmount":0
      },
      "currency":"GBP",
      "fiRecipient":{  
      },
      "status":"Ok",
      "avsCvcCheck":{
        "status":"NotChecked",
        "address":"NotProvided",
        "postalCode":"NotProvided",
        "securityCode":"NotProvided"
      },
      "3DSecure":{
        "status":"Authenticated"
      }
    }
    

    Handling a fallback outcome

    When the cardholder completes 3D Secure authentication, the 3D Secure provider will render a form which submits itself to your termUrl and returns the customer to you. This HTTP POST contains the encrypted results of the authentication in a hidden form field called PaRes. This is a Base64 encoded, encrypted message sent back by the issuing bank to your TermURL at the end of the 3D Secure authentication process

    If you specified an MD in the request then the response will also include the MD. This will be exactly the same value you specified in your request.

    The result of the 3D Secure authentication will be returned to you from the issuing bank in a field called PaRes, which must be forwarded to Opayo in a field called paRes, in camelCase.

    You must POST the paRes to our 3D Secure resource for us to decrypt it and to complete the transaction. For example:

    curl https://pi-test.opayo.cloud/api/v1/transactions/<transactionId>/3d-secure \ -H "Authorization: Basic
    ZHE5dzZXa2tkRDJ5OGszdDRv...o3UkczVjh6T2RIQ1NQS3dKMDJ3QVY="
     \ -H "Content-type: application/json" \ -X POST \ -d
     '{
      "paRes":"eJylV1tzqkgQfv...r19CfwGvWEqk"
    }'

    We will return the 3D Secure object that will provide you with the result of the 3D secure authentication via the status field. If the cardholder was able to successfully authenticate, the status will be Authenticated as follows:

    {
      "status":"Authenticated"
    }

    Step 4: Getting the transaction outcome

    This step is only necessary for a fallback outcome. For the challenge response outcome, the result of the authorisation and authentication is returned in Step 3.

    Once we have received the paRes we will validate the response against the 3D Secure rules for your account and if allowed we will send all the transaction data (including the 3D Secure authentication result) to your acquiring bank and request authorisation. The acquiring bank will either accept or reject the transaction and that will complete the transaction process.

    You can now make a simple GET request to retrieve the transaction and find out whether the transaction was authorised by the bank.

     curl https://pi-test.opayo.cloud/api/v1/transactions/<transactionId>
     \ -H "Authorization: Basic aEpZeHN3N0hMYmo0MGNCOHVkRVM4Q0RSRkx....jEyejRqNVVzNXU=" 
     \ -H "Content-type: application/json" \ -X GET

    If the authorisation was successful the status for the transaction will be Ok. The statusDetail will provide you with additional information regarding the status of the transaction.

    Example response

    {
      "statusCode":"0000",
      "statusDetail":"The Authorisation was Successful.",
      "transactionId":"DB79BA2D-05DA-5B85-D188-1293D16BBAC7",
      "transactionType":"Payment",
      "retrievalReference":9493946,
      "bankResponseCode":"00",
      "bankAuthorisationCode":"999777",
      "status":"Ok",
      "amount":{
        "totalAmount":10000,
        "saleAmount":10000,
        "surchargeAmount":0
      },
      "currency":"GBP",
      "paymentMethod":{
        "card":{
          "cardType":"Visa",
          "lastFourDigits":"0006",
          "expiryDate":"0317"
        }
      },
      "3DSecure":{
        "status":"Authenticated"
      }
    }

    Related Pages