Advanced flow with the in-app SDK

Set up your server to authenticate 3D Secure 2.0 payments using the advanced flow with either the iOS or Android SDK.


To have more control over the 3D Secure 2.0 flow, use the advanced flow with the In-app SDK for iOS or Android. This allows you to:

  • Collect the specific scheme public keys ahead of the transaction that they are going to be used for.
  • Reduce the frequency of calls your backend server needs to make to Adyen. By caching the scheme public keys, you will be able to collect one and use multiple times the public keys used to encrypt the device fingerprint collected in the shopper device.

This means that you can submit the 3D Secure 2.0 authentication and authorisation requests in a single API call. In some cases, the issuer may ask for additional verification from the cardholder, requiring you to make an additional API call.

How it works

Authenticating a 3D Secure 2.0 payment with the advanced in-app flow follows these steps:

  1. Your server makes an API call, and receives a scheme public key required to encrypt the device data in the in-app SDK. You cache this key for future use.
  2. When a shopper submits a payment for this scheme, the SDK collects and encrypts the device data with the scheme key and passes the result to your application. Your application will then send it to your server.
  3. Your server submits a payment request with the device data:
    1. If approved, authentication is completed and the payment is authorised.
    2. If not approved, the in-app SDK requests additional verification from the shopper to authenticate the payment. If verified successfully the payment is authorised.

You will also need to update your cache. We recommend doing this at least every 24 hours.

To authenticate 3D Secure 2.0 payments, you'll also need to integrate an in-app SDK specific for your ecosystem (iOS or Android).

Step 1: Cache authentication keys

Submit a /get3dsAvailability request, providing a cardNumber from a BIN range you want to cache. For example, using 4111111111111111 will fetch the threeDSMethodURL for all cards in the 4111 XXXX XXXX XXXX BIN range.

Make a similar request for every card BIN range you want to cache.

Request

{
   "merchantAccount":"TestMerchant",
   "cardNumber":"4111111111111111"
}

Response

If this BIN range is enrolled in 3D Secure 1.0, the threeDS1Supported parameter will be returned as true.

If this BIN range is enrolled in 3D Secure 2.0, the response will include:

  • The threeDS2Supported parameter set to true.
  • The dsPublicKeys array containing a list of 3DS Directory Server public keys that you can use for in-app flow device fingerprint encryption. This array might contain multiple items if the BIN range is for a multi branded card.
  • The threeDS2CardRangeDetails array containing card ranges, including the 3DS protocol version supported by the card issuer. An item might contain a threeDSMethodURL if configured for the card range. Use the threeDSMethodURL to trigger device fingerprinting using the Web SDK.
{  
  "dsPublicKeys":[  
    {  
      "brand":"visa",
      "directoryServerId":"A000000003",
      "publicKey":"eyJrdHkiOiJSU0.....Eb0dyY2JbOV80NncifQ=="
    }
  ],
  "threeDS1Supported":true,
  "threeDS2Supported":true,
  "threeDS2CardRangeDetails":[  
    {  
      "brandCode":"visa",
      "endRange":"41111111",
      "startRange":"41111111",
      "threeDS2Version":"2.1.0",
      "threeDSMethodURL":"https://pal-test.adyen.com/threeds2simulator/acs/startMethod.shtml"
    }
  ]
}

If a card is registered with multiple 3D Secure 2.0 schemes, the threeDS2CardRangeDetails array might contain a threeDSMethodURL for each item.

Step 2: Fingerprint shopper device

Initialize the in-app SDK to fingerprint the shopper's device. For more information, see the iOS 3DS SDK or Android 3DS SDK pages.

Step 3: Submit 3D Secure 2.0 payment with cached keys

Submit a payment request to the /authorise endpoint. Include all the details required for card authorisation, and the sdkEncData that the SDK has generated for you.

If you only want to authenticate a 3D Secure 2.0 payment with Adyen and authorise it later, include the authenticationOnly parameter within threeDS2RequestData.

Request

{
   "amount":{
      "currency":"EUR",
      "value":1240
   },
   "merchantAccount":"TestMerchant",
   "reference":"TEST4",
   "card":{
      "cvc":"737",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "holderName":"Visa Cert",
      "number":"4111111111111111"
   },
   "threeDS2RequestData":{
      "deviceRenderOptions":{
         "sdkInterface":"native",
         "sdkUiType":[
            "text",
            "singleSelect",
            "multiSelect",
            "outOfBand",
            "otherHtml"
         ]
      },
      "sdkAppID":"0ebe63ac-7974-49ad-ad23-9393714eaa46",
      "sdkEncData":"xyzasdf",
      "sdkEphemPubKey":{
         "crv":"P-256",
         "kty":"TEST",
         "x":"aDkEQrEtpWi85iyrRhb5A7oS6HXPYiykq3ss_1XLM8Y",
         "y":"0GbYDeGCcnG7d4E2e2sEa6-WB12eUaPRKLJK2iimcNc"
      },
      "sdkReferenceNumber":"sdk_reference_number",
      "sdkTransID":"263131ba-e9a9-439d-ab45-0ed7f89089be"
   }
}

Response

You'll receive a response containing a resultCode:

  • Authorised – Indicates that the 3D Secure 2.0 authentication was frictionless, and the payment authorisation was successfully completed. 
  • ChallengeShopper – The issuer has requested additional authentication from the shopper. In this case you'll also receive a threeDS2Token, which you'll use to authenticate for this transaction.
  • AuthenticationFinished – The authentication is now finished and you can now retrieve the ECI and AV value and submit them to another acquirer (when authenticationOnly was set to true). See Step 5.
{
   "additionalData":{
      "threeds2.threeDS2ResponseData.threeDSServerTransID":"211b2ab0-7395-11e8-9d85-26e6f389607d",
      "threeds2.threeDS2Token":"- - BINARY DATA - -",
      "threeds2.threeDS2ResponseData.transStatus":"C",
      "threeds2.threeDS2ResponseData.acsChallengeMandated":"Y",
      "threeds2.threeDS2ResponseData.acsTransID":"1714867b-8737-4f01-9081-ba8a5d15d909"
   },
   "pspReference":"9925293944977557",
   "resultCode":"ChallengeShopper"
}

Step 4: Authenticate the shopper

Present a request for additional authentication to the shopper through the in-app SDK. After this authentication Adyen will receive the results of the shopper authentication with their issuer. For more information, see the iOS 3DS SDK or the Android 3DS SDK.

Step 5 (optional): Retrieve authentication details

Optionally, if you are not aiming to pursue an authorisation with Adyen, from this point you can retrieve the authentication details from Adyen. For this, submit a request to  /retrieve3ds2Result to retrieve the ECI and AV values.

Request

{
   "merchantAccount":"TestMerchant",
   "pspReference":"9935272408535455"
}

Response

{   
  "threeDS2Result":{ 
    "transStatus":"Y",
    "authenticationValue":"3q2+78r+ur7erb7vyv66vv8deha8=",
    "eci":"07",
    "threeDSServerTransID":"73aab3ce-eb39-49e8-8e9b-46fb77a472f1"
  }
}

Step 6: Complete the payment

If you receive ChallengeShopper, the in-app SDK will present a request to the shopper, in order to verify that they are the cardholder.

Once the shopper has successfully completed the additional verification, authorise the 3D Secure 2.0 payment by making an /authorise3ds2 request from your server. Send the transStatus generated by the SDK and the threeDS2Token that you received earlier.

Request

{
   "merchantAccount":"TestMerchant",
   "threeDS2Result":{
      "transStatus":"Y"
   },
   "threeDS2Token":"- - BINARY DATA - -"
}

Response

If the Challenge was successful you'll received Authorised as the resultCode.

{
   "additionalData":{
      "cvcResult":"1 Matches",
      "authCode":"46125",
      "avsResult":"4 AVS not supported for this card type",
      "avsResultRaw":"4",
      "cvcResultRaw":"M",
      "refusalReasonRaw":"AUTHORISED",
      "acquirerCode":"TestPmmAcquirer",
      "acquirerReference":"8PPSD0S76PE"
   },
   "pspReference":"9935272408535455",
   "resultCode":"Authorised",
   "authCode":"46125"
}