How to Take MyFatoorah Payments with Gravity Forms (Kuwait, Saudi Arabia, UAE and More)

If you sell classes, services, event tickets or products in Kuwait, Saudi Arabia, the UAE, Qatar, Bahrain, Oman, Jordan or Egypt, MyFatoorah is probably already part of your business. It lets your customers pay an invoice online with the payment methods they use every day. Gravity Forms is the form builder many WordPress sites use for bookings, orders and donations. This tutorial shows how to connect the two, so that every form submission becomes a MyFatoorah invoice for the exact form total, and every payment is confirmed by MyFatoorah before your team sees it as paid.

We use the Gravity Forms MyFatoorah Premium Add-on, a small plugin that talks to the MyFatoorah API from your server. It takes about fifteen minutes from installing the plugin to your first test payment.

Why take MyFatoorah payments through Gravity Forms?

Many businesses in the region start by sending payment links by hand: someone fills in a form, a team member creates an invoice in the MyFatoorah portal, copies the link and sends it over chat or email, and later checks the portal to see whether it was paid. That works for a handful of orders a week, but it is slow for customers and easy to get wrong when the numbers grow.

With the form and the payment joined together, the customer pays straight after submitting, the amount always matches what they chose in the form, and the entry in Gravity Forms shows the payment status, the MyFatoorah payment ID and any refunds. Your notification emails can wait until the payment is confirmed, so nobody starts work on an unpaid booking.

How the payment works

• The customer fills in your form and sees the total in your currency, for example KD 285.750.
• When they submit, your server creates a MyFatoorah invoice for that exact total and sends the customer to the MyFatoorah invoice page.
• They pay there with a card or another method active on your MyFatoorah account. Card numbers are entered at MyFatoorah, never on your site.
• They come back to your form page, and the plugin asks MyFatoorah for the invoice before it shows your thank-you message.

Forms that work well with MyFatoorah

• Class and workshop bookings with a fixed price per seat.
• Event registrations with ticket types and quantities.
• Service deposits, for example for a design consultation or a repair.
• Simple product orders where a full shop would be too much.
• Donations and membership fees with a chosen amount.

What you need

• WordPress with Gravity Forms 2.9 or newer.
• A MyFatoorah account in one of the supported countries, and a free demo account for testing.
• The API token of each account (Integration Settings → API Key in the portal).
• For live payments, a site that runs on https, so MyFatoorah can send webhooks to it.

Gulf currencies and three decimals

One detail is easy to miss. The Kuwaiti, Bahraini and Jordanian dinar and the Omani rial have three decimals: one dinar has 1,000 fils. Gravity Forms does not list these currencies by default, and a currency set up with two decimals would round 285.750 to 285.75 in some places and could even read the amount wrongly in others. The plugin adds all eight MyFatoorah currencies to Gravity Forms with the right decimals, so the total on the form, the amount on the MyFatoorah invoice and the amount on the entry are the same number, to the fils.

Step 1: Install the add-on and connect your account

1. Upload and activate the plugin, then activate your licence key in Forms → Settings → MyFatoorah.
2. Leave the mode on Test and choose your account country.
3. Paste the API token of your demo account and save. The plugin checks the token with MyFatoorah without creating anything, stores it encrypted and only ever shows the first and last four characters.
4. In Forms → Settings, set the Gravity Forms currency to the currency of your account country.

Step 2: Set up the webhook

The webhook is how MyFatoorah tells your site that an invoice was paid or refunded, even if the customer closes the browser right after paying. Copy the webhook address from the plugin settings. In the MyFatoorah portal, open Integration Settings → Webhook Settings, turn webhooks on, choose version 2, tick the payment status and refund status events, paste the address and turn on the secret key. Copy the secret key back into the plugin and save.

From now on, every webhook is checked against that secret key. A webhook with a wrong or missing signature is refused, and a correct one is only a signal: the plugin still reads the invoice from MyFatoorah before it changes anything.

Step 3: Build the form

Create the form as usual. Add a name field, an email field, a phone field for the mobile number, your product fields and a total field. Prices follow the Gravity Forms currency, so a class at 120.125 dinars shows as KD 120.125. Gravity Forms works out the total in the browser for the customer and again on your server when the form is submitted; the plugin always uses the server total.

Step 4: Add a MyFatoorah feed

Open the form settings, choose MyFatoorah and add a feed. Pick Products and Services (or Donations), map the customer name, email and mobile to your fields, and write a description such as “Pottery class #{entry_id}”. The description becomes the invoice item the customer sees on the MyFatoorah invoice page. Keep “Send form notifications only after the customer has paid” ticked if your team should only hear about paid bookings.

Step 5: Test with your demo account

Open your form, fill it in and submit. You land on the MyFatoorah invoice page of the test environment. Pay with one of the MyFatoorah test cards and you come back to your form page with the thank-you message. In Forms → Entries, the entry shows Paid, the MyFatoorah payment ID and a note that it was a test payment. Try a partial refund from the MyFatoorah box on the entry to see how refunds are recorded. Then try a declined test card: the customer is told nothing was charged and the entry stays Processing, because they can still pay the same invoice.

What happens behind the scenes

1. The form is checked on the server: the currency must be your account currency and the total must have no more decimals than the currency has.
2. An invoice is created with SendPayment for the exact amount, with a unique reference for this attempt and signed return addresses.
3. The answer must contain an invoice number and an address on the MyFatoorah invoice page; otherwise the customer stays on the form and nothing is charged.
4. When the customer returns, when a webhook arrives and every five minutes, the plugin reads the invoice with GetPaymentStatus.
5. Only an invoice that MyFatoorah shows as paid, with a successful transaction, your reference, the entry amount and the entry currency, marks the entry Paid. Anything else is noted and left for you to check.

A worked example

A pottery studio in Kuwait City sells a two-hour wheel class at KD 120.125 and a glaze and firing kit at KD 45.500. A customer books two classes and one kit. The form shows KD 285.750. On submit, the plugin creates a MyFatoorah invoice with an InvoiceValue of 285.750 in Kuwaiti dinars and one invoice item, “Pottery class #1042”. The customer pays on the invoice page. The webhook arrives a few seconds later; its signature is valid, so the plugin reads the invoice: Paid, 285.750 KD, a successful transaction with its payment ID. The entry becomes Paid, the held booking email goes out, and the payment ID is stored on the entry. The next week the customer cancels one class, and the studio refunds 120.125 dinars from the entry. The refund is recorded once, and the entry stays Paid with 165.625 dinars left.

How it differs

• It connects to your own MyFatoorah account directly with the MyFatoorah API, so the money is settled by MyFatoorah to your account under your own MyFatoorah agreement, and the invoice page shows every payment method you have switched on.
• It never trusts the return address or the webhook body on its own. The webhook signature is checked with your secret key, and then the invoice is read back from MyFatoorah. Only a paid invoice with the entry’s reference, amount and currency marks the entry Paid.
• It adds the eight MyFatoorah currencies to Gravity Forms with the correct number of decimals, so a total of KD 285.750 is sent as exactly 285.750, never rounded and never ten times too large.
• Refunds, including several partial refunds, are made from the Gravity Forms entry and recorded once per MyFatoorah refund, together with refunds you make in the MyFatoorah portal.

Tips for smooth payments

• Map a real name field: MyFatoorah requires a customer name on every invoice.
• Ask for the mobile number in international format; the plugin removes your country code for MyFatoorah.
• Keep prices at the decimals of your currency, for example 12.500 dinars rather than 12.5 with hidden rounding.
• Use a clear description with the entry number, so your team can find the invoice in the MyFatoorah portal quickly.
• Check the Webhook line in the settings after your first payment: it shows when the last valid webhook arrived.

Step 6: Go live

When your tests look right, paste the live API token and webhook secret key from your country portal, set up the live webhook there, switch the mode to Live and save. Make one small real payment and refund it. Each entry remembers whether it was paid in Test or Live and in which country, so older test entries keep working.

Questions

Do card details reach my website?

No. The customer enters them on the MyFatoorah invoice page. Your site only receives the invoice status from MyFatoorah.

Which currencies can I use?

The currency of your MyFatoorah account country: KWD, SAR, AED, QAR, BHD, OMR, JOD or EGP. The plugin adds them to Gravity Forms with the right decimals.

What if the webhook never arrives?

The plugin also reads the invoice when the customer returns and every five minutes, so the entry is updated anyway.

Can I refund part of a payment?

Yes, several partial refunds up to the paid amount, from the entry screen. Refunds made in the MyFatoorah portal are recorded too.

Are recurring payments supported?

Not in this version. The plugin handles one-off payments for products, services and donations.

Get started

Get the Gravity Forms MyFatoorah Premium Add-on and follow the setup guide. Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year.