Documentation

FIRMA Integration Guide

This guide outlines how third-party organizations can seamlessly integrate the FIRMA KYC & Document Signing Engine into their own applications using Iframes, APIs, or our React SDK.

1. Iframe Integration (Low-Code)

Embed the FIRMA flow directly into your web application

The simplest way to integrate FIRMA into an external platform is by embedding our pre-built flows directly into your web application using an HTML <iframe>. This approach requires minimal backend work. When an action is required (e.g., signing a contract), your backend generates a secure session URL via the FIRMA API and embeds it.

<!-- Example of embedding the FIRMA signing flow -->
<iframe 
  src="https://firma-ngo-frontend.vercel.app/embed/sign?session_token=YOUR_SECURE_TOKEN" 
  width="100%" 
  height="800px" 
  frameborder="0"
  allow="camera; microphone" <!-- CRITICAL: Required for Video KYC -->
></iframe>

Important

Because FIRMA requires video and camera access for biometric KYC attestations, you must include the allow="camera; microphone" attribute in your iframe tag.

Handling Callbacks

You can listen to iframe events in your frontend using the postMessage API to know when the user completes the flow.

window.addEventListener("message", (event) => {
  if (event.origin !== "https://firma-ngo-frontend.vercel.app") return;
  
  if (event.data.status === "KYC_VERIFIED") {
    console.log("User verified successfully!");
  } else if (event.data.status === "DOCUMENT_SIGNED") {
    console.log("Document signed and anchored on the blockchain.");
  }
}, false);

2. API Integration (Headless)

Full control using our REST endpoints

For full control over the user experience, you can build your own custom UI and connect directly to the FIRMA backend using our REST APIs. Ideal for enterprise platforms that require a fully white-labeled experience and want to handle the UI/UX natively.

A. Initialize a Signing Request

POST https://firma-ngo-backend.vercel.app/api/external/signatures/request
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "documentUrl": "https://your-platform.com/docs/contract.pdf",
  "signerEmail": "user@example.com",
  "requireKyc": true
}

B. Webhooks

Instead of polling for status updates, register a webhook URL. FIRMA will send a POST request to your server when a signature is approved or rejected.

// Example Webhook Payload
{
  "event": "kyc.rejected",
  "userId": "12345",
  "reason": "Blurry or unreadable ID Document",
  "timestamp": "2026-08-10T14:30:00Z"
}

3. React SDK (NPM)

Plug-and-play components for Next.js & React

FIRMA provides a JavaScript SDK (@firma-trust/react-sdk) that provides pre-built, customizable React components. Ideal for developers who want a native integration without dealing with raw API calls or iframes.

Implementation

npm install @firma-trust/react-sdk
import { FirmaProvider, DocumentSigner } from '@firma-trust/react-sdk';

function App() {
  return (
    <FirmaProvider apiKey="YOUR_PUBLIC_API_KEY" environment="production">
      <div className="my-app">
        <h1>Contract Signing</h1>
        <DocumentSigner 
            documentId="doc_987654"
            onSuccess={(hash) => console.log('Ledger Hash:', hash)}
            onError={(err) => console.error(err)}
        />
      </div>
    </FirmaProvider>
  );
}