Complete onboarding and move from account approval to your first production-ready integration path.

⏱️

Time to integrate: Most teams can complete sandbox setup in under 1 hour after they receive API access and required onboarding approval.

This page shows the exact onboarding sequence for NadaPay from organization setup through KYC/KYB (Know Your Customer / Know Your Business), wallet or account readiness, and your first transaction flow.

What onboarding covers

Use this workflow to:

• register your organization
• complete KYC or KYB verification
• confirm account or wallet readiness
• fund the account you will use for transactions
• complete your first working transaction flow
• prepare for production approval

Who should use this page

This page is for:

• backend engineers building the integration
• solutions architects designing the system flow
• technical PMs coordinating launch readiness
• security and compliance reviewers validating controls

Prerequisites

Complete these steps before you start the full integration:

1. Create or request your NadaPay organization account.
2. Assign an internal owner for engineering, compliance, and operations.
3. Prepare your KYC or KYB documents.
4. Prepare a secure server-side environment to store your x-api-key.
5. Decide which NadaPay capabilities you are implementing first: account funding, beneficiary management, quotes, or transaction execution.

Onboarding sequence

Follow this sequence in order.

1. Register your organization

Create your NadaPay account using your business contact details.

During registration, collect and confirm:

• legal business name
• primary business email
• internal technical contact
• internal compliance or operations contact

If you are onboarding as a partner managing sub-businesses, also define whether you need child organization support.

2. Complete KYC or KYB

NadaPay requires verification before live financial activity can begin.

KYC requirements for individuals or sole traders

Prepare:

• government-issued ID
• proof of address

KYB requirements for companies and institutions

Prepare:

• certificate of incorporation
• proof of business address
• Ultimate Beneficial Owner (UBO) details

🔎

AML (Anti-Money Laundering) screening is part of onboarding. Verification data may be checked against internal compliance controls and watchlists before access is expanded.

3. Track verification status

Use the verification endpoint as your source of truth for onboarding state.

Recommended check:

curl --request GET \
  --url "$NADAPAY_BASE_URL/organizations/verification/KYB" \
  --header "x-api-key: $NADAPAY_API_KEY" \
  --header "Accept: application/json"

Use the returned verification state to decide whether your team should:

• continue submitting onboarding data
• wait for review
• fix missing or invalid information
• proceed to account setup, funding, or go-live steps

⚠️

Needs confirmation: Exact verification statuses, status transition definitions, and which statuses unlock sandbox versus production access are not yet documented.

4. Confirm wallet or account readiness

Once your organization is provisioned for testing, store your sandbox API key in your server-side environment and confirm your organization accounts are available.

Use these checks first:

1. Authenticate with x-api-key.
2. Fetch your organization accounts.
3. Identify the account or wallet you expect to use for funding and execution.
4. Confirm the environment is correct for those accounts.

Do not embed your API key in frontend or mobile applications.

5. Fund the account you will transact from

Before you try the full transaction flow, confirm the source account can be funded and has the balance required for your test or live scenario.

Use these endpoints as needed:

• GET /organizations/accounts
• GET /organizations/balance/{currency}
• GET /transactions/deposit-instructions
• POST /organizations/upgrade-virtual-account if your funding flow requires inbound receiving details on an eligible account

⚠️

Needs confirmation: Exact funding workflow, supported rails, and when a virtual account upgrade is required still need to be documented more fully.

6. Complete your first transaction flow

After organization, verification, and account readiness are confirmed, build the minimum working payout flow:

1. Create a beneficiary.
2. Add a beneficiary account.
3. Resolve bank details if the flow uses bank rails.
4. Check transaction limits for the intended corridor.
5. Generate a quote.
6. Execute the transaction.

This sequence gives your team a complete operational test from onboarding through funds movement.

7. Validate failure handling and production readiness

Before requesting production access, confirm your system can handle:

• invalid API keys
• verification still pending
• missing required fields
• rate limit responses
• insufficient balance conditions
• rejected or failed transaction outcomes

After sandbox validation, prepare for production enablement.

Your review should include:

• confirmation that onboarding is approved
• confirmation that your integration uses the correct production API key
• confirmation that secrets are stored securely
• confirmation that your team can monitor failures and retries
• confirmation that account funding, beneficiary setup, quote generation, and transaction execution are tested end to end

For launch requirements, continue to Going Live.

⚠️

Needs confirmation: Exact webhook event model, signature verification process, and retry behavior still need to be documented before this page can fully define operational event handling.

Onboarding checklist

Use this checklist to reduce delays.

Verification workflow

What success looks like

Your onboarding is progressing correctly when:

• your organization is registered
• required KYC or KYB documents are submitted
• your verification status endpoint returns an actionable state
• your team has sandbox API access
• your first end-to-end sandbox flow succeeds

Common reasons onboarding stalls

Onboarding usually slows down when:

• ownership details are incomplete
• legal entity information does not match submitted records
• technical teams are waiting on compliance review without checking the verification endpoint
• production assumptions are being tested in sandbox

How to recover from incomplete or rejected submissions

If verification is incomplete or rejected:

1. Identify the missing business or identity data.
2. Correct the submitted information.
3. Resubmit through the approved onboarding channel.
4. Recheck status through the verification endpoint.
5. Do not proceed to production workflows until the status is approved for that environment.

⚠️

Needs confirmation: Exact resubmission workflow, approval timing expectations, and rejection reason taxonomy are not yet documented.

Enterprise implementation notes

Security

• Store API keys only in server-side systems.
• Restrict access to production keys using least privilege.
• Separate sandbox and production secrets.

Architecture

• Keep NadaPay API calls in backend services, not browser clients.
• Centralize logging for account, beneficiary, quote, and transaction requests.
• Add alerting for authentication failures, rate limits, and transaction errors.

Auditability

• Record the internal actor or system that initiated each API call.
• Log request IDs, organization IDs, transaction IDs, and timestamps where available.
• Retain onboarding decisions and operational approvals in your internal systems.

Troubleshooting

Verification appears stuck

Check the verification endpoint before escalating. Use the latest returned state to determine whether the issue is missing data, pending review, or environment access.

Sandbox access is not working

Confirm:

• you are using the sandbox API key
• the x-api-key header is present
• your base URL matches the intended environment

Production cannot start after approval

Confirm:

• the organization is approved for production use
• production credentials are configured separately from sandbox
• your live operational checklist is complete

Next steps