Gravity Forms MultiSafepay Premium Add-on Setup Guide

The Gravity Forms MultiSafepay Premium Add-on connects Gravity Forms to your own MultiSafepay account. When a form with a MultiSafepay feed is submitted, the add-on creates a MultiSafepay order for the exact total Gravity Forms calculated and sends the customer to the MultiSafepay payment page, where they choose how to pay: a card, iDEAL, Bancontact, a bank transfer or any other method active on your website. Payment details are entered at MultiSafepay, never on your website.

When MultiSafepay reports the payment, the add-on checks the notification signature with your API key, reads the order back from MultiSafepay and only then marks the entry Paid, with the MultiSafepay transaction ID as the transaction ID. This guide covers installation, every setting, the webhook, the feed, what the customer sees, the payment statuses, refunds, testing with a test 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 → MultiSafepay and activate your licence key. The MultiSafepay settings appear once the licence is active.
3. Set the Gravity Forms currency (Forms → Settings) to Euro, or to another currency you will enable in the add-on settings.

Updates are delivered from gravityextra.com like every GravityExtra add-on. The add-on keeps working if you rename its folder.

Currencies and amounts

The euro is built into Gravity Forms with two decimals and a comma as the decimal separator, so prices such as 285,00 € or 1.250,00 € are read correctly both in the browser and on the server. The add-on sends the total to MultiSafepay in cents, as MultiSafepay asks: a total of 285,00 € is sent as 28500 EUR. Totals with more than two decimals, below 1.00 or in a currency that is not enabled are refused before anything is sent to MultiSafepay.

MultiSafepay settles in euros by default. If MultiSafepay has enabled other currencies on your account, you can also take payments in pound sterling, US dollars, Swiss francs, Danish, Norwegian or Swedish krone, Polish zloty, Czech koruna, Canadian or Australian dollars: tick the currency in the settings and set the Gravity Forms currency to it. These are all built into Gravity Forms with two decimals as well. MultiSafepay only shows the payment methods that support the currency of the order. Currencies without decimals are not offered.

Settings

When you save, the add-on asks MultiSafepay to confirm the API key of each mode (a read that changes nothing in your account). A key MultiSafepay refuses is not saved, and the error tells you which mode to check. The settings page also shows when the last notification with a valid signature arrived, so you can see at a glance that notifications reach your site.

The webhook

MultiSafepay tells your site about payments with notifications, sent as a POST request to a webhook address. The add-on sends its own webhook address (https://your-site/wp-json/gravityextra-msp/v1/notification) with every order, so there is nothing to add in the MultiSafepay dashboard. MultiSafepay only accepts https addresses without a port and with a limited set of characters, so use a permalink structure other than “Plain”; the settings page warns you when the address cannot be used. Without it, payments are still confirmed when the customer returns and by the five-minute status check.

For each notification the add-on:

1. limits how many notifications one address can send per minute;
2. checks the Auth header: a timestamp and an HMAC-SHA512 signature of the raw message made with your API key, and refuses the notification when it does not match or is more than an hour old;
3. finds the entry by the order ID it created, and checks that the key belongs to the mode the payment was made in;
4. reads the order back from MultiSafepay and only then changes the entry, and answers OK.

If MultiSafepay cannot be read for a moment, the add-on answers with an error, so MultiSafepay sends the notification again later. A repeated notification never completes a payment twice.

The feed

Open the form, go to Settings → MultiSafepay and add a feed:

• Transaction type: Products and Services, or Donations. The payment amount is usually the form total.
• Customer information: map the email field (required: MultiSafepay uses it for the payment confirmation and bank transfer instructions). First name, last name and phone are optional; names are sent when they are 2 to 25 characters long.
• Description: shown on the MultiSafepay payment page, in your dashboard and, where the bank supports it, on the customer’s statement. Merge tags work; the default is {form_title} #{entry_id}.
• Payment method: leave empty to offer every method active on your website, or enter one MultiSafepay gateway code such as IDEAL, CREDITCARD or BANKTRANS to open the payment page for that method only.
• Notifications: tick it to send the form notifications only after the customer has paid. Use the Payment Completed event for receipts.
• Conditional logic: as with any Gravity Forms payment feed.

What the customer sees

The customer fills in the form and clicks the submit button. The add-on creates the order and sends them to the MultiSafepay payment page, in the language of your site where MultiSafepay offers it, where they pick a payment method and pay. MultiSafepay then sends them back to the form page. The add-on reads the order from MultiSafepay and shows your confirmation as soon as the payment is confirmed. If a payment needs a moment, the page shows “Confirming your payment” and checks again by itself every few seconds. If the customer cancelled on the payment page, the page says the payment was not completed and that they have not been charged, with a link back to the form.

Payment statuses

The entry screen

Every entry paid through MultiSafepay has a MultiSafepay box with the status, the amount, the MultiSafepay transaction ID, the payment method, the order ID, the last MultiSafepay status and any refunds. Test payments carry a “Test — test payment” badge. Refresh status reads the order and its refunds from MultiSafepay again. Each step is also written to the entry notes.

Refunds

On a paid entry, type the amount in the refund field and click Refund with MultiSafepay. Amounts can be typed as 50,00, 1.250,00, 50.00 or 1250. The add-on first reads the order from MultiSafepay to make sure the payment is completed with the entry amount, then sends the refund with the exact amount. MultiSafepay passes refunds to the bank once a day, so a refund may show as “Refund requested” until MultiSafepay completes it; it is then recorded once under its MultiSafepay refund ID. Several partial refunds are possible up to the paid amount; when they add up to the whole amount the entry becomes Refunded.

• A refund form can be used once, so a double click or a resubmitted page cannot refund twice.
• If MultiSafepay does not answer, the request stays reserved (“do not refund again”). The status check records it when MultiSafepay lists the refund, or frees it after an hour with a note.
• A refund MultiSafepay declines frees the reservation with a note.
• Refunds made in the MultiSafepay dashboard are recorded from the next notification or when you click Refresh status.
• Staff need the Gravity Forms “edit entries” permission; administrators always can.

Testing with a test account

1. Create a free MultiSafepay test account, add your website in the test dashboard and copy its API key.
2. Keep the mode on Test, paste the API key and save. The connection line should say “Connected to MultiSafepay (Test)”.
3. Add a feed, open the form on a page that MultiSafepay can reach over the internet and pay a small amount with one of the test payment methods MultiSafepay lists for test accounts.
4. Check that the entry becomes Paid, the transaction ID appears in the MultiSafepay box and the settings page shows the last notification. Then make a partial refund.

Going live

• Copy the API key of your website from the live MultiSafepay dashboard.
• Paste it into the Live field and switch the mode to Live.
• Make sure the site uses https and is reachable from the internet, so MultiSafepay can send its notifications.
• Make one small real payment and refund it to confirm everything end to end.
• Entries started in Test keep using the test key, so switching modes never mixes the two.

For developers

The filter gravityextra_multisafepay_request_fields can change the description, the customer’s email, names, phone, locale and IP address, the payment method (gateway) and how long the payment page stays open (days_active, 1 to 365). The order type, order ID, amount, currency and the return, cancel and webhook addresses are always set by the add-on. Other filters: gravityextra_multisafepay_max_cents (lower the largest payment), gravityextra_multisafepay_rate_limit, gravityextra_multisafepay_payments_per_hour and gravityextra_multisafepay_notify_url (the webhook address, for sites behind a proxy).

// Keep the payment page of one form (ID 7) open for 3 days and show the class date in the description.
// The order ID, amount, currency and the return and webhook addresses cannot be changed here.
add_filter( 'gravityextra_multisafepay_request_fields', function ( $body, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $body;
    }
    $body['days_active'] = 3;
    $body['description'] = 'Class ' . rgar( $entry, '8' ) . ' / booking ' . rgar( $entry, 'id' );
    return $body;
}, 10, 4 );

How it differs

• It connects to your own MultiSafepay account directly with the MultiSafepay API, so the money is settled by MultiSafepay to your account under your own MultiSafepay agreement, and the payment page shows every method you have switched on for your website.
• It never trusts the return address or the notification body on its own. The notification signature is checked with your API key, and then the order is read back from MultiSafepay. Only a completed order with the entry’s amount and currency marks the entry Paid.
• The webhook address is sent with every order, so there is no webhook to add in the dashboard, and each entry remembers whether it was a test or a live payment.
• Refunds, including several partial refunds, are made from the Gravity Forms entry and recorded once per MultiSafepay refund, together with refunds you make in the MultiSafepay dashboard.

Troubleshooting

Uninstall

Uninstalling from Forms → Settings → Uninstall, or deleting the plugin, removes the settings (including the encrypted keys), the schedule, locks, counters and cached checks. Entries, their notes and the orders at MultiSafepay are kept.

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