Setup Merchant Payout

Intro

Configures how a sub-merchant gets paid — local bank transfer or Stripe Connect, depending on their country — and is the step that unlocks charge_eligible for that merchant.

Context

This sits alongside KYC in the onboarding flow, not after it: for African markets, the bank details you send here can independently make a merchant charge-eligible even before (or instead of) sending bank details through Submit KYC — the two write to the same underlying verification record. For everywhere else, this endpoint is what actually creates the Stripe Connect account and starts onboarding.

Until payout is configured (and, for African merchants, approved) or Stripe onboarding is complete, any charge attempt using this merchant’s sub_merchant_id is blocked. Check payout.charge_eligible on Get Merchant Details to confirm readiness before charging.

Hows

Path parameters

string

required

The ID of the sub-merchant to configure payout for.

Request body

string

required

2-letter ISO country code (e.g., US, NG, GB). Determines which payout rail is used and the merchant’s settlement currency.

For `NG`, `GH`, `ZA`, `KE` — local bank transfer

string

required

Bank name. For NG specifically, this must exactly match a name from Get Supported Payout Banks — Khaime resolves it against that list to wire up the transfer rail.

string

required

Bank account number.

string

required

Account holder name.

For everywhere else — Stripe Connect

string

required

Merchant’s email address, used to create their Stripe Connect account.

string

required

Where the merchant is redirected after completing (or exiting) Stripe’s onboarding flow. Stripe uses this for both outcomes.

Without callback_url, the merchant has no way back to your platform after Stripe onboarding.

Response — African countries (immediate)

{
  "success": true,
  "message": "Payout setup completed successfully",
  "data": {
    "merchant_id": 1676,
    "payout_ready": true,
    "settlement_currency": "NGN",
    "country": "NG",
    "date_connected": "2026-03-28T14:30:00.000Z"
  }
}

Response — everywhere else (onboarding required)

{
  "success": true,
  "message": "Payout account created. Complete onboarding to activate.",
  "data": {
    "merchant_id": 1676,
    "payout_ready": false,
    "settlement_currency": "USD",
    "country": "US",
    "client_secret": "accs_1234567890",
    "onboarding_url": "https://connect.khaime.com/setup/..."
  }
}

When payout_ready is false, the merchant must complete Stripe onboarding using client_secret or onboarding_url before charge_eligible on Get Merchant Details turns true.

Country → currency mapping

Country	Currency	Payout type
`NG`	NGN	Immediate
`GH`	GHS	Immediate
`ZA`	ZAR	Immediate
`KE`	KES	Immediate
`US`	USD	Onboarding required
`GB`	GBP	Onboarding required
`CA`	CAD	Onboarding required
EU countries	EUR	Onboarding required

How funds are split at charge time

Once payout is configured, every charge made with this merchant’s sub_merchant_id is split automatically:

Recipient	Amount
Sub-merchant	Charge amount minus commission minus platform fee — transferred automatically
Marketplace operator	Commission — stays in the operator’s account
Khaime	Platform fee — taken upfront as part of the charge

No manual disbursement step is needed; the split happens in real time as the payment clears.

Checking readiness before charging

{
  "payout": {
    "status": "active",
    "payout_ready": true,
    "charge_eligible": true
  }
}

`charge_eligible`	Meaning
`true`	Ready — you can charge this merchant via `sub_merchant_id`
`false`	Not ready — payout setup is incomplete or Stripe onboarding is pending

NGN/African merchants: charge_eligible is true as soon as this endpoint returns payout_ready: true, no further action needed.
International merchants: charge_eligible becomes true only once the merchant completes Stripe onboarding via onboarding_url. Poll Get Merchant Details until it flips.

Error cases

Status	Error	Fix
`400`	`country is required`	Include the `country` field
`400`	`For this country, settlement_bank, account_number, and account_name are required`	Include all bank details for African countries
`400`	`For this country, email is required`	Include the merchant’s email for non-African countries
`400`	`callback_url is required for non-African countries...`	Include a `callback_url` for the Stripe redirect
`400`	`Payout is already set up for this merchant`	Already configured — use Update Merchant Payout instead
`400`	`Bank "<name>" is not supported for NGN payouts...`	The bank name doesn’t match a supported institution — check spelling against Get Supported Payout Banks
`401`	Missing or invalid `X-API-Key` header	Include a valid Partner API key
`403`	`This endpoint is restricted to marketplace operators`	Your account must have marketplace mode enabled
`404`	`Active merchant relationship not found`	The merchant is not linked to your marketplace

curl -X POST https://api.khaime.com/api/v1/merchants/1676/payout \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "settlement_bank": "Access Bank",
    "account_number": "0123456789",
    "account_name": "John Doe"
  }'

curl -X POST https://api.khaime.com/api/v1/merchants/1676/payout \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "email": "merchant@example.com",
    "callback_url": "https://yourplatform.com/merchants/1676/payout-complete"
  }'

Whys

Country decides the rail, not a separate flag. African markets settle over local bank transfer rails that Khaime already integrates with directly (so setup is synchronous); everywhere else routes through Stripe Connect, which owns bank verification and payout compliance for those geographies. Branching on country avoids asking partners to know which underlying rail a given country uses. NGN specifically validates the bank name against a fixed list. Khaime resolves the settlement bank against its own supported-institution list (rather than accepting any free-text bank name) so it can pick the correct transfer rail per bank at approval time, instead of failing silently at payout time. Immediate approval for African bank setups. Unlike Stripe Connect’s multi-step hosted flow, a local bank account paired with an already-verified business identity doesn’t need an additional onboarding round trip — so payout_ready can be true in the same response.

Why nots

Not for merchants who already have payout configured. Calling this a second time returns Payout is already set up for this merchant — use Update Merchant Payout to change bank details afterward.
Doesn’t verify identity. This endpoint is about payout mechanics (where money goes), not who the merchant is — that’s Submit KYC’s job, and for NGN specifically, charge_eligible still requires an approved KYC submission in addition to bank details.
Not a way to change country after the fact. If a merchant’s country changes (e.g., they relocate), this endpoint doesn’t support switching rails on an already-configured account — contact support.

Next Steps

Once charge_eligible is true:

Process charges on behalf of the merchant using the Create Charge endpoint with sub_merchant_id
View the merchant’s products using List Merchant Products

API Reference

Account

Products & Pricing

Payments

Integration Guides

Commerce API

Subscriptions

Installments

Marketplace

Intro

Context

Hows

Path parameters

Request body

For `NG`, `GH`, `ZA`, `KE` — local bank transfer

For everywhere else — Stripe Connect

Response — African countries (immediate)

Response — everywhere else (onboarding required)

Country → currency mapping

How funds are split at charge time

Checking readiness before charging

Error cases

Whys

Why nots

Next Steps

​Intro

​Context

​Hows

​Path parameters

​Request body

​For NG, GH, ZA, KE — local bank transfer

​For everywhere else — Stripe Connect

​Response — African countries (immediate)

​Response — everywhere else (onboarding required)

​Country → currency mapping

​How funds are split at charge time

​Checking readiness before charging

​Error cases

​Whys

​Why nots

​Next Steps

Intro

Context

Hows

Path parameters

Request body

For `NG`, `GH`, `ZA`, `KE` — local bank transfer

For everywhere else — Stripe Connect

Response — African countries (immediate)

Response — everywhere else (onboarding required)

Country → currency mapping

How funds are split at charge time

Checking readiness before charging

Error cases

Whys

Why nots

Next Steps