API Reference
Start typing to search…

3DS integration

Welcome to the 3DS (3-D Secure) integration documentation. This guide will help you implement 3DS authentication in your application for secure card payments.

Overview

The 3DS API provides endpoints to manage the authentication flow for card payments, including browser information collection, DS (Directory Server) method execution, and ACS (Access Control Server) challenges.

URLs


Card-Vault seamless Flow

The card vault flow implements a secure tokenization process for payment card data, ensuring PCI DSS compliance while enabling seamless payment processing. Below is a detailed breakdown of each step and where it executes:

Flow Diagram


  1. Client to Sqala Server: The client initiates the process by sending a request to create a card vault token.
curl --request POST \
  --url 'https://api.sqala.tech/core/v1/card-vaults?publicKey=YOUR_PUBLIC_KEY_HERE' \
  --header 'content-type: application/json' \
  --data '{
  "number": "5186882549895601",
  "expYear": 33,
  "expMonth": 2,
  "holderName": "Holder Name",
  "cvv": "200",
  "threeDSecure": {
    "value": 100
  }
}'
{
  "token": "eyJpdiI6IjU4OGYzMDdlZjZiMmMwYzAzOWQ5MjM5OTAxOTVhODY0IiwiY2lwaGVydGV4dCI6ImRkNWM1MGFmMThiMGM4NWZhZTc2NmI3YmFkMTFkODM2ZjdmNTYyNDNkNmZmNDA0YjgyOTNmNGMyOTc1ZTUzMDBlZmQ1N2EwMyIsInRpbWVzdGFtcCI6MTc0NjAzNjgwMjkwNCwic2FsdCI6IjJmYmEyNTkwZjA2NDZmOGMwNzdlZDFkZDNjMTVkOWY4IiwiYXV0aFRhZyI6ImRiNGI1MTA0MzIxZDRiZDljNThlYTg2NTMxYjQ4NGIxIn0=",
  "threeDSecureId": "019687e7-41a1-77ff-a389-2f86b45d564a"
}

  1. 3DS Session Creation: The Sqala server creates a 3DS authentication session for the payment card.

  2. Return Card Token: The server returns a card token and 3DS session details to the client.

  3. 3DS Authentication Initiation: The client executes the 3DS authentication process using the Sqala plugin.

5-9. Directory Server Flow (if required):

  • The plugin renders a Directory Server iframe in the browser
  • The browser communicates with the Directory Server
  • The Directory Server processes the DS method
  • The Directory Server notifies the Sqala server of the result
  • The Sqala server forwards this response to the plugin

10-13. Challenge Flow (if required):

  • The plugin renders the challenge interface
  • The browser communicates with the Access Control Server (ACS)
  • The ACS processes the challenge and sends the result to the Sqala server
  • The Sqala server forwards the challenge response to the plugin

  1. 3DS Result: The plugin returns the 3DS authentication result to the client.

  2. Payment Request: The client initiates a payment using the authenticated card token.

  3. Payment Processing: The Sqala server processes the payment with the validated card information.

  4. Payment Result: The server returns the payment result to the client.

Key Components

  • Client: The end-user application initiating payment
  • Browser: The user's web browser where the 3DS flows are rendered
  • Sqala Server: Core backend that manages tokenization and payment processing
  • Sqala Plugin: Frontend component that handles 3DS authentication flows link
  • Directory Server: 3DS infrastructure that validates card enrollment
  • ACS (Access Control Server): Card issuer's server that authenticates the cardholder

This flow ensures secure card tokenization while maintaining PCI DSS compliance and providing strong customer authentication through the 3D Secure protocol.

3DS plugin

This plugin provides a set of React hooks and utilities to implement 3D Secure authentication flows in your payment applications. It supports the full 3DS authentication lifecycle including directory server interactions, challenges, and result handling.

Features

  • Complete 3D Secure authentication flow
  • React hooks-based API
  • Handles the entire authentication lifecycle
  • Type-safe implementation with TypeScript
  • Responsive challenge rendering
  • Cancellable authentication processes

Installation

npm install @sqala/threedsecure-react

yarn add @sqala/threedsecure-react

Quick Start

import { useRef } from 'react';
import { useThreeDSecure } from '@sqala/threedsecure-react';

function PaymentComponent() {
  const containerRef = useRef<HTMLDivElement>(null);
  
  const { status, isExecuting, isFinalized, result, execute, error: threeDSecureError } = useThreeDSecure({
    publicKey: 'YOUR_PUBLIC_KEY_HERE',
    container: container as RefObject<HTMLDivElement>,
  })

  const handleAuthentication = async () => {
    await execute({
      id: '3ds-session-id' // Unique identifier for the 3DS session
    });
  };

  return (
    <div>
      <button 
        onClick={handleAuthentication}
        disabled={isExecuting}
      >
        Process Payment
      </button>
      
      {isExecuting && <p>Processing payment authentication...</p>}
      {status && <p>Current status: {status}</p>}
      
      {/* Container for 3DS challenges */}
      <div ref={containerRef} style={{ width: '100%', height: '400px' }} />
      
      {isExecuting && (
        <button onClick={cancel}>Cancel</button>
      )}
      
      {result && (
        <div>
          <h3>Authentication Result</h3>
          <pre>{JSON.stringify(result, null, 2)}</pre>
        </div>
      )}
    </div>
  );
}

API Direct Call

If you are managing your own 3-D Secure authentication process externally and need to provide the results to our API during payment creation, you can utilize the "API Direct Call" method. This allows you to integrate the outcome of your 3DS authentication engine directly into the payment request, ensuring that the transaction benefits from the authentication layer.

This feature is intended for merchants, gateways, or other payment service providers who operate their own 3-D Secure Server (3DSS) or interact directly with the Directory Server (DS) and Access Control Server (ACS) to perform cardholder authentication. You perform the authentication flow yourself and then provide the key authentication results to our payment creation endpoint.

To use this functionality, you must provide the following information, which are outputs from your completed 3-D Secure authentication process:

  • Protocol Version (protocolVersion): This specifies the version of the 3-D Secure protocol used for the authentication. Our service supports active versions of 3-D Secure 2 (v2.1.0, v2.2.0) and previously supported 3-D Secure 1 (v1.0.2). Note that 3-D Secure 1 is being phased out. You must provide the exact version used for the authentication.
  • Directory Server Transaction ID (dsTransId): This is a unique identifier assigned to the authentication transaction by the Directory Server (DS). The DS facilitates communication between your 3-D Secure Server (3DSS) and the Card Schemes' systems. This ID serves as a crucial link for tracking the authentication across the network.
  • Authentication Value (authenticationValue): This is the cryptographic proof that the cardholder authentication process was successfully performed and completed. It is generated as a result of the authentication flow.
  • ECI: The Electronic Commerce Indicator is a value returned by the Access Control Server (ACS) indicating the outcome of the 3-D Secure authentication attempt. Standard ECI values signal whether the transaction was authenticated, attempted (liability shift may still apply), or not authenticated.
    These details must be included within the payment request payload under a dedicated node named threeDSecure.

The JSON structure for this node should be as follows:

{
  // ... other payment details
  "threeDSecure": {
    "protocolVersion": "string", // e.g., "2.2.0", "2.1.0", "1.0.2"
    "dsTransId": "string",      // Directory Server Transaction ID
    "authenticationValue": "string", // Authentication Value (AAV/CAVV)
    "eci": "string"             // Electronic Commerce Indicator
  }
  // ... other payment details
}