Fawry is a payment method that is supported only in Egypt, and its payments workflow is a little bit different from payments via credit/debit card workflow. In the article, we will walk you through the transaction API via Fawry, for a better understanding of the request/response workflow.


In this article you will be going to know about:

Create Payment Page


The payment request payload will be similar to the usual Hosted Payment Page one, except you will pass the "fawry" value within the "payment_methods" object, to declare that this payment will be only via Fawry, as the default behavior is showing all available payment methods for this merchant profile, the customer can select the payment method on the payment page. Hence sending the payment method(s) on the request would limit the options on the payment page to the only specified sent payment methods. To know more about this please check our How to control payment methods on the PayTabs payment page? solution article.


Sample Request Payload

{
    "profile_id" : {{profile_id}},
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "4444333221",
    "cart_currency": "EGP",
    "cart_amount": "1000",
    "cart_description": "50 empty boxes used for nothing",
    "payment_methods": [
        "fawry"
    ],
    "paypage_lang": "en",
    "callback": "https://webhook.site/53aba5b2-2e8d-4104-af30-34976b2fd57d",
    "return": "https://webhook.site/53aba5b2-2e8d-4104-af30-34976b2fd57d",
    "customer_details": {
        "name": "John Snow",
        "email": "[email protected]",
        "phone": "01234567890",
        "street1": "Winterfell, The north",
        "city": "Egypt",
        "state": "eg",
        "country": "EG",
        "zip": "34717"
    },
    "shipping_details": {
        "name": "John Snow",
        "email": "[email protected]",
        "phone": "01234567890",
        "street1": "Winterfell, The north",
        "city": "Egypt",
        "state": "eg",
        "country": "EG",
        "zip": "34717"
    }
}



Sample Response Payload

{
  "tran_ref": "PTE2110300142699",
  "tran_type": "Sale",
  "cart_id": "4444333221",
    "cart_description": "50 empty boxes used for nothing",
  "cart_currency": "EGP",
  "cart_amount": "1000.00",
  "return": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
  "redirect_url": "https://secure-egypt.paytabs.com/payment/page/3F76B62E82E417E6AB2104212437A16EA53E657E75232A6C4C544962",
"customer_details": {
        "name": "John Snow",
        "email": "[email protected]",
        "phone": "01234567890",
        "street1": "Winterfell, The north",
        "city": "Egypt",
        "state": "eg",
        "country": "EG",
        "zip": "34717"
    },
    "shipping_details": {
        "name": "John Snow",
        "email": "[email protected]",
        "phone": "01234567890",
        "street1": "Winterfell, The north",
        "city": "Egypt",
        "state": "eg",
        "country": "EG",
        "zip": "34717"
    }
}


Page Language


Payment pages via the Fawry payment method are currently available only in the English Language. and doesn’t support a full Arabic page yet.


Payment Workflow


Customer User-Experience


Once you created the payment request as clarified above and redirect your customer to the sent payment page "redirect_url", he will experience a payment page as shown below, and he will have to go to any Fawry POS station/store to pay for the provided.



Also, according to the Fawry process, your customer will immediately receive an SMS like:

"Please use code# 9133849621 to pay 1,002 LE for GOT Store before 24-12-2021, 04:29 PM ,via FawryPay (Service code 788)"


The SMS will be sent to the number registered on customer details, NOT the number on shipping details.

Merchant User-Experience


Merchant Initiating Payments' Notifications


  • via The Dashboard

    Once the customer opens the payment page a "Payment Request" transaction will be created on your dashboard with a "Pending" status as shown below, and only then you will be able to identify that your customer navigated successfully to your payment page:

 


  • via the Callback 


    If you passed a callback URL within your first request payload, only then a callback like the shown below would be sent to this provided callback URL to notify your system that your customer has navigated (opened) to the payment page successfully as well:
    {
  "tran_ref": "PTE2**********68",
  "merchant_id": 2***7,
  "profile_id": 8***6,
  "cart_id": "4444333221",
  "cart_description": "50 empty boxes used for nothing",
  "cart_currency": "EGP",
  "cart_amount": "1000.00",
  "tran_currency": "EGP",
  "tran_total": "1000.00",
  "tran_type": "Payment Request",
  "tran_class": "ECom",
  "customer_details": {
    "name": "John Snow",
    "email": "[email protected]",
    "phone": "0123 456 7890",
    "street1": "Winterfell, The north",
    "city": "Egypt",
    "country": "EG",
    "zip": "34717",
    "ip": "15*.***.***.*16"
  },
  "shipping_details": {
    "name": "John Snow",
    "email": "[email protected]",
    "phone": "01234567890",
    "street1": "Winterfell, The north",
    "city": "Egypt",
    "country": "EG",
    "zip": "34717"
  },
  "payment_result": {
    "response_status": "P",
    "response_code": "9133849621",
    "response_message": "Pending",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2021-12-23T14:30:02Z"
  },
  "payment_info": {
    "payment_method": "Fawry",
    "card_scheme": "",
    "payment_description": "Fawry",
    "issuerCountry": "EG",
    "issuerName": "Fawry"
  },
  "ipn_trace": "IPNS0003.********.00000DB5"
}




Merchant Post-Payment Notifications


Merchants can be notified as well post the payment whether the payment was paid successfully, or expired without being paid as clarified below:


  • Expired Payments


    In this case, the payment hasn't been paid till it exceeds the expiry date and becomes no longer valid

    • via The Dashboard

      The status of the previously initiated "Payment Request" transaction on the Paytabs dashboard will be updated to "Expired" as shown below:


    • via the Callback


      If you passed a callback URL within your first request payload, only then a new callback would be triggered/sent with the new transaction status which is expired
      {
  "tran_ref": "PTE21**********8",
  "merchant_id": 2***7,
  "profile_id": 8***6,
  "cart_id": "4444333221",
  "cart_description": "50 empty boxes used for nothing",
  "cart_currency": "EGP",
  "cart_amount": "1000.00",
  "tran_currency": "EGP",
  "tran_total": "1000.00",
  "tran_type": "Payment Request",
  "tran_class": "ECom",
  "customer_details": {
    "name": "John Snow",
    "email": "[email protected]",
    "phone": "0123 456 7890",
    "street1": "Winterfell, The north",
    "city": "Egypt",
    "country": "EG",
    "zip": "34717",
    "ip": "15*.***.***.*16"
  },
  "shipping_details": {
    "name": "John Snow",
    "email": "[email protected]",
    "phone": "01234567890",
    "street1": "Winterfell, The north",
    "city": "Egypt",
    "country": "EG",
    "zip": "34717"
  },
  "payment_result": {
    "response_status": "X",
    "response_code": "9133849621",
    "response_message": "Expired",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2021-12-23T14:30:02Z"
  },
  "payment_info": {
    "payment_method": "Fawry",
    "card_scheme": "",
    "payment_description": "Fawry",
    "issuerCountry": "EG",
    "issuerName": "Fawry"
  },
  "ipn_trace": "IPNS0004.********.00000C54"
}


It's worth mentioning that the expiry date can be calculated regarding the transaction date and time + the expiry period subjected to the agreed one on the onboarding documents.



  • Successfully Paid Payments


    In this case, the payment has been done successfully via one of the Fawry POS stations/stores.

    • via The Dashboard


      1- The status of the previously initiated "Payment Request" transaction on the Paytabs dashboard will be updated to "Authorized" as shown below:


      2- A new transaction will be initiated/created with the type "Sale" and will be marked as "Authorized" as a status, coping all its proprieties from the previous transaction as shown below:

  • via the Callback


    If you passed a callback URL within your first request payload, only then a new callback would be triggered/sent with the new "Sale" transaction that has been created as shown below:
    {
  "tran_ref": "PTE2**********9",
  "previous_tran_ref": "PTE21**********8",
  "merchant_id": 2***7,
  "profile_id": 8***6,
  "cart_id": "4444333221",
  "cart_description": "50 empty boxes used for nothing",
  "cart_currency": "EGP",
  "cart_amount": "1000.00",
  "tran_currency": "EGP",
  "tran_total": "1000.00",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "customer_details": {
    "name": "John Snow",
    "email": "[email protected]",
    "phone": "0123 456 7890",
    "street1": "Winterfell, The north",
    "city": "Egypt",
    "country": "EG",
    "zip": "34717",
    "ip": "1**.***.***.**6"
  },
  "shipping_details": {
    "name": "John Snow",
    "email": "[email protected]",
    "phone": "01234567890",
    "street1": "Winterfell, The north",
    "city": "Egypt",
    "country": "EG",
    "zip": "34717"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "9133849621",
    "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2021-12-23T14:30:02Z"
  },
  "payment_info": {
    "payment_method": "Fawry",
    "card_scheme": "",
    "payment_description": "Fawry",
    "issuerCountry": "EG",
    "issuerName": "Fawry"
  },
  "ipn_trace": "IPNS0004.********.00000C55"
}



If you configured an IPN or didn't want to pass a callback with each request payload, you will recieve as well all the previously mentioned Callbacks notifications. To know more about managing IPNs please check our How to configure Instant payment notification (IPN)? solution article.