Fawry with Direct API

About this guide

This page explains how to add Fawry to your existing Direct API integration. The Direct API flow remains consistent across all payment methods, but each requires its own payment_type_code and a few specific fields.

• For Fawry Cash:
• payment_type_code: "fawry"
• country: "eg" (Egypt)

Availability:

Fawry Cash integration through Direct API is currently available in Egypt (EG).

If you are not integrated with EBANX Direct API yet, please take a look in this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
2. Fawry enabled in your EBANX Dashboard. (If Fawry is not enabled, please contact our integration team.)

How it works (High-Level)

1. Create the payment:

• Your system sends a POST request to EBANX’s Direct API endpoint (/ws/direct) with "payment_type_code": "fawry".
• The payment remains in Pending (PE) status until the customer pays in cash at a Fawry outlet.

2. Display/Send instructions to the customer

• The API response will include details such as:
  • merchant_payment_code
  • due_date
  • fawry.reference_number (if applicable)
• The customer will also receive an SMS or email containing the Fawry reference number, which they must present to complete the payment.

3. Fawry notifies EBANX

• Once the customer pays at a Fawry outlet, kiosk, or Fawry, Fawry notifies EBANX.
• EBANX updates the payment status to Confirmed (CO).

4. Check or listen for status updates

• You can periodically check the payment status via the EBANX Query API or configure a webhook for real-time updates.
• If the customer does not pay by the due_date, the payment will be automatically canceled (CA status).

Basic parameters:

Parameter	Description
operation	Operation must be request
integration_key	Your unique and secret integration key
payment_type_code	For Fawry Cash, use fawry
country	Two-letter country code - eg for Egypt

Customer data:

Parameter	Description
name	Customer’s full name.
email	Customer’s email address.
document	Customer’s document (e.g., National ID).
address	Customer’s street address.
street_number	Street number.
city	City.
state	State or region.
zipcode	ZIP or postal code.
phone_number	Customer’s phone (used for Fawry SMS).

Charge Parameters:

Parameter	Description
merchant_payment_code	A unique code you generate to identify this payment.
currency_code	ISO-4217 currency code. For Egypt/Fawry, use EGP.
amount_total	Total amount to be charged.
instalments	Number of instalments. Use "1" if no installment plan applies.

Example Request: Below is an example POST request to create a Fawry Cash payment in sandbox using the Direct API:

curl -L -X POST 'https://sandbox.ebanxpay.com/ws/direct' \

-H 'Content-Type: application/json' \

--data-raw '{

"integration_key": "{{your_integration_key}}",

"operation": "request",

"payment": {

"payment_type_code": "fawry",

"currency_code": "EGP",

"merchant_payment_code": "1738591477",

"country": "eg",

"email": "gabriel.pinheiro@ebanx.com",

"name": "Gabriel Pinheiro",

"phone_number": "41995121292",

"amount_total": "10",

"zipcode": "1234",

"address": "street name",

"street_number": "111",

"city": "city",

"state": "state",

"instalments": 1

}

}'

Example Response: If the payment request is successful, you will receive a JSON response like the one below:

{

"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": "gabriel.pinheiro@ebanx.com",

"name": "GABRIEL PINHEIRO"

},

"fawry": {

"reference_number": "775814981"

}

},

"status": "SUCCESS"

}

Key Elements:

• status: "SUCCESS" indicates EBANX successfully processed the request.
• payment.status: "PE" (Pending) means the payment is awaiting completion at a Fawry outlet.
• fawry.reference_number: The specific Fawry reference code the customer must present to complete the payment.

Completing the Payment:

1. Provide instructions to the customer

• Retrieve and store details such as:
  • merchant_payment_code
  • due_date
  • fawry.reference_number (if available)
• EBANX will send an SMS and email containing the Fawry reference number.
  • You may also send your own notifications if preferred.

2. Customer pays at Fawry

• The customer visits any Fawry kiosk, partner location, or the Fawry app with the reference code to complete the payment.
• Payment is made in cash (or another accepted method) at the kiosk or on the Fawry app.

3. Status update

• Once Fawry confirms the payment, EBANX updates the payment status from "PE" (Pending) to "CO" (Confirmed).
• If the customer does not pay by the due date, the status changes to "CA" (Canceled).

Handling Payment Status:

Status Code	Description
PE (Pending)	Payment created, awaiting offline payment at Fawry
CO (Confirmed)	Payment received by Fawry and confirmed by EBANX
CA (Canceled)	Payment canceled if the customer does not pay by due_date

Getting help

We hope this guide helps you integrate Fawry Cash payments with EBANX Direct API. If you need further assistance:

• If you’re not our partner yet and would like to know more about our prices and conditions please fill ou this form and our comercial team will get in touch with you.
• In case you’re already our partner please get in touch with our support team at integration@ebanx.com.