Node.js / TypeScript SDK

The official RDCPASS SDK for Node.js / TypeScript, published on npm as @rdcpass/node. It signs every request, encrypts and decrypts payloads with AES-256-GCM, presents your mTLS client certificate, adds idempotency keys, retries transient failures and verifies webhooks — the complete security stack described in Authentication, handled for you.

npmNode.js 18+Source code ↗Changelog ↗

Installation

Add @rdcpass/node to your project:

npm install @rdcpass/node

Requirements

Node.js 18+ or later.
Outbound HTTPS (TLS 1.2 or later) to gateway.staging.rdcpass.cd for the staging environment and api.rdcpass.cd for production. In production, calls must come from an IP address on your application’s allowlist.
An RDCPASS application with API credentials, created in the console — see Sandbox.

Configuration

Create one client and reuse it across your application: it is safe for concurrent use and keeps connections open between calls. The environment selects the base URL; keys and certificates issued for one environment are rejected by the other.

Environment	RDCPASS_ENVIRONMENT	Base URL
Staging environment	`sandbox`	`https://gateway.staging.rdcpass.cd`
Production	`production`	`https://api.rdcpass.cd`

Configure a client for the staging environment explicitly:

rdcpass.ts
import { RdcPass } from '@rdcpass/node'

// Staging environment: https://gateway.staging.rdcpass.cd
export const rdcpass = new RdcPass({
  environment: 'sandbox',
  keyId: 'key_test_3c7e1a9f42',
  keySecret: process.env.RDCPASS_KEY_SECRET!,
  encryptionKey: process.env.RDCPASS_ENCRYPTION_KEY!,
})

Credentials

Credential	Environment variable	Description
Key ID	`RDCPASS_KEY_ID`	Public identifier of your HMAC key, sent with every request (`key_test_…` in staging, `key_live_…` in production).
Key secret	`RDCPASS_KEY_SECRET`	HMAC-SHA256 signing secret. Never sent over the network.
Payload Encryption Key	`RDCPASS_ENCRYPTION_KEY`	AES-256-GCM key used to encrypt requests and decrypt responses, and to verify webhook signatures.
Environment	`RDCPASS_ENVIRONMENT`	`sandbox` or `production`. Defaults to `sandbox`.
mTLS client certificate and key	—	Issued by RDCPASS for your application; required in production. Must belong to the same application as the key ID. Loaded from files in the client configuration.

Production and environment variables

When no credentials are passed, the client reads the four environment variables above. In production, add your mTLS client certificate and private key:

rdcpass.ts
import { readFileSync } from 'node:fs'
import { RdcPass } from '@rdcpass/node'

// With no credentials passed, the client reads RDCPASS_KEY_ID,
// RDCPASS_KEY_SECRET, RDCPASS_ENCRYPTION_KEY and RDCPASS_ENVIRONMENT.
// Production (https://api.rdcpass.cd) also requires your mTLS client certificate.
export const rdcpass = new RdcPass({
  clientCert: readFileSync('/etc/rdcpass/client.crt'),
  clientKey: readFileSync('/etc/rdcpass/client.key'),
})

Keep secrets out of source code

Load the key secret, the Payload Encryption Key and the certificate’s private key from environment variables or a secrets manager. Never commit them, and never ship them in a mobile or browser application — the SDK is for server-side use.

Your first request

Validate a customer by RDCPASS ID with KYC Validation. The SDK encrypts and signs the request, decrypts the response and returns a typed kyc_validation object:

validate-identity.ts
import { RdcPass } from '@rdcpass/node'

const rdcpass = new RdcPass()

const validation = await rdcpass.kyc.validations.create({
  reference: 'cust-0001',
  identifier: { type: 'rdcpass_id', value: 'COD-2103-0214-4937' },
  match: { full_name: 'Kabeya Mwamba Tshisekedi', date_of_birth: '1988-04-12' },
  purpose: 'customer_onboarding',
  scopes: ['kyc.documents.primary', 'kyc.phone_numbers'],
})

console.log(validation.result) // 'verified'
console.log(validation.kyc.basic.full_name) // 'Kabeya Mwamba Tshisekedi'
console.log(validation.scopes_withheld) // []

Decrypted response
{
  "id": "kyc_8d2f6a1c93",
  "object": "kyc_validation",
  "livemode": true,
  "reference": "cust-0001",
  "status": "completed",
  "result": "verified",
  "certified_account": true,
  "identifier": {
    "type": "rdcpass_id",
    "value": "COD-2103-0214-4937"
  },
  "match": {
    "full_name": "match",
    "date_of_birth": "match",
    "age": "not_provided",
    "score": 0.98
  },
  "account": {
    "rdcpass_id": "COD-2103-0214-4937",
    "status": "active",
    "certified": true,
    "created_at": "2025-03-14T09:22:41Z",
    "level_of_assurance": "LOA3"
  },
  "kyc": {
    "basic": {
      "full_name": "Kabeya Mwamba Tshisekedi",
      "first_name": "Kabeya",
      "last_name": "Tshisekedi",
      "date_of_birth": "1988-04-12",
      "age": 38,
      "gender": "male",
      "nationality": "COD"
    },
    "documents": {
      "primary": {
        "type": "passport",
        "number": "OB1234567",
        "issued_at": "2022-06-01",
        "expires_at": "2027-05-31",
        "issuing_authority": "Direction Générale de Migration",
        "status": "valid",
        "image": {
          "content_type": "image/jpeg",
          "url": "https://files.rdcpass.cd/d/9f2c41e8b7a3?sig=Qm9fX2t5Y19zaWc&exp=1790418002",
          "expires_at": "2026-09-26T10:20:02Z"
        }
      }
    },
    "phone_numbers": [
      {
        "number": "+243812345678",
        "operator": "Vodacom",
        "is_primary": true,
        "verified": true
      },
      {
        "number": "+243991234567",
        "operator": "Airtel",
        "is_primary": false,
        "verified": true
      }
    ]
  },
  "scopes_applied": [
    "kyc.basic",
    "kyc.documents.primary",
    "kyc.phone_numbers"
  ],
  "scopes_withheld": [],
  "purpose": "customer_onboarding",
  "created_at": "2026-09-26T10:15:02Z"
}

Every field is documented in KYC Validation.

Calling every service

Every service is exposed as a resource on the client, named after its endpoint. Parameters and responses use the same names and shapes as the API reference.

KYC Validation

Look up an identity by RDCPASS ID, passport, CENI voter card, driving licence or national ID. The result is verified, not_found or not_certified. Reference →

const validation = await rdcpass.kyc.validations.create({
  identifier: { type: 'passport', value: 'OB1234567' },
  purpose: 'customer_onboarding',
  scopes: [], // basic KYC only
})
console.log(validation.result) // 'verified' | 'not_found' | 'not_certified'

Face Recognition

Compare a photo — sent as base64 data or a url — with the enrolled face of an identity. reason is required; the result is match or no_match. Reference →

import { readFileSync } from 'node:fs'

const recognition = await rdcpass.face.recognitions.create({
  image: { data: readFileSync('selfie.jpg').toString('base64') },
  identifier: { type: 'rdcpass_id', value: 'COD-2103-0214-4937' },
  reason: 'Current account opening at Gombe branch, Kinshasa',
  purpose: 'customer_onboarding',
})
console.log(recognition.result) // 'match' | 'no_match'

Age Verification

Check whether a person is over a threshold without receiving their date of birth; read over_threshold. Reference →

const verification = await rdcpass.age.verifications.create({
  identifier: { type: 'rdcpass_id', value: 'COD-2103-0214-4937' },
  threshold: 18,
  purpose: 'age_gating',
})
console.log(verification.over_threshold) // true

KYB Verification

Verify a business by rccm, id_nat or nif, and receive its officers and beneficial owners if your application is granted those scopes. Reference →

const business = await rdcpass.kyb.verifications.create({
  identifier: { type: 'rccm', value: 'CD/KIN/RCCM/23-B-01234' },
  match: { business_name: 'Congo Digital Solutions SARL' },
  purpose: 'customer_onboarding',
  scopes: ['kyb.officers', 'kyb.beneficial_owners'],
})
console.log(business.result)

AML/CTF Screening

Screen a subject against the requested checks; enable monitoring to be notified of new hits. Read risk_level. Reference →

const screening = await rdcpass.aml.screenings.create({
  subject: { identifier: { type: 'rdcpass_id', value: 'COD-1907-5521-0386' } },
  checks: ['sanctions', 'pep', 'adverse_media', 'watchlists', 'high_risk_jurisdictions'],
  monitoring: true,
  purpose: 'regulatory_compliance',
})
console.log(screening.risk_level) // 'low' | 'medium' | 'high'

Credit Scoring

Requires the customer’s consent in the RDCPASS app (consent.method: rdcpass_app). Returns a score and a band. Reference →

const credit = await rdcpass.credit.scores.create({
  identifier: { type: 'rdcpass_id', value: 'COD-2103-0214-4937' },
  consent: { method: 'rdcpass_app', consent_id: 'cns_5e8a2d71c4' },
  purpose: 'credit_assessment',
})
console.log(credit.score, credit.band)

Fraud Reporting

Report a confirmed or suspected fraud, such as identity_usurpation, against a subject, with a description. Reference →

const report = await rdcpass.fraud.reports.create({
  type: 'identity_usurpation',
  subject: { identifier: { type: 'rdcpass_id', value: 'COD-2103-0214-4937' } },
  description: 'Account opened with a stolen passport at an agent in Lubumbashi.',
})
console.log(report.id, report.status)

Login with RDCPASS

The login helper builds the /v1/oidc/authorize URL with state and a PKCE code_challenge (S256), exchanges the authorization code at /v1/oidc/token with the matching code_verifier, and calls /v1/oidc/userinfo. See Login with RDCPASS.

login.ts
// 1. Build the authorize URL. The SDK generates state and the PKCE
//    code_verifier / code_challenge (S256) for you.
const { url, state, codeVerifier } = rdcpass.login.createAuthorizationUrl({
  clientId: 'app_8f2a1c0e9b',
  redirectUri: 'https://yourapp.example.com/callback',
  scopes: ['openid', 'profile', 'rdcpass:kyc.phone_numbers'],
})
// Store state and codeVerifier in the user's session, then redirect to url.

// 2. On your callback, check state and exchange the code.
export async function handleCallback(code: string, returnedState: string, session: { state: string; codeVerifier: string }) {
  if (returnedState !== session.state) throw new Error('state mismatch')
  const tokens = await rdcpass.login.exchangeCode({
    clientId: 'app_8f2a1c0e9b',
    code,
    codeVerifier: session.codeVerifier,
    redirectUri: 'https://yourapp.example.com/callback',
  })
  return rdcpass.login.userInfo(tokens.access_token)
}

Batches & async

Every service accepts batches at /batches: up to 50 items synchronously, or up to 10,000 asynchronously. With the async option the SDK sends Prefer: respond-async and returns a 202 job or batch object immediately.

Wait — the wait helper polls /v1/batches/{id} (or /v1/jobs/{id} for a single async call) with backoff until the status is final, or until your timeout elapses.
Iterate — the results helper pages through /v1/batches/{id}/results and follows next_cursor for you.
Or subscribe — instead of polling, handle the batch.completed and batch.completed_with_errors webhooks.

refresh-kyc.ts
// Submit up to 10,000 items asynchronously (Prefer: respond-async).
const batch = await rdcpass.kyc.validations.batches.create(
  {
    purpose: 'customer_onboarding',
    items: [
      { reference: 'cust-0001', identifier: { type: 'rdcpass_id', value: 'COD-2103-0214-4937' } },
      { reference: 'cust-0002', identifier: { type: 'ceni', value: '1234567890123' } },
    ],
  },
  { async: true },
)

// Poll GET /v1/batches/{id} until the batch reaches a final status.
const done = await rdcpass.batches.wait(batch.id, { pollInterval: 5_000, timeout: 30 * 60_000 })
console.log(done.status, done.succeeded_items, done.failed_items)

// Iterate every result; the SDK follows next_cursor page by page.
for await (const item of rdcpass.batches.results(batch.id, { limit: 500 })) {
  if (item.status === 'succeeded') console.log(item.reference, item.result.result)
  else console.log(item.reference, item.error.error)
}

Batch quota is separate from single-call quota, and batch items are billed at the discounted batch rate — see Rate limits and Billing.

Webhooks

The webhook helper checks X-RDCPASS-Webhook-Signature — HMAC-SHA256 of {timestamp}.{rawBody} with your Payload Encryption Key — using a constant-time comparison, rejects deliveries whose X-RDCPASS-Webhook-Timestamp is more than 5 minutes from your clock (configurable), and parses the envelope { id, object: "event", type, livemode, created_at, data: { object, previous_attributes } } into a typed event.

webhooks.ts
import express from 'express'
import { rdcpass } from './rdcpass'

const app = express()

// Keep the raw body: the signature covers `${timestamp}.${rawBody}`.
app.post('/webhooks/rdcpass', express.raw({ type: 'application/json' }), (req, res) => {
  let event
  try {
    event = rdcpass.webhooks.constructEvent(req.body, req.headers)
  } catch {
    return res.status(400).send('Invalid signature')
  }

  switch (event.type) {
    case 'kyc_validation.completed':
      console.log(event.data.object.result)
      break
    case 'batch.completed':
    case 'batch.completed_with_errors':
      console.log(event.data.object.id, event.data.object.failed_items)
      break
  }
  res.sendStatus(200)
})

Pass the raw request body, exactly as received — a body parsed and re-serialized by your framework will not match the signature. Respond with a 2xx within 5 seconds and deduplicate on the event id, which is also sent as X-RDCPASS-Webhook-Id. See Webhooks.

Errors

Every API error — { error, message } in the response body — is raised as RdcPassError, which carries code, status, message, requestId. Network failures and timeouts that exhaust their retries raise a separate connection error. Quote the request ID when you contact RDCPASS support.

Code	HTTP	What to do
`invalid_identifier`	400	The identifier is malformed for its type. Fix the input; do not retry.
`insufficient_balance`	402	Your prepaid balance is too low. Top up in the console.
`scope_not_granted`	403	A requested scope is not granted to your application. Remove it or request it in the console.
`purpose_not_approved`	403	The purpose is not approved for your application.
`rate_limited`	429	Too many requests per second. Retried automatically after `Retry-After`.
`batch_quota_exceeded`	429	Your batch quota is used up. Separate from single-call quota.

import { RdcPassError } from '@rdcpass/node'

try {
  await rdcpass.kyc.validations.create({
    identifier: { type: 'rdcpass_id', value: 'COD-2103-0214-4937' },
    purpose: 'customer_onboarding',
    scopes: ['kyc.biometrics.iris'],
  })
} catch (err) {
  if (err instanceof RdcPassError) {
    console.error(err.status, err.code, err.message, err.requestId)
    if (err.code === 'scope_not_granted') {
      // 403: request the scope for your application in the console
    }
  } else {
    throw err
  }
}

The full list is in Errors.

Retries & idempotency

Automatic idempotency keys. Every POST is sent with a generated Idempotency-Key, reused on each retry of that request, so a retried call is never processed or billed twice.
What is retried. 429 responses, 5xx responses, connection failures and timeouts. Other 4xx errors are raised immediately.
Backoff. Exponential backoff with jitter, starting at 0.5 seconds and capped at 8 seconds; Retry-After is honoured when present. Up to 3 retries by default.
Configurable. Change the number of retries per client or per request, and pass your own idempotency key to keep retries safe across process restarts.

const rdcpass = new RdcPass({
  maxRetries: 5, // default 3; set 0 to disable
})

// Every POST gets an Idempotency-Key automatically. Pass your own to make
// retries safe across process restarts:
await rdcpass.fraud.reports.create(
  {
    type: 'identity_usurpation',
    subject: { identifier: { type: 'rdcpass_id', value: 'COD-2103-0214-4937' } },
    description: 'Account opened with a stolen passport.',
  },
  { idempotencyKey: 'fraud-case-INC-2026-88213', maxRetries: 1 },
)

Timeouts & logging

Each attempt times out after 30 seconds by default; set a different timeout per client or per request. Logs are written through your language’s standard logging interface. They include method, path, status, duration, retry attempts and request ID — never decrypted payloads, secrets or personal data.

const rdcpass = new RdcPass({
  timeout: 20_000, // per attempt, in milliseconds (default 30_000)
  logLevel: 'debug', // 'error' | 'warn' | 'info' | 'debug'
  logger: console, // any object with debug/info/warn/error methods
})

// Override per request.
await rdcpass.aml.screenings.create(
  { subject: { identifier: { type: 'rdcpass_id', value: 'COD-1907-5521-0386' } }, purpose: 'regulatory_compliance' },
  { timeout: 60_000 },
)

Upgrading & versioning

@rdcpass/node follows semantic versioning: only major versions contain breaking changes.
Each major version receives security and bug fixes for 24 months after the next major version is released.
Every release, with upgrade notes for each major version, is listed in the Changelog.
New API fields and events arrive in minor releases, so keep the SDK up to date to use them.

Integrating without an SDK? See Authentication to sign, encrypt and send requests yourself.