Skip to navigation
Corporate Accounts

Initiate Corporate KYC

View as Markdown

Starts BVN verification for the signatory and triggers an OTP. Returns a session_id (also usable as kyc_id) for the next steps. Rate-limited: a maximum of 3 attempts, with a 60-second cooldown between attempts.

Errors: 429 too many attempts / retry too soon.

Body

FieldTypeRequiredRules
bvnstring or integeryesExactly 11 digits (string ^\d{11}$, or integer 10000000000-99999999999).

Behaviour

  • Opens (or reuses) a KYC session for this company + BVN while it is PENDING/OTP_SENT, then asks Safe Haven to send an OTP to the phone linked to the BVN. Calling this again for the same BVN re-uses the same session and counts as another attempt.
  • Every call (success or provider failure) consumes one attempt and starts a 60-second cooldown. Max 3 attempts per session (shared with Resend Corporate KYC OTP).
  • data.session_id and data.kyc_id are the same value (the session id). Use it as session_id in Resend/Validate. It is not the kyc_id required by Create Corporate Sub-account - that one comes from Validate Corporate KYC OTP.
  • message on success/provider-failure is passed through from the BVN provider (falls back to OTP sent / Unable to initiate BVN).
  • Validation errors return 400 with an errors array (Joi path + message).

Authentication

AuthorizationBearer

Access token from Generate Access Token (valid 15 minutes).

Request

This endpoint expects an object.
bvnstringOptional

Response

OK
statusstringOptional
messagestringOptional
dataobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error