> ## 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 Details

> Retrieve detailed information about a specific sub-merchant.

# Get Merchant Details

Retrieve comprehensive information about a specific sub-merchant in your marketplace, including their profile, payout configuration, commission settings, and statistics.

## Path Parameters

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

## Response

```json theme={null}
{
  "success": true,
  "message": "Merchant details retrieved successfully",
  "data": {
    "id": 1676,
    "profile": {
      "business_name": "Sub Store",
      "business_email": "merchant@example.com",
      "business_phone": "+2348012345678",
      "business_country": "NG",
      "subdomain": "substore",
      "custom_domain": null,
      "created_at": "2026-03-15T10:30:00.000Z"
    },
    "marketplace": {
      "marketplace_id": 1042,
      "status": "active",
      "commission_rate": 0.08,
      "joined_at": "2026-03-20T14:00:00.000Z"
    },
    "payout": {
      "status": "active",
      "baseline_currency": "NGN",
      "payout_ready": true,
      "charge_eligible": true,
      "details": {
        "type": "bank_transfer",
        "bank_name": "Access Bank",
        "bank_code": "Access Bank",
        "account_number": "****6789",
        "account_name": "John Doe",
        "date_connected": "2026-03-20T15:00:00.000Z"
      }
    },
    "kyc": {
      "verification_status": "kyc_approved",
      "submission": {
        "id": 42,
        "status": "approved",
        "business_type": "individual",
        "settlement_currency": "NGN",
        "country_mismatch": false,
        "rejection_reason": null,
        "submitted_at": "2026-03-20T15:00:00.000Z",
        "reviewed_at": "2026-03-20T15:01:00.000Z"
      }
    },
    "settings": {
      "custom_platform_fee": null,
      "custom_international_fee": null,
      "customer_pays_transaction_fee": false
    },
    "stats": {
      "product_count": 12
    }
  }
}
```

## Response Fields

### profile

| Field              | Type   | Description                 |
| ------------------ | ------ | --------------------------- |
| `business_name`    | string | Merchant's business name    |
| `business_email`   | string | Merchant's email address    |
| `business_phone`   | string | Merchant's phone number     |
| `business_country` | string | 2-letter ISO country code   |
| `subdomain`        | string | Khaime subdomain            |
| `custom_domain`    | string | Custom domain if configured |
| `created_at`       | string | Account creation timestamp  |

### marketplace

| Field             | Type   | Description                                |
| ----------------- | ------ | ------------------------------------------ |
| `marketplace_id`  | number | Your marketplace ID                        |
| `status`          | string | Relationship status: `active`, `suspended` |
| `commission_rate` | number | Commission rate (0-1, e.g., 0.08 = 8%)     |
| `joined_at`       | string | When merchant joined the marketplace       |

### payout

| Field               | Type    | Description                                                                                                                                   |
| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`            | string  | `not_configured`, `pending_onboarding`, or `active`                                                                                           |
| `baseline_currency` | string  | Merchant's base currency (e.g., `NGN`, `USD`)                                                                                                 |
| `payout_ready`      | boolean | Whether payout account has been verified/configured                                                                                           |
| `charge_eligible`   | boolean | Whether the merchant can receive charges right now. `false` means any charge with `sub_merchant_id` pointing to this merchant will be blocked |
| `details`           | object  | Payout configuration details (see below)                                                                                                      |

#### payout.details (Bank Transfer - NG, GH, ZA, KE)

```json theme={null}
{
  "type": "bank_transfer",
  "bank_name": "Access Bank",
  "bank_code": "Access Bank",
  "account_number": "****6789",
  "account_name": "John Doe",
  "date_connected": "2026-03-20T15:00:00.000Z"
}
```

#### payout.details (International Transfer - US, GB, etc.)

```json theme={null}
{
  "type": "international_transfer",
  "account_id": "****abcd1234",
  "verification_status": "complete",
  "date_connected": "2026-03-20T15:00:00.000Z"
}
```

### kyc

| Field                            | Type           | Description                                        |
| -------------------------------- | -------------- | -------------------------------------------------- |
| `verification_status`            | string         | Overall KYC stage (see values below)               |
| `submission`                     | object \| null | Latest KYC submission, or `null` if none submitted |
| `submission.id`                  | number         | Submission ID                                      |
| `submission.status`              | string         | Submission-level status                            |
| `submission.business_type`       | string         | `individual` or `registered_business`              |
| `submission.settlement_currency` | string         | Currency locked for payouts                        |
| `submission.country_mismatch`    | boolean        | `true` if identity and bank countries differ       |
| `submission.rejection_reason`    | string \| null | Set when `status` is `rejected`                    |
| `submission.submitted_at`        | string         | ISO 8601 submission timestamp                      |
| `submission.reviewed_at`         | string \| null | ISO 8601 review timestamp, or `null` if pending    |

#### kyc.verification\_status values

| Value                           | Description                             |
| ------------------------------- | --------------------------------------- |
| `kyc_not_started`               | No KYC submitted yet                    |
| `kyc_pending_review`            | Awaiting review                         |
| `kyc_approved`                  | Approved — payout account may be active |
| `kyc_rejected`                  | Rejected — resubmission required        |
| `kyc_additional_info_requested` | Reviewer requested more documents       |
| `kyc_revoked`                   | Previously approved KYC revoked         |

### settings

| Field                           | Type    | Description                            |
| ------------------------------- | ------- | -------------------------------------- |
| `custom_platform_fee`           | number  | Custom platform fee override           |
| `custom_international_fee`      | number  | Custom international fee override      |
| `customer_pays_transaction_fee` | boolean | Whether customer pays transaction fees |

### stats

| Field           | Type   | Description                        |
| --------------- | ------ | ---------------------------------- |
| `product_count` | number | Total products created by merchant |

## Payout Status Values

| Status               | Description                                                        |
| -------------------- | ------------------------------------------------------------------ |
| `not_configured`     | Payout has not been set up                                         |
| `pending_onboarding` | Payout initiated but onboarding incomplete (Stripe countries only) |
| `active`             | Payout is fully configured and verified                            |

<Note>
  Use `charge_eligible` rather than `status` or `payout_ready` to determine whether you can charge this merchant. A merchant with `status: active` and `payout_ready: true` will still have `charge_eligible: false` if their real-time payout account (Gravv for NGN, Stripe connected account for international) is not in place. Call [Setup Merchant Payout](/api-reference/marketplace/setup-payout) to resolve this.
</Note>

## Error Codes

| Status | Error                                                  | Fix                                             |
| ------ | ------------------------------------------------------ | ----------------------------------------------- |
| `403`  | `This endpoint is restricted to marketplace operators` | Your account must have marketplace mode enabled |
| `404`  | `Merchant not found in your marketplace`               | The merchant is not linked to your marketplace  |
| `404`  | `Merchant not found`                                   | The merchant account doesn't exist              |

## Full Setup Flow

Before a sub-merchant can receive charges, complete the following steps:

```
Step 1 — For NGN merchants only: fetch supported banks
GET /marketplace/payout/banks?currency=NGN

Step 2 — Submit KYC (includes bank details for local bank countries)
POST /marketplace/merchants/{merchantId}/kyc
  → { business_type, legal_name, id_document_type, id_document_url, id_country,
      bank_country, bank_name, account_number, account_name }

Step 3 — Configure payout (if not auto-verified via KYC)
POST /marketplace/merchants/{merchantId}/payout
  NG/GH/ZA/KE → { country, settlement_bank, account_number, account_name }
  US/GB/EU    → { country, email } → redirect merchant to onboarding_url

Step 4 — Verify readiness
GET /marketplace/merchants/{merchantId}
  → check kyc.verification_status === "kyc_approved"
  → check payout.charge_eligible === true

Step 5 — Charge
POST /payments/charge
  → include sub_merchant_id in the request
```

<Note>
  For local bank countries (NG, GH, ZA, KE), submitting KYC with full bank details can auto-verify
  payout in one step — no separate payout setup call needed if `kyc.verification_status` comes back
  as `kyc_approved` and `payout.charge_eligible` is already `true`.
</Note>

| Country group                  | `charge_eligible: true` when                                         |
| ------------------------------ | -------------------------------------------------------------------- |
| NGN (`NG`)                     | KYC approved with bank details (auto) or after separate payout setup |
| StartButton (`GH`, `ZA`, `KE`) | KYC approved with bank details (auto) or after separate payout setup |
| Stripe (`US`, `GB`, `CA`, EU)  | After merchant completes Stripe onboarding via `onboarding_url`      |

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