Guides

Onboard a user

A user must pass identity checks and accept Ndeipi's terms before they can hold a wallet or move money. Ndeipi hosts both steps; you create the user and send them to the links.

The flow

Create the user
POST /users with type (individual or business) and your own external_reference. Personal details are optional here, because the hosted flow collects identity data. Businesses need business_name.
A second create with the same reference returns 409 external_reference_exists with the existing user's ID in existing_id, so a retried create is always safe.
Send them to the hosted links
POST /users/{user_id}/onboarding_links returns a KYC link and a terms link, each with its own status and expiry. Pass redirect_url to bring the user back to your app when they finish. Calling it again issues fresh links and expires the old ones.
Wait for the decision
Listen for user.kyc_status_changed and user.terms_status_changed. A user can move money once kyc_status and terms_status are both approved. Until then, wallets, deposit accounts, payout accounts and transfers are refused with 403 user_not_approved.

KYC statuses

`kyc_status`	Meaning	What to do
`not_started`	The user hasn't opened the KYC link.	Remind them, or issue fresh links.
`under_review`	Documents are being checked.	Wait for the event.
`incomplete`	Something is missing or unreadable.	Show `rejection_reasons` and send fresh links.
`approved`	Identity verified.	Create a wallet once terms are approved too.
`rejected`	Verification failed.	Show `rejection_reasons`; the user can't move money.

terms_status is pending until the user accepts the terms, then approved.

Updating and closing accounts

PATCH /users/{user_id} changes contact details and metadata. Identity details change only through a new onboarding link.
To close an account, pay its balance out first: deactivation is refused while a wallet holds funds (409 user_has_balance) or a transfer is open (409 user_has_open_transfers). A deactivated user can't send or receive, and can't be reactivated.