---
updatedAt: 2026-09-23T02:20:38.000Z
agentTools:
  projectIndex: https://docs.kyshi.co/llms.txt
---

# Create Beneficiary

Create or reuse a payout beneficiary.

Create a payout beneficiary. If a matching beneficiary already exists for the business, account number, bank, integration, and mode, Kyshi returns the existing record.

```Text Header
-H "x-api-key: your_secret_key"
```

```Text Request
POST {{host}}/v1/transfer/beneficiaries
```

# Request Body

| Field         | Data Type | Required | Description                                                                                                                                  |
| :------------ | :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| accountName   | string    | Yes      | Beneficiary account name.                                                                                                                    |
| accountNumber | string    | Yes      | Beneficiary bank account number, or mobile money phone number for mobile money payouts.                                                      |
| bankName      | string    | Yes      | Beneficiary bank name, or mobile money provider name for mobile money payouts.                                                               |
| bankCode      | string    | Yes      | Beneficiary bank code. For XOF mobile money payouts, use the mobile money provider code such as `MTN_MOMO_CIV`, `ORANGE_CIV`, or `WAVE_CIV`. |
| currency      | string    | Yes      | Payout currency. Supported payout currencies include `NGN`, `GHS`, `KES`, and `XOF`, depending on what is enabled for your business.         |
| description   | string    | No       | Description for the beneficiary.                                                                                                             |
| bvn           | string    | No       | Beneficiary BVN, when required.                                                                                                              |
| nameEnqRef    | string    | No       | Name enquiry/session reference returned by name enquiry, when available.                                                                     |

```json Request
{
  "accountName": "FEMI ZACK",
  "accountNumber": "0123456789",
  "bankName": "Access Bank",
  "bankCode": "000014",
  "currency": "NGN",
  "description": "Supplier payout",
  "nameEnqRef": "SESSION_123456789"
}
```

```json Response
{
  "status": true,
  "message": "Success",
  "code": 201,
  "data": {
    "id": "8495ec4e-ce21-405f-b0cf-982702881f4d",
    "accountName": "FEMI ZACK",
    "accountNumber": "0123456789",
    "bankName": "Access Bank",
    "bankCode": "000014",
    "bvn": "",
    "providerId": "SESSION_123456789",
    "description": "Supplier payout",
    "isActive": true,
    "mode": "live",
    "createdAt": "2026-05-20T10:15:00.000Z",
    "updatedAt": "2026-05-20T10:15:00.000Z"
  }
}
```

# XOF Mobile Money Beneficiary

For XOF payouts, create the beneficiary with the recipient's mobile money phone number as `accountNumber` and the mobile money provider as both `bankName` and `bankCode`.

```json Request
{
  "accountName": "Jean Kouadio",
  "accountNumber": "2250700000000",
  "bankName": "ORANGE_CIV",
  "bankCode": "ORANGE_CIV",
  "currency": "XOF",
  "description": "Customer mobile money wallet"
}
```

Supported Côte d'Ivoire mobile money provider codes include:

| Provider         | `bankCode`     |
| :--------------- | :------------- |
| MTN Mobile Money | `MTN_MOMO_CIV` |
| Orange Money     | `ORANGE_CIV`   |
| Wave             | `WAVE_CIV`     |