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 MyOpayo, read our Using 3D Secure guide and watch our video, MyOpayo – 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 3D 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 MyOpayo settings for that transaction by using the apply3DSecure field, otherwise the MyOpayo settings will be used.

    If we receive a transaction POST which requires 3D Secure authentication, we will check if the card and the card issuer are enrolled in the 3D 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 3D 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 3D Secure and you will receive the normal transaction response. You will be able to see the outcome of the 3D 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 2 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",
  "dsTransId":"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",
  "dsTransId":"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.

    Please 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, however this can help prevent ACS redirection issues with specific ACS providers, this can only be used during a 3DSv2 authentication flow.

    The threeDSSessionData must be BASE64 URL encoded with no padding, 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>

     

    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

     

    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 cRes for a transaction has to be provided within 10 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",
  "dsTransId":"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"
  }
}

     

    Related Pages