Sub-merchant onboarding
Three ways to onboard sub-merchants under your platform — hosted, embedded, and API-driven.
Before a sub-merchant can accept payments or receive payouts, VINR must verify their identity and register them under your platform account. There are three integration paths.
Onboarding modelsAsk
Hosted onboarding
VINR provides a hosted onboarding page. You redirect the sub-merchant to a VINR-generated URL; they complete identity and bank details; VINR redirects them back to your platform.
When to use: fastest integration; acceptable when a redirect is fine UX.
POST /v1/platform/sub-merchants
{
"email": "seller@example.com",
"return_url": "https://myplatform.com/onboarding/complete",
"refresh_url": "https://myplatform.com/onboarding/retry"
}
→ { "onboarding_url": "https://onboarding.vinr.com/sm_..." }Redirect the sub-merchant to onboarding_url. When they finish (or need to return), VINR calls your return_url or refresh_url.
Embedded onboarding
Render the onboarding flow inside your app using VINR's Embedded Components SDK. The sub-merchant never leaves your site.
When to use: branded experience is important; you want to control the visual context.
<VinrOnboarding
subMerchantId="sm_..."
onComplete={() => refetch()}
/>The component handles multi-step collection (identity, bank account, business details), adaptive document prompts by country, and real-time verification status.
API-driven onboarding
Collect all information in your own UI and push it to VINR via API. Full control, highest engineering cost.
When to use: fully white-labeled product; you already collect this data for other purposes.
POST /v1/platform/sub-merchants
POST /v1/platform/sub-merchants/{id}/legal-entity
POST /v1/platform/sub-merchants/{id}/documents
POST /v1/platform/sub-merchants/{id}/bank-accountsYou are responsible for keeping document and compliance requirements current as regulations change.
Onboarding lifecycleAsk
created → identity_submitted → under_review → active
↓
documents_required (VINR sends webhook)
↓
identity_submitted (re-submission)| Status | Meaning |
|---|---|
created | Sub-merchant record exists; no data submitted yet |
identity_submitted | KYC/KYB data submitted; VINR reviewing |
documents_required | Additional documents requested (webhook fired) |
active | Verification passed; can accept payments and receive payouts |
restricted | Partial capabilities only (e.g. can receive but not pay out) |
suspended | Account suspended; contact platform support |
WebhooksAsk
Subscribe to these events to drive onboarding UI state:
| Event | Trigger |
|---|---|
sub_merchant.created | New sub-merchant registered |
sub_merchant.verification.documents_required | Documents needed; payload lists which |
sub_merchant.verification.complete | Verification passed; account active |
sub_merchant.verification.failed | Verification failed; payload includes reason |
sub_merchant.suspended | Account suspended |
Networked onboardingAsk
Sub-merchants who already have a VINR account (from another platform) can reuse their verified identity. They authorize your platform to access their existing account — no re-submission of documents.
Next stepsAsk
- Verification & KYC/KYB — what documents are required and by whom
- Platform controls — restrict capabilities until onboarding is complete
