1. Overview
MultiSafepay Gateway for Gravity Forms by PatSaTECH lets any Gravity Forms form take payments through MultiSafepay. When the form is submitted, the customer is sent to MultiSafepay’s secure payment page with every method active on your MultiSafepay website (Visa, Mastercard, iDEAL | Wero, Bancontact, PayPal, Klarna, Apple Pay, Google Pay, bank transfer and more), or straight to one method you choose in the feed. Card details never reach your site.
The entry is marked Paid only after the payment has been read back from the MultiSafepay API (status, amount and currency), on the customer’s return, from a signed notification, or in a final check when the payment link expires. Notifications and other add-on feeds can wait until the payment is completed. Full and partial refunds are made from the entry screen.
Built on the official Gravity Forms Payment Add-On Framework, with its own slug (gravityforms-multisafepay), classes and options.
2. Features
- MultiSafepay payment page (redirect, API v1)
- Per feed: all methods, or straight to iDEAL | Wero, Bancontact, card or PayPal
- Products & Services feeds, conditional logic
- Notifications sent only when paid
- Post Payment Actions & delayed post creation
- API key checked on save, active methods listed
- Signed notifications (HMAC-SHA512) or API lookup
- Notification URL sent with every payment
- Every payment re-read from the API
- Amount & currency verification, per-entry lock
- Clear decline message + Try again
- Unpaid entries marked Failed on a timer
- Full & partial refunds from the entry
- Reserved refunds followed up automatically
- Refunds made in MultiSafepay Control recorded
- Name, email, phone (E.164) and address sent
- Payment page language
- Logging without API keys
3. Requirements
| Component | Minimum |
|---|---|
| WordPress | 6.0 (tested up to 7.1.3) |
| Gravity Forms | 2.5 or later (tested on 2.10.3) |
| PHP | 7.4 (tested on 8.1.34) |
| SSL / HTTPS | Required for live payments and notifications. |
| MultiSafepay | A test account (free) or a live account, and the website API key of the website you add for this site |
| Currency | Forms → Settings → Currency. EUR for iDEAL | Wero and Bancontact; cards and other methods also take GBP, USD, CHF, SEK and more. |
Tested on: WordPress 7.1.3, Gravity Forms 2.10.3, PHP 8.1.34, MultiSafepay test environment (EUR). See Tested on.
4. Installation
- In WordPress admin go to Plugins → Add New → Upload Plugin.
- Choose
gravityforms-multisafepay-1.0.0.zipand click Install Now. - Activate MultiSafepay Gateway for Gravity Forms. Gravity Forms must be active.
5. Step-by-step setup with screenshots
- iDEAL | Wero paid (entry 9642) and Visa paid (entry 9643): entry Paid, confirmed by signed notification
- iDEAL declined (entry 9644) and cancelled (entry 9645): the entry stays Processing and the customer gets a “Try again” button
- €3 iDEAL partial refund on entry 9642: Reserved, then accepted in MultiSafepay Control; the add-on added exactly one note “MultiSafepay refund … (3,00 €) is now completed.”
Click any screenshot to open it full size. API keys are never shown (not even masked); MultiSafepay order / transaction / refund IDs, emails, phone numbers and IP addresses are blurred or left out.
Part A: MultiSafepay
Create a test account and a website
Sign up at
testmerchant.multisafepay.com/signup, open Websites › Add website and copy the website’s API key with the copy button. Details: Getting your API key.Activate payment methods
Settings › Payment methods: switch on the methods you want.
Part B: WordPress / Gravity Forms
Upload and activate the add-on
Plugins → Add New → Upload Plugin, choose
gravityforms-multisafepay-1.0.0.zip, install and activate.
MultiSafepay Gateway for Gravity Forms 1.0.0 active. Set the currency
Forms → Settings → Currency: choose Euro if you want iDEAL | Wero and Bancontact.
Paste the API key
Go to Forms → Settings → MultiSafepay, keep Mode on Test, paste the Test API key and save. The add-on checks the key and lists the active methods (“MultiSafepay Test API key verified. Active payment methods: …”). The notification URL is shown and sent with every payment.
Forms → Settings → MultiSafepay after Save: the “API key verified” notice and Mode (the API key fields below are not shown). 
Further down the same page: Payment page language, Default phone country, Payment link expires after (minutes) and Debug log, then Save Settings. Add a MultiSafepay feed
Open the form, go to Settings → MultiSafepay → Add New. Choose Products and Services, the payment amount, and the Payment method (All active methods or one method). Map the billing fields (name, email, phone, address), and under Notifications tick Send notifications only when payment is received and the notifications that should wait (for example Admin Notification). Add Conditional Logic if the feed should only run sometimes. A Posts option appears only on forms with Post fields, and Post Payment Actions only when another add-on with delayed-payment support (for example Mailchimp) is installed.
Feed settings: name, transaction type, payment amount and the Payment method list. 
Bottom of the feed: billing information mapping, Payment method, Notifications with “Send notifications only when payment is received” ticked, and Conditional Logic.
Part C: Test payment
Submit the form
Fill in the form and submit it. The entry is created as Processing and the customer is sent to MultiSafepay.
Test form with a 10,00 € product (email blurred). Pay on the MultiSafepay page
The payment page shows your shop, the description and the amount. Test card
4111 1111 1111 1111; for iDEAL | Wero pick a Test Scenario and click TEST.
MultiSafepay payment page for a 10.00 EUR form payment. 
iDEAL | Wero test page with the Test Scenario list (order ID blurred). Back on the site
The customer returns to the form’s confirmation. If MultiSafepay hasn’t confirmed yet, the page says “Thank you. Your payment is being confirmed by MultiSafepay; you will receive a confirmation once it completes.”
Form confirmation after a MultiSafepay payment. Entry is Paid
The entry becomes Paid, delayed notifications are sent, and a note records the payment: “Payment of 10,00 € completed through MultiSafepay. Transaction: … (iDEAL), MultiSafepay order gf-9642-1-…. Mode: test. Confirmed by: notification.”
Entry detail: Payment Details box with status Paid, transaction ID and amount (IDs and customer details blurred). 
Entry notes: “Customer sent to the MultiSafepay payment page…”, then “Payment of 10,00 € completed through MultiSafepay…” (IDs blurred).
6. Getting your MultiSafepay API key
Test account and API key
- Create a free test account at testmerchant.multisafepay.com/signup (no business verification needed for testing). If MultiSafepay asks for a verification code or two-factor authentication, enter it yourself.
- In MultiSafepay Control open Websites › Add website (or open your existing website). Enter your site name and URL. You may enter the notification URL shown in the plugin as the Webhook URL; this is optional because the plugin sends it with every payment.
- Copy the website’s API key and paste it into Forms → Settings → MultiSafepay (Test API key). Use the copy button: never send the key by email or chat.
- Open Settings › Payment methods and switch on the methods you want to test (iDEAL | Wero, Bancontact, Visa, Mastercard, PayPal…). On a test account every method can be switched on.
Live API key
- Your live account at
merchant.multisafepay.comis opened by MultiSafepay after business verification (KYC). Complete that with MultiSafepay; enter any 2FA codes yourself. - Add your website under Websites, copy its API key, and activate the payment methods in your contract.
- Paste it into the Live API key field, set Mode to Live and save. The plugin checks the key and lists the active methods.
7. Add-on settings
Forms → Settings → MultiSafepay
| Setting | Description |
|---|---|
| Mode | Test (default, testapi.multisafepay.com, no real money) or Live. Entries keep the mode they were created in. |
| Test API key / Live API key | The website API key from MultiSafepay Control › Websites › your website (password fields). Checked when you save; the active methods are listed. Also used to verify notification signatures. |
| Notifications | Shows the notification URL https://your-site.com/?callback=gravityforms-multisafepay. It is sent with every payment; you may also enter it as the website’s Webhook URL in MultiSafepay Control. |
| Payment page language | Site language (default), or English, Nederlands, Deutsch, Français, Español, Italiano. |
| Default phone country | Two-letter code (default NL) used for phone numbers entered without a + country code; phones are sent in E.164 format. |
| Payment link expires after (minutes) | Default 60. The add-on then checks MultiSafepay once more and marks the entry Failed if nothing was paid. 0 disables this (use 0 or a large value if you offer bank transfer). |
| Debug log | Logs API and notification details (Forms → Settings → Logging must be on for this add-on). Errors are always logged; API keys never. |
8. Feed settings
| Setting | Description |
|---|---|
| Name / Transaction type | Products and Services (one-time payments; subscriptions are not supported). |
| Payment amount | Form total or a product field. |
| Payment method | All active methods (MultiSafepay payment page), or straight to iDEAL | Wero, Bancontact, Credit card or PayPal. The method must be active in MultiSafepay Control; iDEAL | Wero and Bancontact are for EUR. |
| Billing information | Map first name, last name, email, phone, address, city, state, zip and country. They are sent to MultiSafepay to prefill the payment page. |
| Notifications | “Send notifications only when payment is received”: the ticked notifications are sent only when MultiSafepay confirms the payment. |
| Posts (only on forms with Post fields) | “Create post only when payment is received.” |
| Post Payment Actions (only when another add-on with delayed-payment support, e.g. Mailchimp, is installed) | Run that add-on’s feed only when payment is received. |
| Conditional logic | Only use this feed when the condition matches. |
9. Notifications (webhooks)
Notification URL: https://your-site.com/?callback=gravityforms-multisafepay
The plugin sends this URL with every MultiSafepay order (notification_url, method POST), so nothing has to be set up in MultiSafepay Control. You can also enter it as the website’s Webhook URL in MultiSafepay Control › Websites › your website.
| Notification | How it is checked | What the plugin does |
|---|---|---|
POST (JSON body, Auth header) | The Auth header is base64(timestamp:signature); the signature is HMAC-SHA512 of timestamp:raw body with your website API key. A wrong signature is refused (HTTP 403). | Reads the order back from MultiSafepay (GET /orders/{id}: status, amount, currency) under a per-entry lock, then updates the entry. A completed payment is final; repeats and older notifications are ignored. |
GET (?transactionid=…, no body) | Sent when the Webhook URL is used without the POST method. It cannot be signed, so the plugin trusts nothing in it and only reads the order back from MultiSafepay. | |
| Refund created / accepted | Same checks. | The refund list of the payment (related_transactions) is compared with what the entry already has: a Reserved refund that becomes completed gets one note “MultiSafepay refund … is now completed.”; a cancelled refund gets a warning; a refund made in MultiSafepay Control is recorded. No refund is ever recorded twice. |
Notifications for orders this site did not create (wrong order-id prefix or unknown order) are acknowledged and ignored. Every applied notification writes a log line saying how it was verified (signature or API lookup).
10. Payment flow & entry statuses
| MultiSafepay status | Gravity Forms entry |
|---|---|
| Form submitted, customer on the MultiSafepay page | Processing |
| completed (amount and currency match) | Paid; delayed notifications and Post Payment Actions run |
| declined | Stays Processing with one note. MultiSafepay first shows its own “Transaction declined” page; after the customer clicks Cancel or Back there, the form page shows the decline message and a Try again button |
| void / cancelled by the customer | Stays Processing; “The payment was not completed.” with Try again |
| expired, or time limit reached without a payment | Failed: “No completed MultiSafepay payment 60 minutes after the form was submitted; entry marked Failed.” |
| uncleared | Stays Processing with a note; updated automatically when MultiSafepay accepts or declines it |
| Amount or currency mismatch | Not marked Paid; note “MultiSafepay payment … was NOT accepted…” |
| refunded / partial_refunded | Notes for each refund; fully refunded entries become Refunded |
Declined and cancelled entries deliberately stay Processing so the customer can retry on the same entry; the timer marks them Failed if they don’t.
11. Transaction ID and finding the payment
The MultiSafepay transaction ID (PSP ID) is the entry’s transaction ID. Each attempt has a MultiSafepay order ID gf-<entry id>-<attempt>-<random>. In MultiSafepay Control open Transactions and search for either ID; refunds appear under Related transactions.
12. Refunds
- Open the entry. In the MultiSafepay refund box enter an amount (leave it blank for a full refund) and click the refund button; confirm “Refund this payment through MultiSafepay?”.
- The refund is sent at once and the add-on reads its real status back: “Refund of … completed by MultiSafepay (refund …).” (usually cards) or “Refund of 3,00 € sent to MultiSafepay (refund …, status Reserved).” with the hint to accept it (test) or that MultiSafepay completes it at the end of the day (live).
- A Reserved refund is picked up automatically once it is accepted: the entry gets exactly one note, “MultiSafepay refund … (3,00 €) is now completed.” Confirmed live on entry 9642.
- A refund larger than what is left on the payment is refused (“Only … can still be refunded on this MultiSafepay payment.”).
- Refunds made in MultiSafepay Control are recorded on the entry once.
- MultiSafepay refuses refunds when your balance is too low or the same amount is refunded twice within 5 minutes; on test accounts partial refunds must be enabled by MultiSafepay support.
13. Declined, cancelled and expired payments
Declined payment, step by step. When a payment is declined (for example the iDEAL | Wero Failure test scenario or a declined card), MultiSafepay first shows its own Transaction declined page and the customer is still on MultiSafepay. The entry already gets its decline note from the notification. Only when the customer clicks Cancel or Back on that page do they return to the form page, which shows “The payment was declined. Please try again or use another payment method.” and a Try again button. Try again opens a new MultiSafepay payment for the same entry (entry 9647). If the customer closes the tab instead, the entry stays Processing until the payment link expires and is then marked Failed.
After a cancel on the MultiSafepay payment page (before a method is chosen) the customer comes straight back to the form page with the same kind of message and a Try again button (entry 9645).
Time limit. After Payment link expires after (default 60 minutes) plus a short grace period the add-on checks MultiSafepay once more and marks the entry Failed if nothing was paid.
14. Testing (test payment details)
Test payments use your MultiSafepay test account (testmerchant.multisafepay.com) and its website API key; they run on testapi.multisafepay.com and no money moves. All payment methods can be switched on for a test website under Settings › Payment methods.
| Method | What to do | Result |
|---|---|---|
| iDEAL | Wero | Choose iDEAL | Wero. MultiSafepay shows its test page: pick a Test Scenario and click TEST. | Success = paid · Failure = declined (MultiSafepay shows its “Transaction declined” page; click Cancel or Back to return to the site) · Cancelled = cancelled · Expired = expired. Used for entries 9642, 9644 and 9645. |
| Visa / Mastercard | 4111 1111 1111 1111 (Visa) or 5500 0000 0000 0004 (Mastercard), any name, any future expiry, CVC 123 | Paid. If a 3-D Secure test page appears, choose Authenticated (Y); our Visa tests went straight through. Used for entry 9643. |
| Card declined | 4012 0010 3746 1114 (3-D Secure failed) or 4012 0010 3848 8884 (insufficient funds) | Declined: the customer sees a clear message and can try again. |
| Bancontact | Card 6703 4500 0546 20008, any future expiry (6703 6640 0000 00042 = declined) | Paid. |
| Other cards and scenarios | MultiSafepay’s docs, “Test payment details”: docs.multisafepay.com/docs/testing | Declined, 3-D Secure, Uncleared and more. |
15. Payment methods & currencies
Who can use MultiSafepay. MultiSafepay (Amsterdam) serves businesses in the Netherlands, Belgium and across Europe. Anyone can open a free test account; a live account is opened by MultiSafepay after business verification.
Payment methods. Every method active on your MultiSafepay website appears on the payment page, as your contract allows: Visa, Mastercard, Maestro, American Express, iDEAL | Wero, Bancontact, PayPal, Klarna, Apple Pay, Google Pay, bank transfer, SEPA Direct Debit, Trustly, KBC/CBC, Belfius, MB WAY, Multibanco, Alipay, WeChat Pay, gift cards and more. When you save the API key the plugin lists the active methods.
Currency. MultiSafepay takes many currencies (EUR, GBP, USD, CHF, SEK, DKK, NOK, PLN and others; card methods are the most flexible). iDEAL | Wero and Bancontact are EUR only, and the add-on refuses to start a payment with a method that cannot take the form currency (with a clear message to set Forms → Settings → Currency). The tests used EUR.
Amounts. Amounts are sent in cents; the total must be above zero.
16. Debug logs
Turn on Forms → Settings → Logging for MultiSafepay Gateway for Gravity Forms and tick Debug log in the add-on settings. To read it, go to Forms → Settings → Logging and click view log next to MultiSafepay Gateway for Gravity Forms. With Gravity Forms logging on, warnings and errors (for example a rejected payment or a refused notification signature) and notification receipts are always written; every API request and status line only when the add-on’s Debug log is ticked. API keys, card data and customer details are never logged.
17. Troubleshooting & FAQ
“The API key was refused” when saving
Copy the website API key from MultiSafepay Control › Websites › your website, and check it matches the Mode: a test key only works in Test mode.
Paid on MultiSafepay but the entry is still Processing
Check that the site is reachable over https and that nothing blocks https://your-site.com/?callback=gravityforms-multisafepay. The return page and the expiry check also read the payment from MultiSafepay. Enable logging and look at the add-on log.
The log shows “Notification for … refused: signature …”
The notification was signed with another website’s key, or test and live keys are mixed up.
Why does one refund say “completed” and another “Reserved”?
Card refunds are usually completed at once; iDEAL | Wero and other bank refunds start as Reserved. Live, MultiSafepay completes them at midnight; in the test environment they stay Reserved until you click Accept in MultiSafepay Control.
Will I get a note when a Reserved refund completes?
Yes. A Reserved refund is picked up automatically once it is accepted: the entry gets exactly one “MultiSafepay refund … is now completed” note (or a warning if the refund was cancelled).
Why are declined entries Processing and not Failed?
So the customer can use Try again on the same entry. The timer marks the entry Failed when the payment link expires unpaid.
Subscriptions?
No. One-time payments only.
18. Tested on
- WordPress 7.1.3
- Gravity Forms 2.10.3
- PHP 8.1.34; PHP 7.4 or later required
- MultiSafepay test environment (testapi.multisafepay.com), form currency EUR
- Scenarios: iDEAL | Wero paid, declined and cancelled (Try again); Visa paid; signed POST notifications; iDEAL partial refund Reserved, then accepted (one completion note)
- Not yet tested by PatSaTECH: live payments, PayPal, Klarna, Apple Pay / Google Pay, uncleared payments and chargebacks (covered by automated tests only)
19. Changelog
1.0.0 — 2026-10-19
- Initial release on the Gravity Forms Payment Add-On Framework.
- MultiSafepay payment page (API v1, redirect); per-feed payment method (all, iDEAL | Wero, Bancontact, card, PayPal).
- Test and live API keys checked on save; signed notifications (HMAC-SHA512) or API lookup; notification URL sent with every payment.
- Every payment re-read from the API under a per-entry lock; decline reason with Try again; unpaid entries marked Failed.
- Full and partial refunds with the real refund status; Reserved refunds followed up automatically; refunds made in MultiSafepay Control recorded.
- Delayed notifications, delayed posts and Post Payment Actions; logging without API keys.
20. Support
PatSaTECH · [email protected] · www.patsatech.com
Please include your WordPress, Gravity Forms and PHP versions, the mode (test or live) and the relevant log lines. Never send your API key.
