Skip to navigation
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, sender (with fullName, identity, identityNumber)
  • Optional: attributes

Example Request

{
  "merchantId": "your-merchant-id",
  "merchantReference": "PAYOUT-2024-002",
  "destinationValue": {
    "minorAmount": 500000,
    "currency": "KES"
  },
  "paymentMethodId": "mobilemoney",
  "paymentLocation": "KEN",
  "recipient": {
    "type": "mobile_money",
    "phoneNumber": "254712345678",
    "country": "KEN",
    "operator": "mpesa",
    "name": "Jane Smith"
  },
  "sender": {
    "fullName": "Jane Smith",
    "phoneNumber": "27821234567",
    "nationality": "ZAF",
    "identity": "passport",
    "identityNumber": "A12345678",
    "dateOfBirth": "1990-01-15",
    "purposeOfFunds": "salary",
    "sourceOfFunds": "business income",
    "relationship": "employer"
  },
  "attributes": {}
}

Note: minorAmount: 500000 = 5,000.00 KES (KES has 2 decimal places).

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, sender (with fullName, identity, identityNumber)
  • Optional at request level: 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. Additional sender fields required — see Kenya.
GHS (Ghana)mtn, telecel, airteltigoUse 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.
ETB (Ethiopia)telebirr, mpesa, cbebirr, yayampesa with country: "ETH" is Safaricom Ethiopia. ebirr and awashbirr cannot receive payouts.
NGN (Nigeria)opayOPay wallet payouts.
XOF / XAF (Francophone Africa)mtn, orange, airtel, moov, wave, togocellMultiple operators; use the one the recipient is registered with. Cameroon and Togo T-Money require additional sender fields — see Central Africa and West Africa.
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, cbebirr, celtiis, fawry, free, halotel, moov, mpesa, mtn, opay, orange, telebirr, telecel, tigo, togocell, vodacom, wave, yaya, zamtel.

Amount Format: Amounts are specified in minor units (integer), per the currency’s ISO 4217 exponent — for example, minorAmount: 500000 = 5,000.00 KES, while zero-decimal currencies like XOF and XAF need no conversion. See Single Payouts for details.

Phone Number Format

Submit the beneficiary number in canonical E.164 form with the destination country as an ISO 3166-1 alpha-3 code.

"recipient": {
  "type": "mobile_money",
  "phoneNumber": "+254721755042",
  "country": "KEN",
  "operator": "mpesa"
}

CrissCross normalises local formats using the supplied country, so 0723993187 with KEN also resolves to +254723993187. Normalise before submission regardless: the leading zero is a trunk prefix in most markets but forms part of the national number in Côte d’Ivoire, Benin, Gabon, and Burkina Faso, and an incorrectly normalised number fails at the operator rather than at the API.

See Mobile Number Format for the full contract — accepted input formats, the trunk-zero exception, per-country calling codes, and the format rules enforced for Kenya and Ghana.

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