Create Merchant Onboarding Draft
POST/api/partner/v1/onboarding
Creates a draft merchant onboarding under your partner channel and returns the merchant ref, current status, and channel. The distribution channel is derived from the authenticated partner key (never trusted from the body); if your key owns more than one channel you must supply channel, and it must belong to you. Creation is idempotent on partner_external_ref (scoped per channel): repeating the call with the same reference returns the existing draft with 200 instead of creating a duplicate — a new draft returns 201. The response never contains the hosted-flow URL; obtain it from finalize or GET /onboarding/{ref} in next_action.url. Requires scope onboarding:write.
Request
Responses
- 200
- 201
- 401
- 403
- 422
A draft already exists for this partner_external_ref on this channel (idempotent replay) — the existing draft is returned unchanged.
Draft created.
Missing, malformed, revoked, or unusable partner API key.
The partner key lacks the onboarding:write scope.
Validation error (e.g. email already registered, phone not 9 digits, missing consents) or channel resolution failure (channel does not belong to the partner, or the partner owns multiple channels and none was supplied).