Mobile Money

Mobile Money allows merchants to send payouts directly to a recipient's mobile money account in supported African markets.

All supported countries use the same Submit a payout API and request structure. The destination country, arrival currency, transaction limits, and amount precision vary by market.

Endpoint

POST https://sandbox.transfersmile.com/api/payout

Use the authentication headers described in the parent Submit a payout documentation.

Request body

Parameter	Type	Required	Constraints	Description
name	string	Yes	Must contain 5–100 characters and be a valid recipient name.	Name of the mobile money account holder.
account_type	string	Yes	Fixed value: PHONE.	Type of recipient account.
account	string	Yes	Provide the recipient's mobile phone number, including the country calling code. The value must not exceed 20 characters.	Mobile phone number registered with the recipient's Mobile Money account.
fee_bear	string	Yes	Supported values: merchant and beneficiary.	Specifies which party bears the payout fee.
amount	decimal	Yes	Must be non-negative, contain no more than two decimal places, and satisfy the limits for the selected country. Countries marked as integer-only do not accept decimal amounts.	Payout amount. The amount basis is determined by amount_type.
amount_type	string	No	Supported values: arrival_amount and source_amount. Defaults to arrival_amount when omitted.	Specifies whether amount is fixed on the beneficiary side or the merchant funding side.
source_currency	string	Yes	Merchant account currency. One of: USD, EUR, GBP, or the supported local currencies.	Currency used to fund the payout.
arrival_currency	string	Yes	Must match the currency assigned to the selected country in the supported-country table.	Currency received by the recipient.
notify_url	string	Yes	Must be a valid URL and must not exceed 255 characters.	Merchant endpoint to which payout status notifications are sent.
custom_code	string	Yes	Must not exceed 50 characters and must uniquely identify the payout request for the merchant.	Merchant payout reference.
additional_remark	string	Yes	Must contain 4–40 characters. Only letters, numbers, spaces, and underscores are accepted.	Additional information about the payout.
country	string	Yes	Must be one of the ISO 3166-1 alpha-3 country codes listed in the supported-country table.	Destination country of the payout.
method	string	Yes	Fixed value: MOBILEMONEY; maximum 16 characters.	Payout method.

Mobile Money payouts do not require a bank code. Set account_type to PHONE and provide the recipient's mobile number, including its country calling code, in account.

When amount_type is omitted, it defaults to arrival_amount. For example, amount=100.01, country=NGA, and arrival_currency=NGN means that the beneficiary receives 100.01 NGN. If source_currency is different, Pagsmile calculates the corresponding source_amount using the applicable exchange rate.

Supported countries and transaction limits

arrival_currency is fixed for each country and must match the value shown below. The minimum and maximum amounts are denominated in the arrival currency.

Country	Country code	Arrival currency	Minimum amount	Maximum amount	Amount precision
Zimbabwe	ZWE	USD	1	1,000	Up to 2 decimal places
Uganda	UGA	UGX	500	5,000,000	Integer only
Zambia	ZMB	ZMW	1	20,000	Up to 2 decimal places
Togo	TGO	XOF	200	1,500,000	Integer only
Tanzania	TZA	TZS	1,000	5,000,000	Integer only
South Sudan	SSD	SSP	100	9,999,999	Up to 2 decimal places
Sierra Leone	SLE	SLE	50	25,000	Integer only
Senegal	SEN	XOF	200	2,000,000	Integer only
Rwanda	RWA	RWD	100	2,000,000	Integer only
Nigeria	NGA	NGN	100	50,000	Up to 2 decimal places
Niger	NER	XOF	100	1,000,000	Integer only
Mozambique	MOZ	MZN	1	25,000	Integer only
Morocco	MAR	MAD	11	20,000	Up to 2 decimal places
Mali	MLI	XOF	1,000	1,500,000	Integer only
Malawi	MWI	MWK	50	500,000	Integer only
Madagascar	MDG	MGA	300	10,000,000	Integer only
Liberia	LBR	USD	1	2,000	Up to 2 decimal places
Guinea	GIN	GNF	1,000	30,000,000	Integer only
Guinea-Bissau	GNB	XOF	1	2,000,000	Integer only
Gambia	GMB	GMD	80	120,000	Integer only
Ethiopia	ETH	ETB	300	150,000	Integer only
Democratic Republic of the Congo	COD	USD	1	1,500	Integer only
Côte d'Ivoire	CIV	XOF	10,000	2,000,000	Integer only
Comoros	COM	KMF	100	1,000,000	Integer only
Burkina Faso	BFA	XOF	500	1,000,000	Integer only
Botswana	BWA	BWP	25	10,000	Up to 2 decimal places
Benin	BEN	XOF	500	1,500,000	Integer only

Request example

The following example submits a Mobile Money payout to Zimbabwe:

curl --location --request POST 'https://api.transfersmile.com/api/payout' \
--header 'Content-Type: application/json' \
--header 'AppId: YOUR_APP_ID' \
--header 'Authorization: YOUR_AUTHORIZATION_VALUE' \
--data-raw '{
  "name": "Test Recipient",
  "account_type": "PHONE",
  "account": "263********",
  "fee_bear": "merchant",
  "amount": "1.01",
  "source_currency": "USD",
  "arrival_currency": "USD",
  "notify_url": "https://merchant.example.com/payout/notify",
  "custom_code": "merchant_payout_001",
  "additional_remark": "Mobile Money payout request",
  "country": "ZWE",
  "method": "MOBILEMONEY"
}'

For another destination, update country, arrival_currency, and amount according to the supported-country table. The remaining Mobile Money fields use the same structure.

Response example

{
  "code": 200,
  "msg": "success",
  "time": 1785724575,
  "data": {
    "id": "TS2026********",
    "custom_code": "merchant_payout_001",
    "arrival_amount": "1.01",
    "arrival_currency": "USD",
    "source_amount": "1.03",
    "source_currency": "USD",
    "status": "IN_PROCESSING"
  }
}

A successful API response means that the payout request has been accepted for processing. It does not mean that the recipient has already received the funds. Use payout notifications or the payout-status query API to determine the final result.