Get Merchant KYC Status

Intro

Returns a sub-merchant’s current KYC verification status and latest submission details — whether they can accept payments and receive payouts right now — for both Khaime KYC (African markets) and Stripe Connect (everywhere else).

Context

This is the read side of the KYC lifecycle: call it after Submit KYC to see the outcome, poll it while a merchant is mid-onboarding, and check it before deciding whether to send traffic to Resubmit KYC. It’s also the cheapest way to confirm a merchant is ready before you attempt a charge with their sub_merchant_id.

Hows

Path parameters

number

required

The ID of the sub-merchant.

Response — Khaime KYC merchant

{
  "success": true,
  "message": "KYC status retrieved",
  "data": {
    "provider": "khaime",
    "status": "approved",
    "verification_status": "kyc_approved",
    "can_accept_payments": true,
    "can_receive_payouts": true,
    "khaime_submission": {
      "id": 42,
      "status": "approved",
      "business_type": "individual",
      "settlement_currency": "NGN",
      "country_mismatch": false,
      "submitted_at": "2026-04-10T12:00:00.000Z",
      "reviewed_at": "2026-04-10T14:30:00.000Z",
      "rejection_reason": null
    },
    "connect_onboarding": null
  }
}

Response — Stripe Connect merchant

{
  "success": true,
  "message": "KYC status retrieved",
  "data": {
    "provider": "stripe",
    "status": "approved",
    "verification_status": "kyc_approved",
    "can_accept_payments": true,
    "can_receive_payouts": true,
    "khaime_submission": null,
    "stripe_connect": {
      "account_id": "acct_1234567890",
      "charges_enabled": true,
      "payouts_enabled": true,
      "requirements": {
        "currently_due": [],
        "eventually_due": [],
        "past_due": []
      },
      "onboarding_url": null
    }
  }
}

Response fields

Field	Type	Description
`provider`	string	KYC provider: `khaime` or `stripe`
`status`	string	Normalized status: `not_started`, `pending`, `approved`, `rejected`, `action_required`
`verification_status`	string	Same status with a `kyc_` prefix (see values below) — kept for backward compatibility
`can_accept_payments`	boolean	Whether the merchant can be charged right now
`can_receive_payouts`	boolean	Whether the merchant can receive payouts right now

`verification_status` values

Value	Description
`kyc_not_started`	No KYC has been submitted yet
`kyc_pending_review`	Submission is awaiting review
`kyc_approved`	Approved — merchant can receive payouts
`kyc_rejected`	Rejected — resubmission required
`kyc_additional_info_requested`	Reviewer has asked for more information
`kyc_revoked`	Previously-approved KYC has since been revoked

`khaime_submission` object (African markets)

Present when the merchant is on Khaime KYC (NG, GH, ZA, KE).

Field	Type	Description
`id`	number	KYC submission ID
`status`	string	`pending_review`, `approved`, `rejected`, `additional_info_requested`, `revoked`
`business_type`	string	`individual` or `registered_business`
`settlement_currency`	string	Currency locked in for this merchant’s payouts
`country_mismatch`	boolean	`true` if the identity document’s country and the bank’s country differ — this doesn’t block approval on its own, but flags the submission for closer review
`submitted_at`	string	ISO 8601 submission timestamp
`reviewed_at`	string \| null	ISO 8601 review timestamp, or `null` if still pending
`rejection_reason`	string \| null	Reason for rejection, if rejected

This status endpoint returns a smaller, summary view — it does not echo back legal_name, id_country, or bank account details. If you need those, they’re in the response from Submit KYC or Resubmit KYC, or from Get Merchant Details.

`stripe_connect` object (non-African markets)

Present when the merchant is on Stripe Connect.

Field	Type	Description
`account_id`	string	Stripe Connect account ID
`charges_enabled`	boolean	Can accept charges
`payouts_enabled`	boolean	Can receive payouts
`requirements`	object	Outstanding onboarding requirements
`requirements.currently_due`	array	Fields Stripe needs right now
`requirements.eventually_due`	array	Fields needed eventually
`requirements.past_due`	array	Overdue fields — account may already be restricted
`onboarding_url`	string \| null	URL to resume onboarding, if incomplete

Determining readiness

const isReady = response.data.can_accept_payments && response.data.can_receive_payouts;

That single check is provider-agnostic and is the one to use before attempting a charge. The provider-specific objects (khaime_submission, stripe_connect) are for showing merchants and your own team more detail — you shouldn’t need to branch on provider just to decide if a merchant is chargeable.

Error cases

Status	Error	Fix
`401`	Missing or invalid `X-API-Key` header	Include a valid Partner API key
`403`	`This endpoint is restricted to marketplace operators`	Your API key must belong to a marketplace operator account
`404`	`Active merchant relationship not found`	The merchant is not linked to your marketplace

curl -X GET "https://api.khaime.com/api/v1/marketplace/merchants/123/kyc" \
  -H "X-API-Key: pk_sandbox_your_key"

Whys

A single normalized status on top of two providers’ native statuses. Khaime KYC and Stripe Connect model verification completely differently internally (a review queue status vs. charges_enabled/payouts_enabled flags plus outstanding requirements). Rather than making you learn both models, the endpoint reduces both down to the same handful of status values and two booleans you can act on immediately. verification_status kept alongside status. It predates the normalized status field and is retained so existing integrations built against the kyc_-prefixed values keep working.

Why nots

Not a KYC submission or update endpoint. This is read-only — use Submit KYC or Resubmit KYC to change anything.
Doesn’t return bank account details. For bank details on file, use Get Merchant Details or the response from the submit/resubmit endpoints.
Not a live poll of Stripe. The Stripe fields reflect the last state Khaime received via webhook (or, occasionally, an on-demand refresh) — not necessarily this exact second’s state on Stripe’s side. For most integrations the lag is immaterial, but don’t treat this as a real-time Stripe API proxy.

Submit KYC — submit a new KYC application
Resubmit KYC — resubmit after rejection
Setup Payout — configure bank details for payout

API Reference

Account

Products & Pricing

Payments

Integration Guides

Commerce API

Subscriptions

Marketplace

Intro

Context

Hows

Path parameters

Response — Khaime KYC merchant

Response — Stripe Connect merchant

Response fields

`verification_status` values

`khaime_submission` object (African markets)

`stripe_connect` object (non-African markets)

Determining readiness

Error cases

Whys

Why nots

​Intro

​Context

​Hows

​Path parameters

​Response — Khaime KYC merchant

​Response — Stripe Connect merchant

​Response fields

​verification_status values

​khaime_submission object (African markets)

​stripe_connect object (non-African markets)

​Determining readiness

​Error cases

​Whys

​Why nots

​Related

Intro

Context

Hows

Path parameters

Response — Khaime KYC merchant

Response — Stripe Connect merchant

Response fields

`verification_status` values

`khaime_submission` object (African markets)

`stripe_connect` object (non-African markets)

Determining readiness

Error cases

Whys

Why nots

Related