Fawry Pay

We recommend reading our Direct Charge overview post first, to fully grasp the basics of the direct charge before you proceed.

Fawry payments are agency-based payments that are initiated by users online to be completed offline. With this payment method, customers can make seamless payments over the counter to a wide range of connected agent networks.

This method supports payment in Egypt and Morroco. Kindly contact at hi@flutterwavego.com to request this feature on your account.

Pre-requisites

Before starting your integration, you should ensure that your Flutterwave account is live. We would communicate any additional requirements for this payment method via email.

Payment flow

Users making payments with this method receive a reference from Fawry on their mobile to complete the transaction with an agent or at an ATM.

To successfully collect payments from your customers via Fawry pay, You are to complete these steps:

  1. Initiate the charge.
  2. Make the over the counter (OTC) payment
  3. Verify the payment

Initiating the charge

To initiate the payment for the customer, pass their email address, the transaction amount, currency and reference (see here for optional information to include in your request).

Here is a sample request include the required parameters and some optional ones.

{
    "tx_ref": "fawrySample1",
    "amount": "10",
    "email": "user@flw.com",
    "currency": "EGP",
    "phone_number": "09012345678",
    "redirect_url": "https://www.flutterwave.com",
    "meta": {
        "name": "Cornelius",
        "tools": "Postman"
    }
}

On making a successful request, you should get 200 response.

{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "id": 3907288,
        "tx_ref": "fawrySample1",
        "order_ref": "URF_FAWRY_1667168731662_2318135",
        "flw_ref": "9200967586",
        "device_fingerprint": "N/A",
        "amount": 10,
        "charged_amount": 10,
        "app_fee": 0.23,
        "merchant_fee": 0,
        "processor_response": "Request is pending",
        "currency": "EGP",
        "narration": "Flutterwave Developers",
        "status": "pending",
        "auth_url": "N/A",
        "payment_type": "fawry_pay",
        "fraud_status": "ok",
        "charge_type": "normal",
        "created_at": "2022-10-30T22:25:31.000Z",
        "account_id": 20937,
        "customer": {
            "id": 1869436,
            "phone_number": "09012345678",
            "name": "Anonymous customer",
            "email": "user@flw.com",
            "created_at": "2022-10-30T22:25:31.000Z"
        }
    },
    "meta": {
        "authorization": {
            "mode": "fawry_pay",
            "instruction": "Please make payment with the flw_ref returned in the response which should be the same as the reference sent via SMS"
        }
    }
}

{
    "status": "error",
    "message": "Merchant is not enabled for Fawry Pay collections.",
    "data": null
}

Making payment

After initiating the payment successfully, The customer receives a notification from Fawry with a payment reference that is used to identify the transaction (see sample notification below).

The customer then proceeds to complete this payment with an agent. Once the funds are received, Flutterwave sends you a webhook with the final status of the transaction.

{
   "event":"charge.completed",
   "data":{
      "id":3907467,
      "tx_ref":"fawrySample2",
      "flw_ref":"9200692338",
      "device_fingerprint":"N/A",
      "amount":10,
      "currency":"EGP",
      "charged_amount":10,
      "app_fee":0.23,
      "merchant_fee":0,
      "processor_response":"Fawry charge completion successfully mocked",
      "auth_model":"CASH",
      "ip":"52.209.154.143",
      "narration":"Flutterwave Developers",
      "status":"successful",
      "payment_type":"fawry_pay",
      "created_at":"2022-10-31T00:09:06.000Z",
      "account_id":20937,
      "customer":{
         "id":1869436,
         "name":"Anonymous customer",
         "phone_number":"09012345678",
         "email":"user@flw.com",
         "created_at":"2022-10-30T22:25:31.000Z"
      }
   },
   "meta_data":{},
   "event.type":"FAWRY_PAY_TRANSACTION"
}

Verifying the transaction

Once the transaction is completed, you must verify the status and amount of the transaction before giving value. This should be done for both transaction polling and webhook streaming.

Next steps

Congrats 🎉 on your successful integration. You can learn more about Fawry here.

Loading...