Update Merchant Payout

Intro

Updates bank account details for a sub-merchant that already has payout configured, or issues a fresh Stripe onboarding session for international merchants who need to change their details.

Context

This is the maintenance counterpart to Setup Merchant Payout — use Setup for the first configuration, Update afterward. It’s the endpoint you reach for when a merchant changes banks, corrects an account number, or needs to redo Stripe onboarding without going through the create-account flow again.

Hows

Path parameters

string

required

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

Request body — `NG`, `GH`, `ZA`, `KE`

Provide any subset of the bank fields — at least one is required.

string

New bank name. Must match a name from Get Supported Payout Banks.

string

New bank account number.

string

New account holder name.

Request body — everywhere else

string

required

Where the merchant is redirected after completing (or exiting) a fresh round of Stripe onboarding.

callback_url is required for non-African countries — without it, the merchant has no way back to your platform after updating their Stripe details.

Response — African countries

Bank details update immediately:

{
  "success": true,
  "message": "Payout details updated successfully",
  "data": {
    "merchant_id": 1676,
    "payout_ready": true,
    "settlement_currency": "NGN",
    "country": "NG"
  }
}

This response confirms the update succeeded and returns payout_ready/settlement_currency/country — it does not echo back the new bank name or account number. Check Get Merchant Details if you need to confirm the values that were stored.

Response — everywhere else

Returns a fresh Stripe onboarding session for the merchant to update their own details:

{
  "success": true,
  "message": "To update payout details, the merchant must complete the onboarding flow again.",
  "data": {
    "merchant_id": 1676,
    "payout_ready": false,
    "settlement_currency": "USD",
    "country": "US",
    "client_secret": "accs_1234567890",
    "onboarding_url": "https://connect.khaime.com/setup/..."
  }
}

For international merchants, bank accounts and identity details are managed through Stripe’s hosted flow — this endpoint can only hand you a new session for the merchant to update their own information there.

Error cases

Status	Error	Fix
`400`	`At least one field must be provided: settlement_bank, account_number, or account_name`	Include at least one field to update
`400`	`callback_url is required for non-African countries...`	Include a `callback_url` for the Stripe redirect
`400`	`Payout has not been set up for this merchant. Use POST to set up first.`	Use Setup Merchant Payout first
`400`	`No payout account found. Use POST to set up first.`	Use Setup Merchant Payout first
`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
`404`	`Merchant portfolio not found`	The merchant account doesn’t exist

curl -X PATCH https://api.khaime.com/api/v1/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/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"
  }'

Whys

PATCH semantics for African bank details, session-reissue for Stripe. Local bank details are just data Khaime stores directly, so updating them is a straightforward partial update. Stripe-managed accounts don’t expose a “just change the bank account” API in the same way — the merchant has to go back through Stripe’s flow — so the endpoint’s only lever there is generating a new onboarding session. Requires payout to already exist. Update assumes there’s something to update. Splitting first-time setup (Setup Merchant Payout) from maintenance keeps each endpoint’s validation focused — setup can assume nothing exists yet, update can assume something does.

Why nots

Not for first-time setup. If payout hasn’t been configured yet, this returns an error pointing you at Setup Merchant Payout.
Can’t change country. There’s no field to move a merchant from a local bank rail to Stripe Connect (or vice versa) — that requires a fresh setup and, likely, a conversation with support.
Doesn’t re-verify KYC. Changing bank details doesn’t reset or re-trigger identity verification — if the merchant’s KYC was already approved, it stays approved.
Doesn’t return the values you just set. For African merchants, confirm the new bank details landed correctly via Get Merchant Details rather than trusting the update response body.

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

API Reference

Account

Products & Pricing

Payments

Integration Guides

Commerce API

Subscriptions

Marketplace

Intro

Context

Hows

Path parameters

Request body — `NG`, `GH`, `ZA`, `KE`

Request body — everywhere else

Response — African countries

Response — everywhere else

Error cases

Whys

Why nots

​Intro

​Context

​Hows

​Path parameters

​Request body — NG, GH, ZA, KE

​Request body — everywhere else

​Response — African countries

​Response — everywhere else

​Error cases

​Whys

​Why nots

​Related

Intro

Context

Hows

Path parameters

Request body — `NG`, `GH`, `ZA`, `KE`

Request body — everywhere else

Response — African countries

Response — everywhere else

Error cases

Whys

Why nots

Related