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

merchantId

string

required

The ID of the sub-merchant to retrieve.

Response

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

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

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

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 to resolve this.

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

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.

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`

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

Documentation Index

​Get Merchant Details

​Path Parameters

​Response

​Response Fields

​profile

​marketplace

​payout

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

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

​kyc

​kyc.verification_status values

​settings

​stats

​Payout Status Values

​Error Codes

​Full Setup Flow

Get Merchant Details

Path Parameters

Response

Response Fields

profile

marketplace

payout

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

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

kyc

kyc.verification_status values

settings

stats

Payout Status Values

Error Codes

Full Setup Flow