@kycflux/sdk

Official TypeScript SDK for the KYCFlux identity-verification API.

bun add @kycflux/sdk
# or
npm install @kycflux/sdk

Quickstart

import { KYCFlux } from '@kycflux/sdk'

const kyc = new KYCFlux({ apiKey: process.env.KYCFLUX_SECRET_KEY! })

// 1. Create a verification
const verification = await kyc.verifications.create({
  userRef: 'user_abc123',
  flow: 'PASSPORT_POA',
  metadata: { applicantName: 'Jane Smith' },
})

// 2. Redirect the applicant to the hosted flow…
console.log(verification.url)
// or open the modal in-page (browser only):
//   <script src="https://kycflux.com/v1/kycflux.js"></script>
//   KYCFlux.open({ reference: verification.reference, onComplete: ... })

// 3. Receive a webhook when the verification reaches a terminal state.
//    See "Verifying webhooks" below.

// 4. Or poll, if you must.
const updated = await kyc.verifications.retrieve(verification.id)
console.log(updated.status) // 'APPROVED' | 'REJECTED' | ...

Test mode

Use a sk_test_* key. Verifications run the full pipeline (so you can exercise face-match, OCR, AML, etc. end-to-end) but are excluded from billing and the production review queue. The returned Verification.mode is 'TEST'.

Verifying webhooks

import { Webhooks, type WebhookPayload } from '@kycflux/sdk'

app.post('/webhooks/kycflux', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = Webhooks.verify({
    header: req.headers['x-kycflux-signature'],
    body: req.body.toString('utf8'),
    secret: process.env.KYCFLUX_WEBHOOK_SECRET!,
  })
  if (!ok) return res.status(401).end()

  const event = JSON.parse(req.body.toString('utf8')) as WebhookPayload
  switch (event.event) {
    case 'verification.approved':
      // mark the user verified in your DB
      break
    case 'verification.rejected':
      // notify the applicant, optionally request a resubmit
      break
    // ...
  }
  res.status(200).end()
})

KYCFlux retries failed deliveries on a 1m / 5m / 30m / 2h / 12h schedule (5 attempts total). Every retry carries the same X-KYCFlux-Delivery-Id header so you can dedupe.

Errors

All SDK errors inherit from KYCFluxError:

import {
  KYCFluxError,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
} from '@kycflux/sdk'

try {
  await kyc.verifications.create({ ... })
} catch (err) {
  if (err instanceof ValidationError) {
    // 4xx — fix the request and retry
  } else if (err instanceof RateLimitError) {
    // back off and retry with exponential jitter
  } else if (err instanceof KYCFluxError) {
    // any other API or network failure
  }
}

License

Apache-2.0