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"
  }'

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 '{
    "callback_url": "https://yourplatform.com/merchants/1676/payout-complete"
  }'

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"
  }'

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 '{
    "callback_url": "https://yourplatform.com/merchants/1676/payout-complete"
  }'

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

For international merchants, you must provide a callback URL for the Stripe onboarding redirect:

callback_url

string

required

The URL where the merchant will be redirected after completing (or exiting) Stripe’s onboarding flow. Required for non-African countries.

The callback_url is required for non-African countries. Without it, the merchant has no way to return to your platform after updating their Stripe onboarding details.

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 Field	Storage Location
`settlement_bank`	`KycSubmissions.bank_name`
`account_number`	`KycSubmissions.bank_account_number`
`account_name`	`KycSubmissions.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

Status	Error	Fix
`400`	`At least one field must be provided`	Include at least one field to update
`400`	`callback_url is required for non-African countries`	Include a `callback_url` for Stripe onboarding redirect
`400`	`Payout has not been set up for this merchant`	Use POST to set up payout first
`400`	`No payout account found`	Use POST to set up payout first
`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
`404`	`Merchant portfolio not found`	The 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"
  }'

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 '{
    "callback_url": "https://yourplatform.com/merchants/1676/payout-complete"
  }'

Setup Payout — initial payout configuration
Get KYC Status — check current KYC and bank details
Get Payout Banks — list of valid bank names

Setup Merchant Payout Initiate Merchant Payout

API Reference

Account

Products & Pricing

Payments

Subscriptions

Marketplace

B2B Commerce

Update Merchant Payout

Update Merchant Payout

Data Storage

Path Parameters

Request Body

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

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

Response

African Countries

Other Countries

Where Data is Stored

Error Codes

​Update Merchant Payout

​Data Storage

​Path Parameters

​Request Body

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

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

​Response

​African Countries

​Other Countries

​Where Data is Stored

​Error Codes

​Related

Update Merchant Payout

Data Storage

Path Parameters

Request Body

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

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

Response

African Countries

Other Countries

Where Data is Stored

Error Codes

Related