Onboarding & KYB

Koywe exposes a public onboarding surface for user registration flows and a public KYB surface for merchant verification. These are separate but related workflows.

Two Public Flows

User Pre-Onboarding

Use these endpoints to create and submit registration drafts:

POST /api/v1/pre-onboarding/registration-draft
PUT /api/v1/pre-onboarding/registration-draft/{draftId}
GET /api/v1/pre-onboarding/registration-draft/{draftId}
POST /api/v1/pre-onboarding/registration-form/{draftId}
GET /api/v1/pre-onboarding/registrations
GET /api/v1/pre-onboarding/registrations/{registrationId}/status

These endpoints are useful when your team needs to complete setup data incrementally before final submission.

Merchant KYB

Use these endpoints once a merchant exists and is ready for verification:

POST /api/v1/organizations/{organizationId}/merchants/{merchantId}/onboarding/kyb
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/onboarding/kyb
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/onboarding/kyb/{kybId}

Recommended Flow

Check Current Onboarding State

The authenticated user can retrieve onboarding evaluations with:

GET /api/v1/onboarding/me

This endpoint is useful for dashboards and internal setup tooling because it shows where a user is blocked.

Trigger Merchant KYB


curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/YOUR_ORG_ID/merchants/YOUR_MERCHANT_ID/onboarding/kyb' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "forceRetrigger": false
  }'

After triggering, poll the KYB status endpoint until the provider form link or final state is available.

When You Need This

Use pre-onboarding when the person or team is still preparing registration data.
Use onboarding/me when you need a read-only status summary for the current user.
Use merchant KYB after the merchant has been created and basic entity data is ready.

Best Practices

Save draft IDs so users can resume registration instead of starting over.
Treat KYB as asynchronous and expect polling or dashboard follow-up.
Separate “user registration complete” from “merchant KYB approved” in your internal state model.