Skip to main content
POST
/
marketplace
/
merchants
/
{merchantId}
/
payout
curl -X POST https://api.khaime.com/api/v1/partner/marketplace/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"
  }'

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.

​
Setup Merchant Payout

Configure payout for a sub-merchant. The country determines which payment infrastructure is used and what information is required. Once configured, the merchant’s baseline_currency is automatically set based on their country.
This is a required step before a sub-merchant can receive charges. Until payout is configured, any charge attempt with sub_merchant_id will be blocked. Check payout.charge_eligible on Get Merchant Details to confirm readiness.
For NGN (NG) merchants, the settlement_bank must be a bank name from Get Supported Payout Banks. Retrieve the list first to ensure a valid name is used.

​
Data Storage

All bank details are stored in the KycSubmissions table, which is the single source of truth for both KYC status and payout information. This endpoint creates or updates the KycSubmissions record for the merchant.

​
Path Parameters

​
merchantId
string
required
The ID of the sub-merchant to configure payout for.

​
Request Body

​
country
string
required
2-letter ISO country code (e.g., US, NG, GB). This determines the payout infrastructure and baseline_currency.

​
For African Countries (NG, GH, ZA, KE)

These countries use local bank transfers. Include bank account details:
​
settlement_bank
string
Bank name for the settlement bank. Required for NG, GH, ZA, KE. For NGN merchants, this must exactly match a name from Get Supported Payout Banks.
​
account_number
string
Bank account number. Required for NG, GH, ZA, KE.
​
account_name
string
Account holder name. Required for NG, GH, ZA, KE.

​
For Other Countries (US, GB, CA, EU, etc.)

These countries use Stripe Connect. The merchant must complete an onboarding flow:
​
email
string
Merchant’s email address. Required for non-African countries.

​
Response

​
African Countries (Immediate Setup)

When country is NG, GH, ZA, or KE, payout is configured immediately and bank details are stored in KycSubmissions: 
{
  "success": true,
  "message": "Payout setup completed successfully",
  "data": {
    "merchant_id": 1676,
    "payout_ready": true,
    "baseline_currency": "NGN",
    "country": "NG",
    "date_connected": "2026-03-28T14:30:00.000Z"
  }
}

​
Other Countries (Onboarding Required)

For international countries, the merchant must complete Stripe Connect onboarding: 
{
  "success": true,
  "message": "Payout account created. Complete onboarding to activate.",
  "data": {
    "merchant_id": 1676,
    "payout_ready": false,
    "baseline_currency": "USD",
    "country": "US",
    "client_secret": "accs_1234567890",
    "onboarding_url": "https://connect.stripe.com/setup/..."
  }
}
When payout_ready is false, the merchant must complete Stripe onboarding using the provided client_secret or onboarding_url. Until they do, charge_eligible on Get Merchant Details will remain false and any charge with their sub_merchant_id will be blocked.

​
Where Data is Stored

DataStorage Location
Bank nameKycSubmissions.bank_name
Account numberKycSubmissions.bank_account_number
Account nameKycSubmissions.bank_account_name
Sort codeKycSubmissions.bank_sort_code
Stripe account IDKycSubmissions.stripe_account_id
KYC statusKycSubmissions.status
Settlement currencyKycSubmissions.settlement_currency
Date connectedEducatorportfolio.date_connected
Important: The KycSubmissions table is the single source of truth for all KYC and bank details. Legacy fields in Educatorportfolio (like educator_bank_name) are deprecated and no longer used.

​
Country to Currency Mapping

CountryCurrencyPayout Type
NGNGNImmediate
GHGHSImmediate
ZAZARImmediate
KEKESImmediate
USUSDOnboarding Required
GBGBPOnboarding Required
CACADOnboarding Required
EU countriesEUROnboarding Required

​
Error Codes

StatusErrorFix
400country is requiredInclude the country field
400settlement_bank, account_number, and account_name are requiredFor African countries, include all bank details
400email is requiredFor non-African countries, include the email
400Payout is already set up for this merchantPayout has already been configured — use Update Payout instead
403This endpoint is restricted to marketplace operatorsYour account must have marketplace mode enabled
404Active merchant relationship not foundThe merchant is not linked to your marketplace
curl -X POST https://api.khaime.com/api/v1/partner/marketplace/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"
  }'

​
How funds are split at charge time

Once payout is configured, funds are automatically split every time a charge is made with this merchant’s sub_merchant_id:
RecipientAmount
Sub-merchantCharge amount minus commission minus platform fee — transferred automatically to their bank/Stripe account
Marketplace operatorCommission — stays in the operator’s account
KhaimePlatform fee — taken upfront as part of the charge
No manual disbursement step is needed. The split happens in real time when the payment clears.

​
Checking readiness before charging

After calling this endpoint, poll Get Merchant Details and check payout.charge_eligible: 
{
  "payout": {
    "status": "active",
    "payout_ready": true,
    "charge_eligible": true
  }
}
charge_eligibleMeaning
trueReady — you can charge this merchant via sub_merchant_id
falseNot ready — payout setup is incomplete or Stripe onboarding is pending

​
Next Steps

After confirming charge_eligible: true:
  • For NGN/African merchants: charge_eligible is true immediately after this endpoint returns payout_ready: true. No further action needed.
  • For international merchants: charge_eligible becomes true only after the merchant completes Stripe onboarding via the onboarding_url returned in the response. Poll Get Merchant Details until charge_eligible flips to true.
Once ready: