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.

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.

   SandboxProduction

   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.

   Parameter	Description
   operation	Set to request
   integration_key	Your EBANX integration key
   payment_type_code	Set to fawry
   country	Set to eg for Egypt.

   Customer data

   Parameter	Description
   name	Customer name
   email	Customer e-mail
   document	Customer's valid document number
   phone_number	Customer’s phone (for Fawry SMS)

   Payment info

   Parameter	Description
   merchant_payment_code	Unique merchant payment code
   currency_code	For Fawry in Egypt, use EGP.
   amount_total	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": "Jose Silva",
        "email": "jose@example.com",
        "document": "853513468",
        "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.
   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
   • Learn more about Payment Notificationschevron_right

   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).
   • Learn more about Retrieving Payment Statuschevron_right

7. Congratulations!

   You have successfully integrated Fawry.

   For more information, refer to the

   Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

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

Click to explorechevron_right

Error Codes

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

Click to explorechevron_right

Still need help?

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

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.