Get Merchant KYC Status

Returns the current KYC verification status and latest submission details for a sub-merchant in your marketplace. This endpoint works for both Khaime KYC (African markets) and Stripe Connect (other markets).

Path Parameters

merchantId

number

required

The ID of the sub-merchant.

Response

{
  "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",
      "legal_name": "Amara Osei",
      "id_country": "NG",
      "bank_name": "Access Bank",
      "bank_account_number": "0123456789",
      "bank_account_name": "Amara Osei",
      "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
    },
    "stripe_connect": null
  }
}

For Stripe Connect Merchants

{
  "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

Top-Level 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	Legacy status with `kyc_` prefix (see values below)
`can_accept_payments`	boolean	Whether the merchant can process charges
`can_receive_payouts`	boolean	Whether the merchant can receive payouts

`verification_status` Values

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

`khaime_submission` Object (African Markets)

Present when the merchant uses Khaime KYC (NG, GH, ZA, KE). This is the single source of truth for KYC and bank details.

Field	Type	Description
`id`	number	KYC submission ID
`status`	string	Submission status: `pending_review`, `approved`, `rejected`, `additional_info_requested`, `revoked`
`business_type`	string	`individual` or `registered_business`
`legal_name`	string	Legal name provided
`id_country`	string	Country of identity document
`bank_name`	string \| null	Bank name
`bank_account_number`	string \| null	Account number
`bank_account_name`	string \| null	Account holder name
`bank_sort_code`	string \| null	Sort code if applicable
`settlement_currency`	string	Currency for payouts
`country_mismatch`	boolean	`true` if identity and bank countries differ
`submitted_at`	string	ISO 8601 submission timestamp
`reviewed_at`	string \| null	ISO 8601 review timestamp
`rejection_reason`	string \| null	Reason for rejection

`stripe_connect` Object (Non-African Markets)

Present when the merchant uses Stripe Connect.

Field	Type	Description
`account_id`	string	Stripe Connect account ID
`charges_enabled`	boolean	Can accept payments
`payouts_enabled`	boolean	Can receive payouts
`requirements`	object	Outstanding Stripe requirements
`requirements.currently_due`	array	Fields that must be collected now
`requirements.eventually_due`	array	Fields needed eventually
`requirements.past_due`	array	Overdue fields (account may be restricted)
`onboarding_url`	string \| null	URL to resume onboarding if incomplete

Determining Readiness

Use the following logic to determine if a merchant is ready for charges:

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

// Or check detailed status:
if (response.data.provider === 'khaime') {
  const isApproved = response.data.khaime_submission?.status === 'approved';
  const hasBankDetails = !!response.data.khaime_submission?.bank_account_number;
  const isReady = isApproved && hasBankDetails;
} else {
  const isReady = response.data.stripe_connect?.charges_enabled &&
                  response.data.stripe_connect?.payouts_enabled;
}

Error Codes

Status	Error	Fix
`401`	`Unauthorized`	Include a valid `X-API-Key` header
`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/partner/marketplace/merchants/123/kyc" \
  -H "X-API-Key: pk_sandbox_your_key"

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

Documentation Index

​Get Merchant KYC Status

​Path Parameters

​Response

​For Stripe Connect Merchants

​Response Fields

​Top-Level Fields

​verification_status Values

​khaime_submission Object (African Markets)

​stripe_connect Object (Non-African Markets)

​Determining Readiness

​Error Codes

​Related