KYB onboarding API for Nigerian marketplaces: A Practical Integration Guide

A KYB onboarding API for Nigerian marketplaces should do more than collect incorporation documents. It should help your platform establish who a seller is, understand who controls the business, and decide which financial capabilities that seller can access. For founders and developers, the challenge is connecting verification decisions to collections, balances and payouts without creating an onboarding bottleneck.

This guide focuses on Nigerian marketplaces onboarding business sellers. It explains how to structure verification, manage exceptions and translate compliance decisions into product controls. Paddle brings KYB/AML verification and payment capabilities into the same platform, giving teams a foundation for building that workflow.

What KYB needs to establish before sellers transact

Know Your Business, or KYB, is the process of verifying a business and understanding its ownership, activities and risk profile. It is related to, but distinct from, identity verification for individuals.

For a marketplace, verifying a business name alone does not establish that the person registering can act for the business. Nor does it explain whether the proposed transaction activity makes sense.

Your onboarding policy should address four questions:

• Does the business exist? Establish its registration status and relevant identifying information.
• Who owns or controls it? Identify beneficial owners and controlling persons according to applicable requirements.
• Who is acting for it? Verify the representative and their authority where required.
• What will it do on your platform? Understand its products, customers, payment flows and expected activity.

Requirements vary by legal structure, business activity and banking-partner policy. Registered companies, business names and other seller types should not automatically receive identical questionnaires.

This is implementation guidance, not legal advice. Confirm your obligations with qualified advisers and your banking partners, and check applicable CBN circulars and other relevant guidance before launch.

How to evaluate a KYB onboarding API for Nigerian marketplaces

Start with your seller journey rather than a feature checklist. Map the point at which sellers create profiles, receive funds and request withdrawals. Then identify the verification decision required before each capability becomes available.

Confirm coverage and evidence requirements

Ask which Nigerian business structures the verification service supports, what information it checks and which supporting documents may be necessary. For registered entities, confirm how Corporate Affairs Commission registration information is validated.

Distinguish between collecting a document, extracting its contents and validating its information. These are different operations with different assurance levels.

Also establish what happens when a record cannot be matched automatically. A usable integration needs a path for legitimate businesses with incomplete records, spelling differences or changed details.

Understand screening and review responsibilities

Ask about beneficial-owner verification, sanctions screening, politically exposed person screening and adverse-information checks where relevant. Confirm the available coverage and who reviews potential matches.

A screening alert is not automatically proof of wrongdoing. Your workflow needs documented escalation and human review rather than a blanket rejection rule.

Check operational integration options

Confirm how you submit cases, receive results, handle additional-information requests and retrieve review history. Ask whether callbacks, polling or other mechanisms are supported.

For Paddle, use the current documentation and implementation discussions to establish supported verification steps and integration contracts. Do not design around assumed endpoints, event names or turnaround guarantees.

Collect the right data without overloading sellers

A long form is not necessarily a strong compliance process. Collect information that serves a defined verification or risk-assessment purpose, and explain why sensitive fields are needed.

A business-seller intake may include:

• Legal name, registration identifier, entity type and business address.
• Trading name, website or storefront, and a description of goods or services.
• Representative details and evidence of authority where required.
• Ownership and control information, including relevant ownership relationships.
• Expected transaction activity and intended payout destinations.
• Supporting registration or other documents required by the review policy.

For Nigeria, separate legal names from trading names in your data model. This helps reviewers understand differences between a storefront brand, registration record and proposed bank beneficiary.

Use conditional fields for different entity types. Save progress, provide clear document guidance and explain how sellers can correct errors. Avoid asking sellers to resubmit information your team already holds securely unless an update is necessary.

Apply appropriate privacy notices, lawful processing grounds, access controls and retention rules under applicable Nigerian data-protection requirements. Business onboarding frequently involves personal data about representatives and owners.

Turn verification outcomes into payment permissions

The most important engineering boundary is between a verification result and a financial action. A completed API request should not, by itself, enable payouts.

Model a clear internal state machine

Create internal states such as draft, submitted, under_review, needs_information, approved, restricted and rejected. These are illustrative application states, not Paddle API values.

Define which transitions are allowed and who can trigger them. For example, a seller should not move from needs_information to approved simply because a new document was uploaded. The updated evidence still needs the appropriate checks.

Keep provider results separate from your platform's policy decision. A technical verification outcome may be only one input into final approval.

Gate capabilities separately

Avoid using a single verified flag for everything. Your permissions model might separately control:

• Publishing a seller storefront.
• Activating a collection account.
• Receiving or accessing funds.
• Initiating payouts.
• Changing a payout beneficiary.

The permitted sequence must follow your agreed compliance and banking-partner requirements. Do not assume funds can be collected before verification simply because the product supports account creation.

Paddle offers virtual accounts with NUBANs and instant NIP payouts to 120+ Nigerian banks. Connect access to these capabilities to your approved seller policy, rather than treating verification and payments as disconnected integrations.

Recheck permission when money moves

At payout execution, check the seller's current status and beneficiary approval again. A seller may have become restricted after creating the withdrawal request.

Enforce these checks server-side. Frontend controls improve usability but cannot protect a payout endpoint from direct requests or stale sessions.

Build an auditable review and exception workflow

Automated checks will not resolve every case. Give reviewers a structured queue with evidence, reason codes, requested corrections and a record of previous decisions.

Log who changed a decision, when it changed and why. Preserve the policy version and relevant evidence references so your team can reconstruct the basis for approval. Avoid copying raw identity documents into general application logs.

Use role-based access for sensitive records and consider additional approval for high-impact overrides. Customer-support staff should not be able to silently remove a compliance restriction.

Where asynchronous notifications are supported, follow the documented authenticity checks and handle duplicate or out-of-order messages. Make event processing idempotent so retries do not create conflicting case updates or repeated downstream actions.

Prepare plain-language seller messages for missing information and review delays. Keep sensitive screening details restricted where disclosure would be inappropriate or prohibited.

Practical pre-launch checklist

Use this checklist across product, engineering and compliance before onboarding live sellers:

1. Define eligible sellers. Document supported entity types, prohibited activities and escalation criteria.
2. Agree verification requirements. Confirm evidence, ownership checks and screening responsibilities with relevant partners.
3. Map the data journey. Identify where personal data is collected, stored, accessed and deleted.
4. Implement internal states. Separate provider responses from final platform decisions and capability permissions.
5. Protect payout execution. Check current eligibility, beneficiary status and applicable controls server-side.
6. Test failure paths. Cover unavailable checks, missing documents, duplicate submissions, delayed results and corrections.
7. Prepare manual review. Assign owners, escalation routes and auditable override procedures.
8. Plan ongoing monitoring. Define responses to ownership changes, unusual activity and changed payout details.

After launch, measure where sellers abandon onboarding, how often cases need additional information and which rejection reasons recur. Use those findings to improve instructions and routing, not to bypass required checks.

Build it with Paddle

Paddle combines KYB/AML verification with virtual accounts, payouts, ledgers and other embedded financial capabilities. For Nigerian marketplaces, that creates a practical foundation for connecting seller approval to the movement of money.

Start with one seller segment, a documented verification policy and explicit payout permissions. Confirm the supported verification workflow and partner requirements before expanding to additional business types or cross-border activity.

Paddle is a banking-as-a-service platform by Pickpadi Global Ltd, not a bank. Banking services are provided by CBN-licensed partner banks.

Ready to build a more controlled seller onboarding flow? Create a free account and read the API docs.