Fawry

Who should use this guideThis guide is intended for merchants who:

Use Payrails as a payment orchestrator
Use Fawry for cards or FawryPay in Egypt
Have an active Fawry merchant account

Create a Fawry integration in Payrails

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

About workspacesWorkspaces 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.

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.

A screenshot showing Fawry selected as the provider.

Step 3: Configure your Fawry integration

What you’ll need from FawryBefore you begin, make sure you have your Fawry merchant code and API key. Fawry provides them when it sets up your account.

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.

A screenshot showing the integration instance name field.

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.

A screenshot showing the Fawry account details fields.

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.

A screenshot showing the Fawry credential fields.

Payment methods

In Payrails

Select Card, Fawry Pay or both.

A screenshot showing the Fawry payment method selection.

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 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.

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

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

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a Fawry integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider