Integrate 3D Secure 2.0 (Direct or CSE)
- Introduction to 3D Secure
- 3D Secure 2 Implementation Flow
- Integration Overview
- 3DS 2.0 Integration Steps
Introduction to 3D Secure
3D secure is an additional layer of verification for Card not present (CNP) transactions.
There are 2 versions available for 3D secure:
3D Secure 1.0: In 3D secure 1.0, customers are redirected to the issuer's website to provide additional authentication data such as password or SMS verification code.
3D Secure 2.0: In 3D secure 2.0, customers are not redirected to issuer’s website but performs authentication within a merchant’s website or mobile app using passive, biometric, and two-factor authentication approaches.3-D Secure 2.0 is compliant with EU "strong customer authentication (SCA)" mandates.
Combined with confusing web redirect experiences which made 3DS 1.0 fail customers and businesses. Not only did 3DS 1.0 lack native in-app and web flows, but it also introduced confusing and difficult-to-remember authentication prompts.This resulted in legitimate customers dropping out of the payment flow.
3D Secure 2.0 addresses many of 1.0’s issues, while bringing benefits across a wider set of use cases for businesses all over the world. By supporting additional data during transactions, risk-based decisions will be possible on whether to authenticate or not.
3D Secure 2 Implementation Flow
3DS 2.0 transactions can go through either a frictionless flow or challenge flow based on the requirements of the issuers.
Frictionless flow allows a transaction to be processed without additional intervention from the card holder for the authentication process by exchanging all necessary information in the background using the shopper’s device fingerprint.
Challenge flow requires a customer’s intervention for the authentication process based on secure customer authentication factors.
CSE - Client Side Encryption
Client Side Encryption (CSE) is a card payment integration method that gives merchants full flexibility with how the present card collection fields to their customers whilst allowing merchants to minimise their exposure when it comes to PCI Compliance.
CSE integration merchants to be PCI DSS compliant to a level of Self Assessment Questionnaire A-EP or above, in accordance with the latest PCI DSS standards (v3.2.1).
Your particular level of compliance may differ depending on your own unique setup, so we recommend consulting a QSA to make sure you're set up in the right way to meet your desired PCI DSS level.
APEXX supports integration for 3DS 2.0 via Cardinal Cruise Hybrid Integration method.
Cardinal Cruise Account Credentials
As part of registering for Cardinal Cruise, we receive 3 values that are used to authenticate yourself with Cardinal. JWT creation requires that these values have been generated and handed off to the Cardinal. We will provide you with these details during the onboarding process based on your preference.
API Identifier - A non-secure value that should be passed within the JWT under the iss claim.
Org Unit Id - a non-secure value that should be passed within the JWT under the OrgUnitId claim.
API Key - A secure value that should only ever be known between you and Cardinal. This value should never be rendered or displayed anywhere your users could find it. The API Key should only be used to sign the JWT and to verify a JWT signature from Cardinal. It should never be included within the JWT itself.
Apexx Account Credentials
Apexx account credentials like account_id and X-APIKEY provided to you by the implementation manager. Please ask your implementation manager to enable your accounts for processing 3d secure 2.0.
Client Side Encryption JS and keys
How It Works
Cardinal Cruise uses Songbird.js to perform most of the heavy lifting on behalf of our customers. It will handle all device data collection and communication with our Cardinal Centinel platform, as well as the user experience to the consumer for both CCA and Alternative Payment brands.
The diagram below shows the high-level event execution order of a transaction from the merchant's perspective. The enumerated events do not map to the integration steps found within this document. The enumerated events are simply to help illustrate the order events occur during a transaction.
JWT(JSON Web Token) Creation
Include the Script
Listen for Events
Include BIN Detection
Point 7 to 10 is applicable for CSE integration only
Set the public key (Encryption Key)
Implement the form
Lookup Request (Enrollment)
Handling the Lookup Response (Enrollment Response)
Continue with CCA(Cardinal's Consumer Authentication)
Handling the CCA Response
3DS 2.0 Integration Steps
1. Create JWT(JSON Web Token)
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
Cardinal Cruise utilizes a JWT to handle authentication and to assist in passing secure data between you and Cardinal.
The JWT is a JWS with the signature using a SHA-256 HMAC hash algorithm.
Creating a JWT client-side is not a valid activation option. Each order should have a uniquely generated JWT associated with it.
You can create JWT with your preferable server side programming language like php,java,.net. Etc
Security Warning : For security reasons, all JWT creation must be done on the server side. When creating the JWT, use your company API Key as the JWT secret.
Mandatory Fields: Below fields are mandatory for creating JWT.
Optional Fields: Below fields are optional for creating JWT.
JWT creation example: Link: JWT_Creation
The below code samples are to provide you with a basic idea on how to generate JWT.
Example payload :
Please find the field details for the Payload object from the below link:
You can find JWT libraries as per your requirement from here https://jwt.io/#libraries-io.
Note: A JWT is composed of 3 sections of URL base64 encoded strings of data separated by a period. The first 2 sections are JSON objects while the last section is a digital signature that has been URL base64 encoded.
Header : A small JSON object that specifies what type of algorithm was used to generate the digital signature. This section is denoted in the above example in red.
Payload : A JSON object that contains the data being sent from one party to another. This is where all request data the merchant sends to Cardinal lives and vise Versa. This section is denoted in the above example in green.
Signature : A URL base64 encoded the hash value of the header and payload. This is used to verify the contents of the JWT have not been tampered with. Signatures are generated using a shared secret value so only the creator and consumer have the ability to create the signature. As long as the shared secret stays a secret between the 2 parties no one should be able to spoof the signature. Signatures are verified by the consumer recreating the hash value and checking that it matches the one attached to the JWT. This section is denoted above in blue.
Decrypt JWT: You can use this link https://jwt.io/.
Conclusion: So based on the above information you can create JWT from payload data.
2. Include the Script in Hosted payment page
In this step, You need to import songbird.js in your Hosted payment page.
Add Songbird.js to your site just like any other client-side script - through a script tag.
Test environment :
Production environment :
3. Configure It
Using the Cardinal.configure() function allows you to pass a configuration object into Songbird.
There are different configuration options that can be used to initialize Songbird through Cardinal.configure function. You can call this function once per page load. you can configure your root level configuration like logging, button, payment, etc.
4. Listen for Events
In this step, You have to trigger below two events.
This function sets up an event subscription with Songbird to trigger a callback function when the event is triggered by Songbird.
You can subscribe to an event using the Cardinal.on() function structured like:
This optional event triggers when Songbird has successfully initialized, after calling the Cardinal.setup() function.
This event will not trigger if an error occurred during your Cardinal.setup() call (this includes a failed JWT authentication) and this event will only trigger once per page load. If your callback gets executed, you know that Songbird is available to run transactions.
This function will receive 2 arguments that describe the loaded state of Songbird and the current session identifier.
You will get sessionId from this event. It will be used in further steps.
This event is triggered when the transaction has been finished from the Cardinal end. This is how Songbird hands back control to your webpage.
This event is triggered with the alternative payment brand results that require a payment authorization. The ActionCode (SUCCESS, NOACTION, FAILURE, ERROR) field should be used to determine the overall state of the transaction.
Additional information can be found in the fields ErrorNumber and ErrorDescription if the ActionCode indicates an issue was encountered.
5. Initialize It
In this step, You need to pass a jwt token(that you have created in the 1st step).
Cardinal.setup() will initiate the communication process with Cardinal.
You should only call this function once per page load.
JWT hidden field in the HTML :
Cardinal Setup :
Note: Cardinal.setup does not catch errors. Use the payments.validated event mentioned in Step 4 instead.
6. Include BIN Detection
In this step, You need to trigger a bin.process event with a card number.
The merchant will need to provide a minimum of the first 6 (e.g. BIN) up to the full card number of the consumer (e.g. max of 19 digits).
This event will wait for a static amount of time before resolving to allow for device data collection to complete. The implementor should wait for this event to complete before moving forward with a transaction.
This event will need to occur before the Lookup Request (Enrollment).
You can check the bin details whether it is correct or not and a way to specifically run the EMV 3DS Method URL.
If no Method URL was provided, Cardinal will not perform additional device data collection at this time.
The bin.process event will return a promise that will be fulfilled when the EMV 3DS Method URL 'attempt' has been completed. The promised result will include a single object containing the result of the 3DS Method URL attempt.
You can verify the result.Status by using console.log("verify message"). It’s optional.
Below Steps from 7 to 10 are required for Client-Side Encryption Implementation only
7. Encryption key
The encryption key must be supplied to the Client-Side Encryption library and is used to encrypt the sensitive card details.
The decryption key exists within a secure environment at APEXX.
Contact Apexx Implementation manager for the encryption key.
Test environment :
Production environment :
9. Set the Public Key (Encryption Key)
10. Implement the form
For the form to work, use the “data-apexx” attribute for each item of cardholder data.
In this example the Apexx CSE library will set the encrypted data in data-apexx="encrypted_data" element.
How it all fits together
Include the apexx payment form html in the card details collection elements of your payment page.
Below steps will be the flow to process a CSE payment with APEXX:
Include APEXX.js(apexx-cse-1.0.js) into your page.
Implement the HTML form as mentioned above.
On pressing of Submit/Pay button, our JS(apexx-cse-1.0.js) will take the data i.e card_number, exp_month, exp_year, cvv, etc. and do the encryption and JS file will set the encrypted data into hidden parameter and call to form action (merchant server-side)
Call APEXX /payment/direct API with encrypted value along with other information. (Server(Merchant) to server(APEXX) API call).i.e:
CSE Fields with validation function
Conclusion: So based on the above information you can integrate with CSE.
Now you have CSE encrypted data, You need to pass it for Lookup Request(Apexx Enrollment).
11. Lookup Request (Enrollment)
In this step, You need to make a first request of the transaction that is used to process the Consumer Authentication transaction request.
You must ensure that Cardinal has the proper Acquiring Merchant Identification Number and corresponding Acquiring Bank Identification Numbers (BINs) configured in your account.
For the lookup request, you need to call our 3DSEnrol API https://sandmgw.apexxfintech.com/mgw/v2/api/doc#operation/cardPayWithThreeDSUsingPOST with some extra fields like below:
You need to pass your encrypted data in the card block for the Enrollment process.
Here reference_id will be the sessionId that we received in the “payments.setupComplete” event.
12. Handling the Lookup Response (3DSEnrol API Response)
The Lookup Response will return an acsURL, paReq, reference_id, authentication_transaction_id, three_ds_enrollment, three_ds_version and specification_version field.
The lookup response verifies that the transaction is eligible for Authentication or not by the three_ds_enrollment field.
If the three_ds_enrollment field contains a true value, then Authentication is available and you need to redirect to the ACSUrl to complete the transaction.
If the three_ds_enrollment field value is false, then you are NOT eligible for Authentication.
After calling Apexx enrollment API(3DSEnrol API), you will receive a lookup(Enrollment) response like below:
13. Continue with CCA
After the Lookup Response is returned, take the acsURL, Payload, and TransactionId and include them in the Cardinal.continue function in order to proceed with the authentication session.
The Cardinal.continue will display a modal window and automatically post the consumer's session over to the acs url for authentication.
14. Handling the CCA Response
Songbird.js will handle all the user interactions until CCA has returned back the authentication result. The next step in the integration is to add logic to your payments.validated event to handle specific return values for CCA.
You will receive two elements in the response: data, JWT
The field data.ActionCode should be used as the primary transaction status indicator.
Below are the possible values for ActionCode and what they indicate:
NOACTION - Authentication was not applicable.
SUCCESS - Authentication was completed successfully.
FAILURE - Authentication resulted in a failure.
ERROR - An error was encountered.
For more details :
JSON Response Example:
JWT Response Example:
15. JWT Validation (Optional)
Once the response JWT is received in the payments.validated event, you can verify JWT and extract the results.
Note: JWT validation should only ever be done on the server side for security reasons.
You can validate JWT by JAVA, .NET, or PHP programs in the backend.
JWT validation is optional.
For more information and code samples: https://cardinaldocs.atlassian.net/wiki/spaces/CC/pages/360593/JWT+Validation
After the successful validation of JWT / CCA response, you need to call Apexx 3DS Verify Authentication API with the three_ds authentication data.
After this call you will receive a final payment response with the SUCCESS or FAILED status.
For API request/response:
Request Example: (Not all the fields are required, its required based on gateway)
Conclusion: Based on above all steps you can integrate 3DS 2.0 with CSE.
Implementation - Sample Code