> ## 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 details for an existing sub-merchant.

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

<Note>
  This endpoint is for updating existing payout configurations. To set up payout for the first time, use [POST Setup Merchant Payout](/api-reference/marketplace/setup-payout).
</Note>

## 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

<ParamField path="merchantId" type="string" required>
  The ID of the sub-merchant to update payout for.
</ParamField>

## Request Body

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

Update any of the bank account details. All provided fields are stored in KycSubmissions:

<ParamField body="settlement_bank" type="string">
  New bank name for the settlement bank. Must match a name from [Get Supported Payout Banks](/api-reference/marketplace/get-payout-banks).
</ParamField>

<ParamField body="account_number" type="string">
  New bank account number. Stored as `KycSubmissions.bank_account_number`.
</ParamField>

<ParamField body="account_name" type="string">
  New account holder name. Stored as `KycSubmissions.bank_account_name`.
</ParamField>

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

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

<ParamField body="callback_url" type="string" required>
  The URL where the merchant will be redirected after completing (or exiting) Stripe's onboarding flow. **Required for non-African countries.**
</ParamField>

<Warning>
  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.
</Warning>

## Response

### African Countries

Bank details are updated immediately in KycSubmissions:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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/..."
  }
}
```

<Info>
  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.
</Info>

## 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`   |

<Info>
  **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`.
</Info>

## 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                      |

<RequestExample>
  ```bash cURL (Update Bank Details - Nigeria) theme={null}
  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"
    }'
  ```

  ```bash cURL (Re-initiate Onboarding - US) theme={null}
  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"
    }'
  ```
</RequestExample>

## Related

* [Setup Payout](/api-reference/marketplace/setup-payout) — initial payout configuration
* [Get KYC Status](/api-reference/marketplace/get-kyc-status) — check current KYC and bank details
* [Get Payout Banks](/api-reference/marketplace/get-payout-banks) — list of valid bank names