Which KYC endpoint to use

​

Cards: POST /api/cards/kyc

• Send the customer’s details and one identity document. You don’t create the customer first: a successful submission creates them and returns customer_id.
• Accepted id_type values: bvn, nin, passport, drivers_license, national_id, vnin, voters_card, ghana_card.
• Verification is instant for bvn and nin. Document types can sit at pending for up to 10 minutes. A card can only be created once the customer is approved.
• If the id_number or phone number already belongs to one of your customers under a different email, the call returns 400 and names the existing customer_id. Resubmit with that customer_id.
• Card KYC is enabled per account. If it isn’t on for you, the call returns 403 FEATURE_NOT_ENABLED.

​

Virtual accounts: POST /api/customers

• Create the customer with first_name, last_name, email, phone_number, date_of_birth, id_type: "bvn", and the BVN as id_number.
• Then call Create virtual account with that customer_id. The BVN is checked against the national registry at this point, not when the customer is created.
• The name and date of birth must match the BVN record exactly, or verification fails even when the BVN is valid.
• For a company, set customer_type: "business". The personal fields are those of a director or authorized representative.

​

Check status

GET /api/customers/:customerId

{
  "success": true,
  "message": "Customer retrieved successfully",
  "data": {
    "id": "01a114af-8ea6-79b7-be0b-2405531fe8ef",
    "customer_type": "individual",
    "card_program_kyc": [
      {
        "card_program": "prepaid",
        "normalized_status": "approved"
      }
    ]
  }
}

​

Existing customers

​

Field formats