> For the complete documentation index, see [llms.txt](https://startbutton.gitbook.io/startbutton-product-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://startbutton.gitbook.io/startbutton-product-api/payouts/transfer-overview.md).

# Transfer — Overview

The transfer feature helps you send funds from your wallets to your customers/vendors in their local currencies.

#### Supported Payout Currencies & Channels

| Currency            | Payout Channel                 |
| ------------------- | ------------------------------ |
| NGN - Nigeria       | Bank Transfer                  |
| GHS - Ghana         | Bank Transfer and Mobile Money |
| ZAR - South Africa  | Bank Transfer                  |
| KES - Kenya         | Mobile Money and Bank Transfer |
| UGX - Uganda        | Mobile Money                   |
| RWF - Rwanda        | Mobile Money                   |
| TZS - Tanzania      | Mobile Money                   |
| XOF - Côte d'Ivoire | Mobile Money                   |
| ZMW - Zambia        | Bank Transfer and Mobile Money |

For more payout details, see [Available Currencies](/startbutton-product-api/reference/available-currencies.md).

#### Initiate Transfer

| Header        | Value                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| Authorization | `Bearer SECRET_KEY` (see [Authentication](/startbutton-product-api/getting-started/authentication.md)) |
| Content-Type  | `application/json`                                                                                     |

See [Authentication](/startbutton-product-api/getting-started/authentication.md) before making requests.

**Endpoint:** `POST {{baseurl}}/transaction/transfer`

**Sample requests** (tabbed by currency/channel):

To simulate successful and failed scenarios, find [Test Numbers for Transfers](/startbutton-product-api/testing/test-numbers-for-transfers.md).

NGN Bank transfer:

```json
{
    "amount": 2000,
    "currency": "NGN",
    "country": "Nigeria",
    "bankCode": "057",
    "accountNumber": "1951772514216",
    "reference": "78teguy3rqxxxxx"
}
```

GHS Bank transfer:

```json
{
    "amount": 1000,
    "currency": "GHS",
    "country": "Ghana",
    "bankCode": "240100",
    "accountNumber": "1056772514218",
    "reference": "78teguy3rqxxxxx"
}
```

ZAR Bank transfer:

```json
{
    "amount": 100,
    "currency": "ZAR",
    "country": "South Africa",
    "bankCode": "250655",
    "accountNumber": "630xxxxxxxx",
    "accountName": "John Doe"
}
```

GHS Mobile money:

```json
{
    "amount": 580000,
    "currency": "GHS",
    "MNO": "MTN",
    "msisdn": "0551234987",
    "country": "Ghana",
    "reference": "80qetie3rqxxxxx"
}
```

KES Bank transfer:

```json
{
    "amount": 1000,
    "currency": "KES",
    "country": "Kenya",
    "bankCode": "57",
    "accountNumber": "032xxxxxx",
    "accountName": "John Doe"
}
```

KES Mobile money:

```json
{
    "amount": 120000,
    "currency": "KES",
    "MNO": "MPESA",
    "msisdn": "071000000",
    "country": "Kenya"
}
```

UGX Mobile money:

```json
{
    "amount": 580000,
    "currency": "UGX",
    "MNO": "MTN",
    "msisdn": "+256101010111",
    "country": "Uganda"
}
```

RWF Mobile money:

```json
{
    "amount": 1000,
    "currency": "RWF",
    "country": "Rwanda",
    "MNO": "MTN",
    "msisdn": "123123123"
}
```

ZMW Mobile money:

```json
{
    "amount": 2700,
    "currency": "ZMW",
    "MNO": "zm_airtel",
    "msisdn": "260970000100",
    "country": "Zambia"
}
```

XOF Mobile money:

```json
{
    "amount": 20500,
    "currency": "XOF",
    "msisdn": "+2250707000200",
    "country": "Côte d'Ivoire",
    "MNO": "ORANGE_CI",
    "recipientFirstName": "Cheid",
    "recipientLastName": "Cheid",
    "reference": "test8489273"
}
```

TZS Mobile money:

```json
{
    "amount": 100000,
    "country": "Tanzania",
    "currency": "TZS",
    "MNO": "MTN",
    "msisdn": "+255121212121"
}
```

**Note:** `bankCode`/`MNO` is dependent on the bank or mobile money operator — see [Bank List](/startbutton-product-api/payouts/bank-list.md). Account validation for ZAR transfers is currently not available; documentation will be updated once it is.

A transfer reference (`userTransactionReference`) is a unique code that enables you to track, manage, and reconcile each transfer request. It helps prevent duplicate transactions. Your reference must be 16–100 alphanumeric characters. If you don't provide one, or it doesn't conform to the format, one is generated for you automatically.

**Sample responses:**

Processing (200):

```json
{ "success": true, "message": "transfer", "data": "processing" }
```

Insufficient funds (400):

```json
{ "success": false, "message": "Insufficient funds in GHS wallet" }
```

Duplicate reference (409):

```json
{ "success": false, "message": "Duplicate transaction" }
```

Daily transaction limit (400):

```json
{ "success": false, "message": "You can only send 9xxxxxNGN more today" }
```

Resolution issue (400):

```json
{ "success": false, "message": "Could not resolve account name. Check parameters or try again." }
```

Omission in required parameter:

```json
{ "success": false, "message": "either a bankCode and accountNumber pair or MNO and msisdn pair is required for transfer" }
```

All merchants are subject to a standard daily transaction limit of ₦1,000,000 (Naira) or the equivalent of $500 in other currencies.

To transfer above this limit, contact support at <support@startbutton.africa>

#### Custom Webhook for Payout

To learn more about custom webhooks, see [Custom Webhook Per Transaction](/startbutton-product-api/collections/custom-webhook-per-transaction.md).

```json
{
    "amount": 50000,
    "currency": "NGN",
    "country": "Nigeria",
    "bankCode": "50xxx",
    "accountNumber": "200XXXXXX",
    "webhookUrl": "https://webhook.site/e9d63f59-d13d-4db7-a07d-8ecd25443b22"
}
```

#### Verify Transfer

A webhook notification is sent whenever a transfer's status changes (see [Overview & Verification](/startbutton-product-api/webhooks/overview-and-verification.md)).

You can also retrieve status directly via the [Transaction Status Query](/startbutton-product-api/webhooks/transaction-status-query.md).

#### Supported Currencies for Transfer

See Amount Limits and Settlement Timeline per currency on [Available Currencies](/startbutton-product-api/reference/available-currencies.md).