Transfer

The transfer feature helps you send funds to your customers/vendors in their local currency (NGN, GHS, ZAR, KES, UGX, RWF, TZS, and ZMW).

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
UGX- Uganda	Mobile Money
RWF- Rwanda	Mobile Money
TZS- Tanzania	Mobile Money
XOF- Côte d'Ivoire	Mobile Money
ZMW- Zambia	Mobile Money

For more Payout details check here:

Initiate transfer

Authorization	Set to Bearer SECRET_KEY
Content-Type	Set value to application/json

The secret key can be gotten from the 'Settings' page on your Startbutton dashboard.

Post a request to the URL below, where the base URL is determined by the environment you are in.

BaseUrls

PROD : https://api.startbutton.tech

DEV/ Staging: https://api.startbutton.builditdigital.co

Endpoint

POST {{baseurl}}/transaction/transfer

Here are sample requests below.

NGN Bank transfer (required parameters)

{
    "amount": 2000,
    "currency": "NGN",
    "country": "Nigeria",
    "bankCode": "057",
    "accountNumber": "1951772514216"
}

Bank transfer (optional parameters included)

{
    "amount": 200000,
    "currency": "NGN",
    "bankCode": "058",
    "accountNumber": "003xxxxxxx",
    "country": "Nigeria",
    "reference": "78teguy3rqxxxxx"
}

Bank transfer (ZAR)

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

GHS Mobile money (required parameters)

{
    "amount": 580000,
    "currency": "GHS",
    "MNO": "MTN",
    "msisdn": "0551234987",
    "country": "Ghana"
}

GHS Mobile money (optional parameters included)

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

KES Mobile money (required parameters)

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

UGX Mobile money (required parameters)

{
    "amount": 580000,
    "currency": "UGX",
    "MNO": "MTN",
    "msisdn": "[phone]",
    "country": "Uganda"
}

RWF (Mobile Money)

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

Required Param for ZMW (Mobile Money)

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

XOF (Mobile Money)

 {
    "amount": 20500,
    "currency": "XOF",
    "msisdn": "[phone]",
    "country": "Côte d'Ivoire",
    "recipientFirstName": "Cheid", // optional
    "recipientLastName": "Cheid", // optional
    "reference": "test8489273" // optional
}  

Note: bankCode/MNO is dependent on the or mobile money operator, this can be gotten from our bank list

Account validation for ZAR transfers is currently not available. Interested merchants will be notified and the documentation updated once this is available.

A transfer reference is a unique code that enables you to track, manage, and reconcile each transfer request in your integration. It helps prevent duplicate transactions. Ensure your reference has at least 16 alphanumeric characters and a maximum of 100 characters.

To benefit from this transfer reference system, you should generate and include it for every request. However, if you do not provide a reference or the provided reference does not conform to the required format, a reference would be automatically generated on your behalf in place of the provided one.

Here are sample responses below.

Processing

Sample response 200

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

Insufficient funds

Sample response 400

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

Duplicate reference

Sample response 409

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

Daily transaction limit

Sample response 400

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

Resolution Issue

Sample response 400

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

Omission in required parameter

{
    "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 N1 million (Naira) and an equivalent of $500 in other currencies. To transfer above this, please contact our support team via email ([e-mail])

Transaction statuses

Currently we have 6 transaction statuses namely;

Status	Description	Conclusive?
Initiated	The transaction has been initiated for payment	No
Pending	Transaction has been picked up for processing	No
Processing	The transfer has been picked up by our payment partner and awaiting confirmation	No
Successful	The transfer has been acknowledged and processed successfully.	Yes
Failed	Transfer could not be processed.	Yes
Reversed	The transfer was successful but we got reversed by the receiver's bank or operator. This usually signifies that the customer's bank is currently unable to accept the funds. In such cases, the transfer amount is refunded. The merchant has the option to attempt the transfer again at a later time.	Yes

Verify transfer

Stay up to date with the status of your transaction. Once the status of a transaction changes, a webhook notification is sent. You can also retrieve the status of your transfer by calling the transaction status endpoint.

Supported Currencies for Transfer

Check out the Amount Limits and Settlement Timeline for each currency here.