Skip to navigation
Corporate Accounts

Create Corporate Sub-account

View as Markdown

Creates the dedicated bank sub-account for the business, using a kyc_id from a completed Validate Corporate KYC OTP. settlementId is optional and works the same way as in the Customer flow.

Body

FieldTypeRequiredRules
phoneNumberstringyesMin 7 characters.
emailAddressstringyesValid email.
rn_numberstringyesCompany registration (CAC RC/BN) number, min 3 characters.
kyc_idstringyesThe kyc_id from Validate Corporate KYC OTP (not the session id from Initiate). KYC must belong to you and have status VERIFIED/SUCCESS.
settlementIdnumbernoId of one of your settlement accounts.

Unknown fields are rejected ("<field>" is not allowed). Validation errors are 400 with an errors array using Joi’s default messages (field name in double quotes).

Behaviour

  • Creates the dedicated NUBAN sub-account at the bank. If the bank returns an account number you already hold, the existing record is updated and returned (the new attempt is stored as DUPLICATE).
  • coporate_reference (note spelling) is the sub-account id used by List / Fetch Corporate Sub-accounts.
  • All provider/settlement failures return 400 with message: "Failed to create COOP subaccount" and the reason in error.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
phoneNumberstringOptional
emailAddressstringOptional
rn_numberstringOptional
kyc_idstringOptional
settlementIdintegerOptional

Response

OK
statusstringOptional
messagestringOptional
dataobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error