Make a Payout
curl --request POST \
--url https://sandbox.fapshi.com/payout \
--header 'Content-Type: application/json' \
--header 'apikey: <api-key>' \
--header 'apiuser: <api-key>' \
--data '
{
"amount": 101,
"phone": "<string>",
"name": "<string>",
"email": "jsmith@example.com",
"userId": "<string>",
"externalId": "<string>",
"message": "<string>"
}
'const options = {
method: 'POST',
headers: {apiuser: '<api-key>', apikey: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 101,
phone: '<string>',
name: '<string>',
email: 'jsmith@example.com',
userId: '<string>',
externalId: '<string>',
message: '<string>'
})
};
fetch('https://sandbox.fapshi.com/payout', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.fapshi.com/payout",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 101,
'phone' => '<string>',
'name' => '<string>',
'email' => 'jsmith@example.com',
'userId' => '<string>',
'externalId' => '<string>',
'message' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"apikey: <api-key>",
"apiuser: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://sandbox.fapshi.com/payout"
payload = {
"amount": 101,
"phone": "<string>",
"name": "<string>",
"email": "jsmith@example.com",
"userId": "<string>",
"externalId": "<string>",
"message": "<string>"
}
headers = {
"apiuser": "<api-key>",
"apikey": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)HttpResponse<String> response = Unirest.post("https://sandbox.fapshi.com/payout")
.header("apiuser", "<api-key>")
.header("apikey", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 101,\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"userId\": \"<string>\",\n \"externalId\": \"<string>\",\n \"message\": \"<string>\"\n}")
.asString();package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.fapshi.com/payout"
payload := strings.NewReader("{\n \"amount\": 101,\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"userId\": \"<string>\",\n \"externalId\": \"<string>\",\n \"message\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("apiuser", "<api-key>")
req.Header.Add("apikey", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"message": "<string>",
"transId": "<string>",
"dateInitiated": "2023-12-25"
}{
"message": "<string>"
}Endpoints
Make a Payout
Send money to a user’s mobile money, orange money or fapshi account via a payout-enabled service.
POST
/
payout
Make a Payout
curl --request POST \
--url https://sandbox.fapshi.com/payout \
--header 'Content-Type: application/json' \
--header 'apikey: <api-key>' \
--header 'apiuser: <api-key>' \
--data '
{
"amount": 101,
"phone": "<string>",
"name": "<string>",
"email": "jsmith@example.com",
"userId": "<string>",
"externalId": "<string>",
"message": "<string>"
}
'const options = {
method: 'POST',
headers: {apiuser: '<api-key>', apikey: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 101,
phone: '<string>',
name: '<string>',
email: 'jsmith@example.com',
userId: '<string>',
externalId: '<string>',
message: '<string>'
})
};
fetch('https://sandbox.fapshi.com/payout', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.fapshi.com/payout",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 101,
'phone' => '<string>',
'name' => '<string>',
'email' => 'jsmith@example.com',
'userId' => '<string>',
'externalId' => '<string>',
'message' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"apikey: <api-key>",
"apiuser: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://sandbox.fapshi.com/payout"
payload = {
"amount": 101,
"phone": "<string>",
"name": "<string>",
"email": "jsmith@example.com",
"userId": "<string>",
"externalId": "<string>",
"message": "<string>"
}
headers = {
"apiuser": "<api-key>",
"apikey": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)HttpResponse<String> response = Unirest.post("https://sandbox.fapshi.com/payout")
.header("apiuser", "<api-key>")
.header("apikey", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 101,\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"userId\": \"<string>\",\n \"externalId\": \"<string>\",\n \"message\": \"<string>\"\n}")
.asString();package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.fapshi.com/payout"
payload := strings.NewReader("{\n \"amount\": 101,\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"userId\": \"<string>\",\n \"externalId\": \"<string>\",\n \"message\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("apiuser", "<api-key>")
req.Header.Add("apikey", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"message": "<string>",
"transId": "<string>",
"dateInitiated": "2023-12-25"
}{
"message": "<string>"
}Endpoint
POST /payout
Send money to a user’s mobile money, orange money or fapshi account via a payout-enabled service.
After enabling payouts for a service, that service can no longer collect payments. Use separate services for collections and payouts.
Payout is disabled by default in the live environment. To activate payouts in live environment, first implement and test payouts in sandbox environment, then send an email to Developer Support at support@fapshi.com with your Live API User ONLY and mention that you want to enable payouts on your service.MAKE SURE YOU SEND THE LIVE API USER of your PAYOUT SERVICE.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| amount | Yes | integer | Amount to send (minimum 100 XAF). |
| phone | Conditional | string | Recipient phone number (e.g., 67XXXXXXX). Required when medium is not specified or not "fapshi". |
| medium | No | string | "mobile money", "orange money", or "fapshi". Auto-detected if omitted (requires phone). When set to "fapshi", email is required instead of phone. |
| name | No | string | Recipient’s name. |
| Conditional | string | Recipient’s email. Required when medium is "fapshi". Optional for payout confirmation receipt when medium is not "fapshi". | |
| userId | No | string | Your system’s user ID for payout tracking (1-100 chars; allowed: a-z, A-Z, 0-9, -, _). |
| externalId | No | string | Transaction/order ID for reconciliation (1-100 chars; allowed: a-z, A-Z, 0-9, -, _). |
| message | No | string | Description or reason for payout. |
Required Fields
- When
mediumis not specified:amountandphoneare required. - When
mediumis"fapshi":amountandemailare required.
Sandbox Testing
When testing payouts withmedium set to "fapshi" in the sandbox environment:
- Emails that always return successful transactions:
test.success@fapshi.comandmessi.champion@fapshi.com - Emails that always return failed transactions:
test.failed@fapshi.comandpenaldo.test@fapshi.com - Other emails: Transaction status will be determined in a stochastic (random) manner
Body
application/json
Amount to send (minimum 100 XAF).
Required range:
x >= 100Recipient phone number. Required when medium is not specified or not "fapshi". Not required when medium is "fapshi".
Payment medium (optional). Auto-detected if omitted (requires phone). When set to "fapshi", email is required instead of phone.
Available options:
mobile money, orange money, fapshi Recipient name (optional).
Recipient email. Required when medium is "fapshi". Optional for payout receipt when medium is not "fapshi".
User ID for payout tracking (optional).
Pattern:
^[a-zA-Z0-9\-_]{1,100}$Transaction/order ID for reconciliation (optional).
Pattern:
^[a-zA-Z0-9\-_]{1,100}$Reason for payout (optional).