Gravity Forms MyFatoorah Premium Add-on Setup Guide

The Gravity Forms MyFatoorah Premium Add-on connects Gravity Forms to your own MyFatoorah account in Kuwait, Saudi Arabia, the United Arab Emirates, Qatar, Bahrain, Oman, Jordan or Egypt. When a form with a MyFatoorah feed is submitted, the add-on creates a MyFatoorah invoice for the exact total Gravity Forms calculated and sends the customer to the MyFatoorah invoice page, where they pay with a card or another method active on your account. Payment details are entered at MyFatoorah, never on your website.

When MyFatoorah reports the payment, the add-on checks the webhook signature with your secret key, reads the invoice back from MyFatoorah and only then marks the entry Paid, with the MyFatoorah payment ID as the transaction ID. This guide covers installation, currencies, every setting, the webhook, the feed, what the customer sees, the payment statuses, refunds, testing with a demo account and going live.

Installation

1. Download the add-on zip from your GravityExtra account and upload it in Plugins → Add New → Upload Plugin, then activate it.
2. Open Forms → Settings → MyFatoorah and activate your licence key. The MyFatoorah settings appear once the licence is active.
3. In Forms → Settings, set the Gravity Forms currency to the currency of your MyFatoorah account country, for example Kuwaiti Dinar.

Currencies and amounts

Gravity Forms does not include the Gulf currencies out of the box. The add-on adds all eight MyFatoorah currencies to the Gravity Forms currency list as soon as it is active, with the decimals each currency really has. It never changes a currency that another plugin already defined. Invoices are created in the currency of your MyFatoorah account country, so the Gravity Forms currency must match it.

The amount is worked out on your server from the entry, never from the browser. A total with more decimals than the currency has (for example 12.3456 dinars) is refused before anything is sent, so the customer is never charged a rounded amount. The smallest payment is 1 unit of the currency and the largest 999,999; a filter can lower the largest amount.

Settings

The webhook

MyFatoorah tells your site about payments and refunds with webhooks (version 2). Set them up once in the MyFatoorah portal of each mode:

1. Copy the webhook address from the Webhook line of the add-on settings. It ends in /wp-json/gravityextra-myf/v1/webhook.
2. In the MyFatoorah portal, open Integration Settings → Webhook Settings and turn webhooks on.
3. Choose webhook version 2 and tick the payment status and refund status events.
4. Paste the webhook address, turn on the secret key and save.
5. Copy the secret key into the Test (or Live) webhook secret key field of the add-on and save.

Each webhook is checked before anything happens: the signature must match your secret key, and the invoice must be one this site created in the same mode. Then the add-on reads the invoice back from MyFatoorah. A webhook that arrives twice is acknowledged without changing the entry again. If the read-back fails, the add-on answers with an error so MyFatoorah sends the webhook again.

The feed

• Transaction type: Products and Services, or Donations. The payment amount is the form total or one product field.
• Customer name (required by MyFatoorah), email and mobile: map them to your form fields. The mobile number is sent without the country code of your account country; numbers MyFatoorah cannot take are left out.
• Description: the invoice item the customer sees on the MyFatoorah invoice page and in your portal (merge tags work, up to 200 characters).
• Notifications: hold the form notifications until the customer has paid (on by default).

What the customer sees

The customer fills in the form and sees the total in your currency, for example KD 285.750. After pressing the submit button they go to the MyFatoorah invoice page, in English or in Arabic when your site language is Arabic. They pay there and come back to your form page, where the add-on reads the invoice from MyFatoorah and shows your confirmation. If a card is declined, they see that nothing was charged and can try again on the same invoice page.

Payment statuses

The entry screen

The MyFatoorah box on the entry shows the status, the amount, the MyFatoorah payment ID and payment method, the invoice number, your reference and the last status MyFatoorah reported. Refresh status reads the invoice and its refunds from MyFatoorah again. Test payments carry a “Test — test payment” badge. Users need the Gravity Forms capability to edit entries (administrators always can) to see the buttons.

Refunds

• Type the amount in the refund field of a paid entry and press Refund with MyFatoorah. The full remaining amount is filled in for you.
• The add-on reads the invoice back first, then asks MyFatoorah for the refund with the exact amount, and records it when MyFatoorah shows it as refunded.
• Several partial refunds are possible up to the paid amount. When the whole amount is refunded, the entry becomes Refunded.
• If MyFatoorah takes a moment, the entry shows “Refund requested” and the status check or the refund webhook records it later. A refund MyFatoorah cancels frees the amount again.
• Refunds you make in the MyFatoorah portal are recorded on the entry too, once.
• Each refund form can be used once, so pressing the button twice never refunds twice.

Testing with a demo account

1. Create a MyFatoorah demo account and copy its API token from the demo portal.
2. Keep the add-on in Test mode, choose your account country, paste the token and save. The connection line turns green.
3. Set up the webhook in the demo portal as described above and save the secret key.
4. Submit your form and pay on the invoice page with a MyFatoorah test card.
5. Check the entry: Paid, with the payment ID and a “Test — test payment” note. Try a partial refund.

Going live

• Paste the live API token and webhook secret key from your country portal, set up the webhook there, switch to Live and save.
• Make one small real payment and refund it.
• Your site must be reachable over https for live webhooks.

For developers

The filter gravityextra_myfatoorah_request_fields can change the customer name, email, mobile, invoice item text and language of the invoice. The amount, the currency, the reference and the return addresses are always set by the add-on. gravityextra_myfatoorah_max_minor lowers the largest payment and gravityextra_myfatoorah_payments_per_hour changes the hourly cap of new invoices (300 by default).

// Show the class date on the invoice item of one form (ID 7) and open the invoice page in Arabic.
// The amount, currency, reference and the return addresses cannot be changed here.
add_filter( 'gravityextra_myfatoorah_request_fields', function ( $body, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $body;
    }
    $body['ItemName'] = 'Class ' . rgar( $entry, '8' ) . ' / booking ' . rgar( $entry, 'id' );
    $body['Language'] = 'AR';
    return $body;
}, 10, 4 );

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.

Troubleshooting

Uninstall

Deleting the add-on from the Plugins screen removes its settings (including the encrypted tokens and secret keys), schedules and temporary data. Entries, notes and payments at MyFatoorah stay as they are.

Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year. See the Gravity Forms MyFatoorah Premium Add-on page for details.