Example Requests

Here are examples of the request bodies for both payout methods:

Mobile Money Payout

{  
  "amount": 100,  
  "first_name": "John",  
  "last_name": "Doe",  
  "merchant_reference": "merchant-ref-momo-payout-1234",  
  "msisdn": "+254712345678",  
  "email": "[email protected]",
  "narration": "Payout description",
  "payout_method": "MOBILE_MONEY",  
  "callback_url": "https://callback_url",  
  "payout_option_id": "ke_momo_safaricom_mpesa_c",  
  "payment_reference": "1234"
}

Fawry Voucher Payout

{
  "amount": "10",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "narration": "b853affd-71d4-4ace-978f-02453740b7e2",
  "merchant_reference": "b853affd-71d4-4ace-978f-02453740b7e2",
  "msisdn": "+201112345678",
  "callback_url": "http://localhost/callback",
  "payout_option_id": "eg_fawry_voucher",
  "id_number": {
    "type": "NATIONAL_ID",
    "value": "76554437123456"
  }
}

📘

Required fields

All fields in the JSON above are required. For further details check the payout options API.

After the voucher is generated, the customer will receive an SMS containing a reference number. This reference must be presented at any Fawry Plus location to withdraw the money. Please note that a valid National ID, matching the one provided in the initial request, is required and will be verified by the agent handling the withdrawal.

Bank Payout

{  
  "amount": 100,  
  "first_name": "John",  
  "last_name": "Doe",  
  "merchant_reference": "merchant-ref-bank-payout-ke-1247",  
  "msisdn": "+254712345678",  
  "email": "[email protected]",
  "narration": "Payout description",  
  "payout_method": "BANK",  
  "callback_url": "https://callback_url",  
  "payout_option_id": "ke_bank_c",
  "payment_reference": "merchant-ref-1234",
  "bank": {
    "name": "KCB",  
    "code": "1",  
    "account_number": "1234",  
    "account_owner": "John Doe"  
  }
}

📘

Email Address

the email address is optional except if the field is indicated as required in the payment option. Please refer to this page for more details: Payout Options

Balance Account

Upon initiating a payout request, our platform calculates fees and retrieves your account balance and the total pending transaction amount. If the sum of the fees, transaction amount, and total pending transactions exceeds your account balance, the payout request will be declined. You are responsible for ensuring that your account balance is sufficient before initiating a payout request.

Fees

When a payout request is successful, calculated fees will be subtracted from your balance account. Fees are configured during the payout option activation. If the fees are fixed, for example, 1.0 USD, they will be converted into the local currency of the payout recipient before the balance update.

We recommend reviewing the fee structure for each payout option before going into production. This will help ensure that you understand the costs associated with each payout option and can make informed decisions about which options to offer to your customers.

If you have any questions about fees, don't hesitate to contact our support team for assistance.