FawryPay via Fawry

Accept FawryPay payments from customers in Egypt with Fawry as the payment service provider (PSP). The customer selects FawryPay, gets a FawryPay reference on the Fawry page and pays it later at a Fawry outlet or in the myFawry app. Fawry also processes card payments in Egypt through the same integration.

Supported workflows

Before you begin

Complete these steps before you send your first FawryPay payment through Fawry:

Get your merchant code and API key from Fawry.
Set up a Fawry integration in your workspace with your merchant code and API key. Contact your Payrails account team if Fawry isn’t listed in your Payrails Portal yet.
Choose whether Payrails sends its notification URL to Fawry on each payment. Turn on this account setting if you don’t configure the Payrails notification URL in your Fawry account.
In the Payrails Portal, go to Settings → Integrations, open your Fawry integration, select Fawry Pay under Payment methods, and save.
Add FawryPay as a payment option in your workflow.

To try the flow before you go live, follow the Fawry testing guide.

Request fields for Fawry

Send these fields in the authorize request, in addition to the standard authorize fields. Payrails checks Required fields and returns an error when one is missing. Fields required by the PSP pass the Payrails checks but the PSP can decline the payment without them.

Field	Status	Description
`meta.order.lines`	Required	At least one order line. Sent to Fawry as the charge items.
`meta.order.lines[].unitPrice`	Required	The price of one item.
`meta.order.lines[].quantity`	Required	Must be one or more.
`meta.order.lines[].id`	Required by Fawry	Sent to Fawry as the item ID.
`meta.clientContext.language`	Required	Sent to Fawry as the payment language, for example `en-gb`.
`meta.customer.email`	Required by Fawry	Sent to Fawry as the customer’s email.
`meta.customer.phone.number`	Recommended	Sent to Fawry as the customer’s mobile number.
`meta.customer.name`, `meta.customer.lastName`	Recommended	Sent to Fawry as the customer’s name.
`meta.customer.reference`	Optional	Sent to Fawry as the customer profile ID.
`meta.order.description`	Optional	Sent to Fawry as the payment description.
`meta.order.lines[].description`	Optional	Sent to Fawry as the item description.

Authorize a FawryPay payment

Call authorize a payment with fawryPay as the paymentMethodCode. The response includes the redirect to the Fawry page.

Authorize request

{
  "amount": {
    "value": "250.00",
    "currency": "EGP"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "fawryPay",
      "amount": {
        "value": "250.00",
        "currency": "EGP"
      }
    }
  ],
  "meta": {
    "customer": {
      "email": "nour.hassan@example.com",
      "name": "Nour",
      "lastName": "Hassan",
      "phone": {
        "countryCode": "+20",
        "number": "1001234567"
      }
    },
    "order": {
      "description": "Example Store order",
      "lines": [
        {
          "id": "item-1",
          "description": "Wireless headphones",
          "quantity": 1,
          "unitPrice": {
            "value": "250.00",
            "currency": "EGP"
          }
        }
      ]
    },
    "clientContext": {
      "language": "en-gb"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

After the customer gets their FawryPay reference, Fawry returns them to your success or error URL. The payment is still pending at that point. Confirm the result through webhook notifications or the execution status before you fulfill the order.

How Fawry handles FawryPay

The payment stays pending until the customer pays the reference. When the customer pays, Fawry notifies Payrails, and Payrails records the authorization and the capture together.
If the customer leaves the Fawry page before generating a reference, the payment stays pending.
To stop an unpaid reference, cancel the FawryPay payment. Send meta.clientContext.language on the cancel request too: Payrails returns an error without it.
Refunds use the Fawry reference of the paid payment. Fawry supports full and partial refunds.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Supported workflows

Before you begin

Request fields for Fawry

Authorize a FawryPay payment

How Fawry handles FawryPay

​Supported workflows

​Before you begin

​Request fields for Fawry

​Authorize a FawryPay payment

​How Fawry handles FawryPay

Supported workflows

Before you begin

Request fields for Fawry

Authorize a FawryPay payment

How Fawry handles FawryPay