Marketplace
Resubmit Merchant KYC
Resubmit a KYC application after rejection or resume Connect onboarding.
POST
Intro
Resubmits a KYC application for a sub-merchant after rejection, or hands back a fresh onboarding session for a merchant still completing Stripe Connect — one endpoint for both providers, mirroring Submit KYC.Context
This is the recovery path in the KYC lifecycle:submit → pending_review → rejected → resubmit → pending_review (or additional_info_requested → resubmit). Check Get KYC Status first so you know which branch applies before calling this endpoint.
Hows
Path parameters
number
required
The ID of the sub-merchant.
Request body — Khaime KYC (African countries)
The shape mirrors Submit KYC’s structured format:id_country, account_type, owner, business (for registered businesses), and bank_account. Unlike submission, every field on resubmit is technically optional at the request-validation layer — but resubmission overwrites the stored record with whatever you send, so a partial owner object can leave previously-approved fields blank. Always send the complete corrected owner (and business, if applicable) object, not just the field the reviewer flagged.
Request body — Stripe Connect (everywhere else)
string
Where the merchant lands after completing Stripe onboarding. Optional — if omitted, Stripe falls back to its default session behavior. Still recommended so the merchant returns to your platform, not Khaime’s.
string
Where the merchant lands if the session expires or they exit early. Optional, for the same reason.
Unlike the initial Submit KYC call — where
return_url and refresh_url are required — they’re optional here. You don’t need to re-send country or any other Stripe fields; the existing submission on file drives the new session.Response — Khaime KYC
Response — Stripe Connect
Error cases
All of the
400 business-rule errors above are surfaced with error_code: INTERNAL_ERROR today, regardless of the underlying cause — don’t rely on error_code alone to distinguish between them; match on the message text as well until this API area’s error codes are refined further.
Whys
One resubmit endpoint instead of separate rejection-fix and Stripe-resume routes. Both cases are “the merchant needs another pass at verification” — collapsing them keeps your integration from needing to track which provider a merchant is on before deciding which endpoint to call. Resubmission updates a record in place rather than creating a fresh one for Khaime KYC. A rejected submission’s row is reused when you resubmit, so the merchant keeps one continuous verification history (with the rejection reason preserved) rather than accumulating disconnected rows per attempt. Stripe resumes reuse the same connected account. Recreating a Stripe Connect account on every resume would orphan the original account and lose any progress the merchant already made — the resume path always targets the existingstripe_account_id.
Why nots
- Not for approved merchants. If KYC is already
approved, this endpoint refuses the request — use Update Merchant Payout to change bank details on an approved merchant instead. - Not for first-time submissions. If there’s no submission on file yet, this returns an error telling you to use Submit KYC.
- Partial payloads are risky, not recommended. The API doesn’t enforce a fully-populated
owner/businessobject on resubmit the way it does on initial submission, but omitting fields doesn’t necessarily preserve the previous values. Treat resubmission as “send the complete, corrected record,” not “send a diff.” - Doesn’t retry review automatically. A resubmission goes back into the same queue as a fresh submission — there’s no fast-track for merchants who’ve been rejected before.