Business customer KYB

This guide is for any customer you create with type=business. The flow is different from type=individual — it has its own set of endpoints, its own data shape, and its own review timeline. Read this page first, then follow Onboarding a business customer for the step-by-step.

​

Two onboarding paths: Standard and Minimal

Every business customer carries a kyb_scope that controls two things:

1. What data you have to send to onboard them.
2. Which currencies they can hold a Virtual Bank Account in.

The two paths share the same identity columns. The only structural difference is whether you have to provide beneficial-owner data.

​

Who can use Minimal KYB?

Minimal KYB is gated by an admin-controlled allow list. Most platforms onboard their business customers under the Standard (FULL) path. Minimal KYB exists for platforms whose use case is genuinely Nigerian-naira-only — typically Nigerian fintechs collecting payments in NGN for their own customers, where the underlying NGN provider doesn’t require beneficial-ownership data. If your platform is on the allow list:

• You can pass kyb_scope=MINIMAL on a customer create.
• If you omit kyb_scope, your customers default to MINIMAL.
• You can still pass kyb_scope=FULL explicitly when you need a customer to qualify for non-NGN currencies.

If your platform is not on the allow list:

• Sending kyb_scope=MINIMAL returns 422.
• If you omit kyb_scope, your customers default to FULL.
• This is the right path for almost everyone — contact support@blaaiz.com only if your use case is genuinely NGN-only.

​

Upgrading from Minimal to Full

A Minimal customer can be upgraded to Full at any time via POST /customer/{id}/upgrade-kyb-scope — you supply the beneficial owners and the customer flips to FULL. After the upgrade, you upload owner ID files and call /submit again to re-verify the customer under the Standard floor. Upgrades are one-way. Once a customer is on Full, they stay on Full. There is no admin downgrade. The rest of this guide covers the Standard (FULL) flow. For Minimal onboarding see Onboarding a business customer → Minimal KYB onboarding.

​

Why a different flow than individuals?

A business customer is a company. Verifying it requires more than an ID document and a selfie:

• Beneficial owners (FULL only) — every owner / signatory / director that meets the threshold, with personal ID for each.
• A KYB document collection (both scopes) — incorporation certificate, articles of incorporation, share register, bank statements, etc. The exact set depends on the jurisdiction and the business profile.

The legacy id_file / id_file_back / proof_of_address_file / liveness_check_file slots that work for individual customers don’t model this. Business customers use a separate set of endpoints.

​

Lifecycle states

Three records each carry their own state. They share the same four-state vocabulary, but the rules differ.

​

Customer (verification_status)

PROCESSING is the active-review window — the saved customer state is frozen so compliance reviews a stable picture. Wait for the customer-level webhook before attempting edits. VERIFIED is final; corrections on a verified customer go through operations (see Customer data corrections).

​

Owner and KYB document (status)

Each owner and each document has its own status, even while the customer is PENDING. “Editable” assumes the parent customer’s state allows it: even a PENDING owner is locked while the customer is PROCESSING or VERIFIED. Locked edits return 400. To correct an APPROVED owner or document, contact operations — see Customer data corrections.

​

Editing a REJECTED owner or document

When you edit a previously rejected owner or document — change a field, replace a file, anything — its status automatically flips back to PENDING and its admin_comments are cleared. You don’t need to manually reset state. Fix the data, then call /submit to re-route the corrected record through review.

​

What /submit does

When you call POST /api/external/customer/{customer}/submit:

1. The customer flips from PENDING (or REJECTED on re-submission) to PROCESSING.
2. Every PENDING owner flips to PROCESSING.
3. Every PENDING KYB document flips to PROCESSING.
4. Owners and documents that were already APPROVED or REJECTED are not touched.
5. A customer.status_changed webhook fires for the customer-level transition.

There are no per-owner or per-document webhooks. The customer-level event is the only signal you need to track.

​

What we check before accepting a /submit

/submit runs a set of checks before flipping the customer into PROCESSING. If any check fails, the response is 422 with a message naming the specific gap, the customer stays editable, and you can fix and call /submit again. The required set depends on the customer’s kyb_scope. Minimal needs the identity baseline plus a formation document; Full needs everything Minimal needs plus beneficial owners.

​

Both Minimal and Full

Customer-level identity

• business_name is set.
• country (registered-address country) is set and a valid ISO alpha-2 code.
• registration_number is set.
• incorporation_country is set and a valid ISO alpha-2 code.
• country equals incorporation_country. By company law a company’s registered office sits in its country of incorporation, so the two must agree.
• operating_country is set whenever any other operating_* address field is set, and is a valid ISO alpha-2 code (the operating address can be in a different country from the registered one).

KYB documents

• At least one document of a formation type: CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, BENEFICIAL_OWNERSHIP_CERTIFICATE, INCORPORATION_DOCUMENTS, or CAC_STATUS_REPORT.

​

Full only — the additional rules

Owners

• At least one owner attached.
• The owners’ ownership_percentage values sum to exactly 100.
• Owner emails are unique within the customer (case-insensitive).
• For each owner: id_document_front is uploaded; id_document_back is uploaded for drivers_license, id_card, and resident_permit types and absent for passport.
• For each owner with the field set: date_of_birth is at least 18 years ago, id_expiry_date is strictly after today, and nationality / country / id_document_country are valid ISO alpha-2 codes.

Minimal customers do not need any of the owner rules above. You can attach owners to a Minimal customer if you want to — they’re stored on the record — but they don’t gate /submit.

​

Verification timeline

Business KYB review typically takes 1–5 business days. Compliance reviews each owner and each document individually before issuing the customer-level verdict. This is longer than individual KYC because business verification involves additional checks against company registries, beneficial-ownership records, and risk databases.

​

Re-submission

If a customer comes back as REJECTED, look at the admin_comments on each owner and each KYB document. The rejected items are editable; the approved items stay locked. Fix the rejected ones (replace files, edit fields) and call /submit again. The customer flips back to PROCESSING for re-review. See Handling KYB rejections.

​

Upgrading from Minimal to Full

A kyb_scope=MINIMAL customer is restricted to NGN VBAs. To enable USD / GBP / EUR for that customer, call POST /customer/{id}/upgrade-kyb-scope with the beneficial-owner data. The upgrade endpoint:

1. Checks that the customer is currently MINIMAL (or has no scope set, which is treated as Minimal). If they’re already FULL, returns 422.
2. Checks that the customer is not currently in PROCESSING. If they are, returns 400 — wait for the customer-level webhook before retrying.
3. Saves the new owners (and any optional augmentations like industry_type, business_type, etc.).
4. Flips kyb_scope to FULL. One-way — there is no downgrade.
5. If the customer was VERIFIED, transitions them back to PENDING. An upgrade is a re-onboarding under stricter rules; existing NGN VBAs are unaffected.

The upgrade endpoint does not run the Standard readiness checks. It saves the data only. After the upgrade succeeds:

6. Upload owner ID files via the normal owner-file endpoints (per owner, per slot).
7. Call POST /customer/{id}/submit to re-verify under the Standard checks.

You can think of an upgrade as: “add the owner data, then re-submit.” Splitting the two steps lets you upload owner ID files between them — running the Standard checks on the upgrade itself would force you to upload all owner files before owners even existed as records. The upgrade endpoint is the only way to change kyb_scope. The regular PUT /customer/{id} endpoint rejects kyb_scope in the payload — admin downgrades are also blocked by the same rule. To “fix” a customer onboarded at the wrong scope, talk to support.

​

What KYB unlocks

A verified business customer can hold Virtual Bank Accounts and act as a payout recipient. NGN VBAs are available for both Minimal and Full customers. USD, GBP, and EUR VBAs are gated to kyb_scope=FULL — Minimal customers are NGN-only. For payout currency support on business customers, see Creating your first payout. For verified individual customers, see Virtual Bank Accounts.