Skip to main content
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>"
}
'
{
  "message": "<string>",
  "transId": "<string>",
  "dateInitiated": "2023-12-25"
}

Documentation Index

Fetch the complete documentation index at: https://docs.fapshi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

NameRequiredTypeDescription
amountYesintegerAmount to send (minimum 100 XAF).
phoneConditionalstringRecipient phone number (e.g., 67XXXXXXX). Required when medium is not specified or not "fapshi".
mediumNostring"mobile money", "orange money", or "fapshi". Auto-detected if omitted (requires phone). When set to "fapshi", email is required instead of phone.
nameNostringRecipient’s name.
emailConditionalstringRecipient’s email. Required when medium is "fapshi". Optional for payout confirmation receipt when medium is not "fapshi".
userIdNostringYour system’s user ID for payout tracking (1-100 chars; allowed: a-z, A-Z, 0-9, -, _).
externalIdNostringTransaction/order ID for reconciliation (1-100 chars; allowed: a-z, A-Z, 0-9, -, _).
messageNostringDescription or reason for payout.

​
Required Fields

  • When medium is not specified: amount and phone are required.
  • When medium is "fapshi": amount and email are required.

​
Sandbox Testing

When testing payouts with medium set to "fapshi" in the sandbox environment:
  • Emails that always return successful transactions: test.success@fapshi.com and messi.champion@fapshi.com
  • Emails that always return failed transactions: test.failed@fapshi.com and penaldo.test@fapshi.com
  • Other emails: Transaction status will be determined in a stochastic (random) manner

Authorizations

​
apiuser
string
header
required
​
apikey
string
header
required

Body

application/json
​
amount
integer
required

Amount to send (minimum 100 XAF).

Required range: x >= 100
​
phone
string

Recipient phone number. Required when medium is not specified or not "fapshi". Not required when medium is "fapshi".

​
medium
enum<string>

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
​
name
string

Recipient name (optional).

​
email
string<email>

Recipient email. Required when medium is "fapshi". Optional for payout receipt when medium is not "fapshi".

​
userId
string

User ID for payout tracking (optional).

Pattern: ^[a-zA-Z0-9\-_]{1,100}$
​
externalId
string

Transaction/order ID for reconciliation (optional).

Pattern: ^[a-zA-Z0-9\-_]{1,100}$
​
message
string

Reason for payout (optional).

Response

Accepted

​
message
string

Success message

​
transId
string

Transaction ID for the payment.

​
dateInitiated
string<date>

Date when the payment was initiated.