3D Secure React Library

A modern React library that simplifies the integration of 3D Secure (3DS) authentication for secure payment processing in web applications.

Overview

This library 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
# or
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 { isExecuting, status, result, execute, cancel } = useThreeDSecure({
    baseUrl: 'https://api.sqala.tech/core/v1/threedsecure',
    publicKey: 'your-public-key',
    container: containerRef
  });

  const handleAuthentication = async () => {
    await execute({
      id: 'authentication-id' // Unique identifier for the authentication
      ip: 'user-ip' // Optional user's IP address
    });
  };

  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>
  );
}

When calling execute on a useEffect, pass an AbortController and call abort on the cleanup function:

useEffect(() => {
  const abortController = new AbortController()

  execute({
    id: "authentication-id",
    ip: "user-ip",
    abortController,
  })

  return () => abortController.abort()
})

Development Setup

Prerequisites

Node.js 18+ and npm/yarn
Modern browser with DevTools for debugging

Setting Up the Development Environment

Clone the repository:

git clone https://github.com/rpo-pay/threedsecure-react.git
cd threedsecure-react

Install dependencies:
```
npm install
# or
yarn
```
Start the development server:
```
npm run start:dev
# or
yarn start:dev
```

This will concurrently:

Build the library TypeScript files
Watch for changes in the lib folder
Start Vite's development server

Project Structure

threedsecure-react/
├── lib/                  # Library source code
│   ├── hooks/            # React hooks
│   ├── models/           # Data models
│   ├── types/            # TypeScript type definitions
│   └── main.ts           # Main entry point
├── src/                  # Demo application
├── dist/                 # Build output
├── .vscode/              # VS Code configuration
├── tsconfig.lib.json     # TypeScript config for the library
└── vite.config.ts        # Vite configuration

Debugging

The project is configured with source maps for easy debugging. When using VS Code:

Open the project in VS Code
Set breakpoints in your code
Press F5 to start debugging (this launches Edge with the development server)
The debug session will automatically terminate the development server when stopped

Running Tests

npm run test
# or
yarn test

Building for Production

npm run build
# or
yarn build

This generates the library output in the dist directory.

Contributing

We welcome contributions from the community! Here are some ways you can contribute:

Reporting Issues

Use the issue tracker to report bugs
Include detailed steps to reproduce the issue
Mention your environment (browser, OS, library version)

Feature Requests

Open an issue describing the feature
Explain the use case and benefits
Discuss implementation approaches

Pull Requests

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow the existing code style and patterns
Write unit tests for new features
Update documentation for any API changes
Keep commits focused and atomic
Use semantic commit messages

License

MIT

Acknowledgements

This library is developed and maintained by Sqala
Special thanks to all the contributors who have helped improve this project

Package detail

@sqala/threedsecure-react

readme