PayoutsRecipient Types

Mobile Wallet

Send payouts to mobile money wallets

Use the Payouts API to send funds to mobile money wallets (MoMo). Set paymentMethodId to "mobilemoney" and provide a recipient object with type: "mobile_money".

Request Shape

Set paymentMethodId to "mobilemoney" and provide recipient with the following structure:

FieldRequiredDescription
typeYesMust be "mobile_money"
phoneNumberYesMobile money MSISDN in international format.
countryYes3-letter ISO country code (e.g., KEN, CIV, SEN).
operatorYesMobile money operator identifier (e.g., mpesa, mtn, orange, airtel, moov, opay, wave).
nameNoFull name of the recipient (optional).

Top-level required fields for every payout:

  • Required: merchantId, merchantReference, destinationValue (with minorAmount and currency), paymentMethodId ("mobilemoney"), paymentLocation, recipient
  • Optional: sender, attributes

Example Request

1{
2  "merchantId": "your-merchant-id",
3  "merchantReference": "PAYOUT-2024-002",
4  "destinationValue": {
5    "minorAmount": 500000,
6    "currency": "KES"
7  },
8  "paymentMethodId": "mobilemoney",
9  "paymentLocation": "KEN",
10  "recipient": {
11    "type": "mobile_money",
12    "phoneNumber": "254712345678",
13    "country": "KEN",
14    "operator": "mpesa",
15    "name": "Jane Smith"
16  },
17  "attributes": {}
18}

Note: minorAmount: 500000 = 5,000.00 KES (multiply major units by 100 to get minor units).

Required vs Optional Summary

  • Required for recipient (mobile_money): type ("mobile_money"), phoneNumber, country, operator
  • Optional for recipient: name
  • Required at request level: merchantId, merchantReference, destinationValue, paymentMethodId, paymentLocation, recipient
  • Optional at request level: sender, attributes

Operator and Currency

Operator choice depends on the destination currency and country:

CurrencyTypical operatorsNotes
KES (Kenya)mpesa (M-Pesa), airtelUse mpesa for M-Pesa.
GHS (Ghana)mtnUse the operator the recipient is registered with.
TZS (Tanzania)mtn, airtelUse the operator the recipient is registered with.
UGX (Uganda)mtnUse the operator the recipient is registered with.
EGP (Egypt)fawryUse fawry for Fawry wallets.
NGN (Nigeria)opayOPay wallet payouts.
XOF / XAF (Francophone Africa)mtn, orange, airtel, moov, waveMultiple operators; use the one the recipient is registered with.
Other supportedAs per productSee Supported Destinations.

Use the operator enum value that matches the recipient’s wallet (e.g. M-Pesa in Kenya → mpesa). Valid operator values: airtel, airteltigo, celtiis, fawry, free, halotel, moov, mpesa, mtn, opay, orange, tigo, vodacom, wave, zamtel.

Amount Format: Amounts are specified in minor units (integer). For example, minorAmount: 500000 = 5,000.00 KES. See Single Payouts for details.

Phone Number Format

Phone numbers are automatically normalized to international format. You can provide numbers in:

  • Local format: 0723993187 (Kenya) → normalized to 254723993187
  • International format: +254723993187 or 254723993187 → normalized to 254723993187

Mobile Number Verification

Before initiating a payout, you can verify that a mobile number is valid and registered with the mobile money provider using the Mobile Number Verification API. This helps:

  • Reduce payout failures due to invalid or unregistered numbers
  • Display the account holder’s name for confirmation before disbursement
  • Catch errors early in the disbursement process

The verification API is currently available for M-Pesa in Kenya. Contact CrissCross support for availability in other markets.

Where Mobile Wallet Is Supported

Not every currency supports mobile wallet payouts. See Supported Destinations for a table of currencies, countries, and supported rails.

Next Steps