> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Merchant KYC Status

> Retrieve the current KYC verification status for a sub-merchant.

# 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

<ParamField path="merchantId" type="number" required>
  The ID of the sub-merchant.
</ParamField>

## Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```javascript theme={null}
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             |

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.khaime.com/api/v1/partner/marketplace/merchants/123/kyc" \
    -H "X-API-Key: pk_sandbox_your_key"
  ```
</RequestExample>

## Related

* [Submit KYC](/api-reference/marketplace/submit-kyc) — submit a new KYC application
* [Resubmit KYC](/api-reference/marketplace/resubmit-kyc) — resubmit after rejection
* [Setup Payout](/api-reference/marketplace/setup-payout) — configure bank details for payout