Skip to main content

​
Overview

Chainrails KYC is a reusable identity layer for headless financial flows. Instead of asking a user to repeat verification with every provider, Chainrails maintains one profile and evaluates it against the requirements of the provider and transaction being used. The engine follows a progressive model: clients collect only the requirements currently missing for a transaction. Information already provided or verified is reused where the next provider accepts it.
Chainrails KYC applies to headless providers. For widget providers, create the ramp order and redirect the user to widgetUrl; that provider owns its KYC flow.

​
How the flow works

  1. Ask for the provider requirements with GET /api/v1/kyc/requirements.
  2. Read the user’s current eligibility with GET /api/v1/kyc/state.
  3. Collect only missing, insufficient, or rejected fields.
  4. Submit them with POST /api/v1/kyc/submit.
  5. If an external verification URL is returned, redirect the user and poll state after they return.
  6. Continue when canProceed is true, or direct the user to support when blocked is true.
Submitting KYC creates the profile automatically when one does not exist. Only email is required initially, and the profile is reused through the normalized email address. Your application remains responsible for authenticating the user and verifying ownership of that email.

​
Progressive requirements

Every required field has an assurance level: State responses group requirements by what the client should do next:

​
Verification methods

Chainrails currently supports:
  • Text verification: registry validation of country-specific identifiers. Nigeria currently supports BVN and NIN.
  • External verification: a hosted identity-document and biometric flow covering document verification, liveness, face match, phone verification, and device/IP analysis.
  • Manual review: used when verified identity evidence conflicts or a provider result is inconclusive.
countryCode identifies the transaction corridor. fields.country identifies the user’s current country of residence. They are separate concepts and do not need to match.

​
Standalone KYC endpoints

Use the dedicated endpoints when KYC is managed independently of a ramp transaction or will be reused across multiple Chainrails products:
For a ramp-only integration, use the equivalent /api/v1/ramp/kyc entry points documented in the Complete Ramping Guide. They apply ramp-specific amount handling and access checks while calling the same KYC engine.

​
Security and privacy

  • Send KYC requests only from your authenticated backend.
  • Never expose your Chainrails API key in a frontend application.
  • Do not log identity numbers, document data, verification payloads, or decrypted profile fields.
  • Do not assume that returning from an external verification URL means approval; always query KYC state.
  • Do not repeatedly resubmit blocked data. Manual review is required when blocked is true.