Update Merchant Payout

Update payout details for an existing sub-merchant.

PATCH /marketplace/merchants/{merchantId}/payout

cURL (Update Bank Details - Nigeria)

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

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 (Update Bank Details - Nigeria)

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

Related

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