> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Fawry

> Connect Fawry to Payrails for cards and FawryPay in Egypt, covering your merchant code, API key and notification settings.

<Note>
  **Who should use this guide**

  This guide is intended for merchants who:

  * Use **Payrails** as a payment orchestrator
  * Use **Fawry** for cards or [FawryPay](/docs/orchestration/payment-methods/fawrypay/fawry) in Egypt
  * Have an active Fawry merchant account
</Note>

***

## Create a Fawry integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **Add instance** to create a new integration configuration.
4. Select the **workspaces** where this integration should be available.

<Note>
  **About workspaces**

  Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.
</Note>

***

## Step 1: Choose the integration type

* Select **Payment**.
* Continue to the next step.

***

## Step 2: Choose the provider

* Select **Fawry**.
* Continue to the next step.

<img src="https://mintcdn.com/payrails-42074109/lzrTQ7bLOCPj3agG/images/docs/fawry-image-01.png?fit=max&auto=format&n=lzrTQ7bLOCPj3agG&q=85&s=60c64c0086d7f8e69cef54b035a93cff" alt="A screenshot showing Fawry selected as the provider." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/fawry-image-01.png" />

***

## Step 3: Configure your Fawry integration

<Tip>
  **What you'll need from Fawry**

  Before you begin, make sure you have your Fawry merchant code and API key. Fawry provides them when it sets up your account.
</Tip>

***

### Integration instance name

> An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

**In Payrails**

* Enter an **Instance name** for your integration, for example `merchant_fawry`.

<img src="https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max&auto=format&n=145W1v58K5wnDMNC&q=85&s=470be58979509680650b0cbf8b5eecc4" alt="A screenshot showing the integration instance name field." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/orchestration/integrations/shared/integration-instance-name.png" />

***

### Account details

**In Payrails**

| Field | Value |
| :- | :- |
| **Merchant code** | Your Fawry merchant code |
| **If true, send notification URL to Fawry in payment request** | Refer to [Configure Fawry settings](#configure-fawry-settings). |

<img src="https://mintcdn.com/payrails-42074109/lzrTQ7bLOCPj3agG/images/docs/fawry-image-02.png?fit=max&auto=format&n=lzrTQ7bLOCPj3agG&q=85&s=64694cb267b5d442bb92a199f03fdbfd" alt="A screenshot showing the Fawry account details fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/fawry-image-02.png" />

***

### Credentials

**In Payrails**

| Field | Value |
| :- | :- |
| **API key** | Your Fawry API key, also called the security key. Payrails signs requests with it and verifies notifications from Fawry. |

Payrails sends requests to the Fawry staging environment in test mode and to the live environment in live mode, so use the credentials for the matching environment.

<img src="https://mintcdn.com/payrails-42074109/lzrTQ7bLOCPj3agG/images/docs/fawry-image-03.png?fit=max&auto=format&n=lzrTQ7bLOCPj3agG&q=85&s=47d134eae3047dd87ad0722fcb4f9a42" alt="A screenshot showing the Fawry credential fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/fawry-image-03.png" />

***

### Payment methods

**In Payrails**

* Select **Card**, **Fawry Pay** or both.

<img src="https://mintcdn.com/payrails-42074109/lzrTQ7bLOCPj3agG/images/docs/fawry-image-04.png?fit=max&auto=format&n=lzrTQ7bLOCPj3agG&q=85&s=7a7bc90652f1dcbb983272ec29b4750f" alt="A screenshot showing the Fawry payment method selection." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/fawry-image-04.png" />

***

### Webhooks or notifications

* If you turn on **If true, send notification URL to Fawry in payment request**, Payrails sends its notification URL to Fawry with every payment, so there's nothing to set up in Fawry.
* Otherwise, copy the **Notification URL** shown under **Account configuration** at the top of the integration form, and ask Fawry to set it as the notification URL for your merchant code.

Payrails verifies each notification with your API key.

***

## Request fields for Fawry

Send these fields in the [authorize request](/reference/authorizeaction) for card payments, in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to Fawry when you include them. For more about meta fields, refer to [Meta fields](/docs/orchestration/meta-fields).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to Fawry as the amount and currency. |
| `meta.order.lines` | Required | At least one line, each with `unitPrice` and a `quantity` of 1 or more. Sent as the charge items, with `id` and `description` when you send them. |
| `meta.clientContext.language` | Required | Sent as the payment language. |
| `merchantReference` | Optional | Sent as the merchant reference number. |
| `meta.order.description` | Optional | Sent as the payment description. |
| `meta.customer.email` | Optional | Sent as the customer email. |
| `meta.customer.phone.number` | Optional | Sent as the customer mobile number. |
| `meta.customer.name`, `meta.customer.lastName` | Optional | Sent as the customer name. |
| `meta.customer.reference` | Optional | Sent as the customer profile ID. Send it when you store cards, so that Payrails can delete them later. |
| `meta.risk.threeDSMode` | Optional | `Force` runs 3D Secure. |
| `instrument.storeInstrument` | Optional | Stores the card with Fawry for later payments. |

***

## Configure Fawry settings

Some Fawry integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting.

| Setting | What it does |
| :- | :- |
| **If true, send notification URL to Fawry in payment request** | Payrails sends its notification URL to Fawry with every card and FawryPay payment. Turn this on unless Fawry has already set up the Payrails notification URL for your account. |

***

## Enable the integration

**In Payrails**

* Select **Save account** to enable the integration.
* Confirm the integration shows as **Enabled**.

Your **Fawry** integration is now ready to process payments.

***

## Next steps

1. Run a test card payment in EGP in the Fawry staging environment.
2. Verify that:
   * The payment appears in Fawry.
   * The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup in live mode.

→ Continue to: [Test a payment](/docs/orchestration/payment-acceptance/test-payments)


## Related topics

- [FawryPay via Fawry](/docs/orchestration/payment-methods/fawrypay/fawry.md)
- [FawryPay](/docs/orchestration/payment-methods/fawrypay.md)
- [FawryPay via Flutterwave](/docs/orchestration/payment-methods/fawrypay/flutterwave.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.