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. consents must contain the id of every required definition from GET /api/partner/v1/consents; completeness is checked only when a new draft is created, so an idempotent replay still returns 200 after a new consent version was published. 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

A draft already exists for this partner_external_ref on this channel (idempotent replay) — the existing draft is returned unchanged.

201

Draft created.

401

Missing, malformed, revoked, or unusable partner API key.

403

The partner key lacks the onboarding:write scope.

422

Validation error (e.g. email already registered, phone not 9 digits, a required consent missing from consents, or an id that is not an active definition) or channel resolution failure (channel does not belong to the partner, or the partner owns multiple channels and none was supplied). A consent error lists the missing definitions as key (id N).