curl -X PATCH https://api.khaime.com/api/v1/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/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"
}'
Marketplace
Update Merchant Payout
Update payout details for an existing sub-merchant.
PATCH
/
merchants
/
{merchantId}
/
payout
curl -X PATCH https://api.khaime.com/api/v1/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/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"
}'
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/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/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.
Related
- Setup Payout — initial payout configuration
- Get KYC Status — check current KYC status
- Get Payout Banks — list of valid bank names