---
title: "Payouts"
method: POST
path: "/api/b2b/fiat/payout"
---

# Payouts

`POST /api/b2b/fiat/payout`

## Request

- Base URL: `https://api-v2.honeycoin.app`
- URL: `https://api-v2.honeycoin.app/api/b2b/fiat/payout`
- Auth: API key in header `Authorization`

This endpoint is a universal endpoint for payouts to destinations such as mobile money wallets and bank accounts. If the account has one or more active allowlisted IP addresses, production requests must originate from an allowed IPv4 address; otherwise the API returns IP_NOT_ALLOWED.

## Request body

- object
  - `amount` integer, required
  - `currency` string
  - `country` string: ISO 3166-1 alpha-2 country code
  - `payoutMethod` object
    - `accountName` string, required: e.g Clark Kent
    - `accountNumber` union, required: Use a string to preserve leading zeroes. MoMo and Till also accept numbers and normalize them to strings; bank and Paybill accounts must be strings.
      - string
      - number
    - `code` string: Might be required depending on the currency and destination. All bank payouts require the bank code which can be retrieved from the get banks api. For mobile money payouts, some currencies require a mobile operator code which can be retrieved from the mobile money providers api.
    - `businessNumber` string: Only applies for Mpesa paybill payouts
  - `destination` string: MoMo / Bank Account
  - `externalReference` string, required: A unique ID of your liking to reconcile transactions internally.
  - `externalAccountId` string
  - `debitCurrency` string: The wallet you want to be debited from. If missing, we will default to the currency passed.
  - `debitCountry` string: Country scope of the wallet being debited. Required whenever debitCurrency is XOF, even for same-currency payouts. Optional for other debit currencies, including USD; omit when debitCurrency is absent.

## Response `200`

200

- object
  - `success` boolean
  - `message` string
  - `transactionId` string

## Other responses

- `400`: Bad request. This includes IP_NOT_ALLOWED when a production request originates outside the account's active IP allowlist.

## Changes

- **2026-11-03** `fcb58b0ef441`: 3 breaking, 1 warning, 6 info
  - added `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5` to the request body `allOf` list
  - the `debitCountry` request property's minLength was increased from `0` to `2`
  - the `payoutMethod/accountNumber` request property type changed from `string` to `string, number`
  - the `debitCountry` request property's maxLength was set to `2`
  - …6 more

[Operation history](https://skmtc.dev/honeycoin/apis/honeycoin-v3-api-official/changes/api/b2b/fiat/payout/post.md)

---

[API](https://skmtc.dev/honeycoin/apis/honeycoin-v3-api-official.md) - [All operations](https://skmtc.dev/honeycoin/apis/honeycoin-v3-api-official/llms.txt) - [OpenAPI document](https://skmtc.dev/honeycoin/apis/honeycoin-v3-api-official/revisions/fcb58b0ef441?raw)