Skip to main content

Fawry

Fawry Cash is an online payment method in Egypt that allows customers to pay for online purchases using cash at any Fawry kiosk, partner location, or via the Fawry app. It’s a secure, cash-based alternative for people who don’t use credit cards or prefer not to pay online directly.

Requirements​

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
  • Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See Direct API Guide for more info.

How it works​

  • Set up a payment request through the EBANX API and choose Fawry as the payment method.
  • Generate a unique payment reference number for the customer.
  • Clearly display the payment reference, total amount, and due date to the customer.
  • The customer visits any Fawry agent (e.g. Fawry kiosk, convenience stores, Fawry App) and provides the reference code to pay in cash or other available payment methods.

Key information​

  • Minimum transaction amount: EGP1
  • Maximum transaction amount: EGP100,000
  • Transaction expiration period: 7 days
  • Refund date range: No restrictions apply to the processing of refunds.

Instructions​

Follow the steps below.

  1. Select your environment

    Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

    https://sandbox.ebanx.com/ws/direct

  2. Create a Fawry reference

    To generate a unique Fawry reference number, prepare the required information and make a request to the /ws/direct endpoint using the parameters below.

    ParameterRequirementDescription
    operationRequiredSet to request
    integration_keyRequiredYour EBANX integration key
    payment_type_codeRequiredSet to fawry
    countryRequiredSet to eg for Egypt

    Customer data

    ParameterRequirementDescription
    nameRequiredCustomer name
    emailRequiredCustomer e-mail
    documentOptionalCustomer's valid document number
    phone_numberRequiredCustomer’s phone (for Fawry SMS)

    Payment parameters

    ParameterRequirementDescription
    merchant_payment_codeRequiredUnique merchant payment code.
    currency_codeRequiredSupported value: EGP.
    amount_totalRequired.Total amount to be charged.

  3. Sample request

    Here’s an example using CURL to initiate a Fawry payment:

    curl -X POST \
    --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_test_integration_key_here",
       "operation": "request",
       "payment": {
         "name": "Precious Karibo",
         "email": "PK@example.com",
         "document": "853513468",
         "phone_number": "0100108955,
         "country": "eg",
         "payment_type_code": "fawry",
         "merchant_payment_code": "a92253fwe29djbs2",
         "currency_code": "EGP",
         "amount_total": 10
       }
     }'

  4. Sample response

    A successful request returns a response similar to the example below.

    • The Fawry reference number is located in the fawry.reference_number parameter.
    • status: "SUCCESS" indicates EBANX successfully processed the request.
    • payment.status: "PE" (Pending) means the payment is awaiting completion at a Fawry outlet.

    {
       "payment": {
           "hash": "67a0ccf54ff4a63e87f5d29e97836e1ca67af9af8a9c8075",
           "country": "eg",
           "merchant_payment_code": "1738591477",
           "status": "PE",
           "amount_ext": "10.00",
           "currency_ext": "EGP",
           "due_date": "2025-02-06",
           "payment_type_code": "fawry",
           "customer": {
               "email": "jose@example.com",
               "name": "JOSE SILVA"
           },
           "fawry": {
               "reference_number": "775814981"
           }
       },
       "status": "SUCCESS"
    }

  5. Show Fawry reference number

    Display the fawry.reference_number and the due_date along with clear instructions for your customer to visit a Fawry location and complete the payment.

  6. Monitor payment for status changes

    Notifications

    • EBANX will send a notification whenever a payment status changes.

    Status

    • After receiving a notification, retrieve the payment status.
    • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO).
    • If the customer does not complete the payment by the due_date, the status will automatically update to cancelled (CA).

  7. Congratulations!

    You have successfully integrated Fawry.

    For more information, refer to the
    Direct API reference guidechevron_right

Fawry UX Flow​


This demo illustrates the end-to-end payment experience with Fawry.The journey begins on the merchant’s checkout page, where the customer selects Fawry and enters their mobile number. After submitting the request, a reference number is generated and displayed to the user.The customer can then complete the payment either by either Visiting any Fawry physical location to pay with cash, or Using the Fawry payment app to finalize the transaction digitally.

Fawry UX Workflow

Resources​

Use the following resources when testing in your sandbox environment.

Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right
Debit Card Icon

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: