Skip to main content
PATCH
/
marketplace
/
merchants
/
{merchantId}
/
payout
curl -X PATCH 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 '{
    "settlement_bank": "GTBank",
    "account_number": "9876543210",
    "account_name": "Jane 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.

​
Update Merchant Payout

Update payout settings for a sub-merchant that already has payout configured. Use this to change bank account details or re-initiate onboarding for international merchants.
This endpoint is for updating existing payout configurations. To set up payout for the first time, use POST Setup Merchant Payout.

​
Data Storage

Updated bank details are stored in the KycSubmissions table, which is the single source of truth for all KYC and payout information.

​
Path Parameters

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

​
Request Body

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

Update any of the bank account details. All provided fields are stored in KycSubmissions:
​
settlement_bank
string
New bank name for the settlement bank. Must match a name from Get Supported Payout Banks.
​
account_number
string
New bank account number. Stored as KycSubmissions.bank_account_number.
​
account_name
string
New account holder name. Stored as KycSubmissions.bank_account_name.

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

No request body needed. The endpoint returns onboarding credentials for the merchant to update their details directly via Stripe.

​
Response

​
African Countries

Bank details are updated immediately in KycSubmissions: 
{
  "success": true,
  "message": "Payout details updated successfully",
  "data": {
    "merchant_id": 1676,
    "bank_name": "GTBank",
    "bank_account_number": "9876543210",
    "bank_account_name": "Jane Doe",
    "baseline_currency": "NGN",
    "country": "NG"
  }
}

​
Other Countries

Returns onboarding credentials for the merchant to update their own details via Stripe: 
{
  "success": true,
  "message": "To update payout details, the merchant must complete the onboarding flow again.",
  "data": {
    "merchant_id": 1676,
    "baseline_currency": "USD",
    "country": "US",
    "client_secret": "accs_1234567890",
    "onboarding_url": "https://connect.stripe.com/setup/..."
  }
}
For international countries, payout details (bank accounts, identity verification) are managed through Stripe’s hosted onboarding flow. The merchant must complete this flow to update their information.

​
Where Data is Stored

Updated FieldStorage Location
settlement_bankKycSubmissions.bank_name
account_numberKycSubmissions.bank_account_number
account_nameKycSubmissions.bank_account_name
Important: Legacy fields in Educatorportfolio (like educator_bank_name, educator_bank_account_number) are deprecated and no longer used. All bank details are stored in KycSubmissions.

​
Error Codes

StatusErrorFix
400At least one field must be providedInclude at least one field to update
400Payout has not been set up for this merchantUse POST to set up payout first
400No payout account foundUse POST to set up payout first
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
404Merchant portfolio not foundThe merchant account doesn’t exist
curl -X PATCH 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 '{
    "settlement_bank": "GTBank",
    "account_number": "9876543210",
    "account_name": "Jane Doe"
  }'