Gravity Forms PayPlug Premium Add-on Setup Guide

The Gravity Forms PayPlug Premium Add-on lets your Gravity Forms take card payments in euros through PayPlug, the French online payment service. When a form is submitted, the add-on creates a PayPlug payment for the exact total and sends the customer to the PayPlug payment page, where they pay by card. When they come back, or when PayPlug sends its notification, the add-on reads the payment back from PayPlug and only then marks the entry as paid. Refunds, full or partial, are made from the entry screen. This guide covers every setting, the feed, what happens during a payment, refunds, testing in Test mode and going live.

How a payment works

1. The customer fills in the form. Gravity Forms works out the total; the add-on checks that it is a euro amount with at most two decimals, from 0.30 to 20,000.00 EUR, and that the email address is valid.
2. The entry is saved with the status Processing. The add-on creates a PayPlug payment on your server with the total in cents, the customer details you mapped in the feed, the delivery type, a description, a unique order reference, a signed return link, a signed cancel link and a signed notification address.
3. PayPlug answers with the payment and its payment page. Before the customer is sent there, the add-on checks that PayPlug created it for the right amount, in euros, in the mode you chose, and that the page is on payplug.com. If anything differs, the payment is aborted at PayPlug and the customer is told that nothing was charged.
4. The customer pays by card on the PayPlug page, including strong customer authentication when their bank asks for it. Card details are entered on PayPlug and never reach your website.
5. PayPlug sends the customer back to your form page and posts a notification to your site. Either way, the add-on reads the payment from PayPlug with your key and updates the entry: Paid, Failed or Cancelled.
6. If the customer clicks Cancel payment on the PayPlug page, the add-on aborts the open payment at PayPlug and marks the entry Cancelled straight away.

Install and activate

1. In WordPress go to Plugins → Add New → Upload Plugin, upload the zip and activate it.
2. Open Forms → Settings → PayPlug, enter your GravityExtra license key and activate it. The settings below appear once the license is active.
3. Check Forms → Settings: the currency must be Euro.

Settings

Open Forms → Settings → PayPlug. Both modes have their own key field; only the key of the mode you choose is used for new payments. An entry always keeps the mode it was created in, so a payment started in Test mode is still read with the Test key after you switch to Live.

Getting an API key

1. Sign in to the PayPlug portal and open API keys.
2. Choose API Key, pick the mode (Test first) and generate the key.
3. PayPlug shows the key only once. Copy it and paste it into the Test API key field, then save. The connection line turns green when PayPlug accepts it.

The feed

Open your form, go to Settings → PayPlug and add a feed. Choose Products and Services or Donations and the payment amount (usually the form total). Then map the customer fields: the email is required; first and last name, address, city, postcode, country and mobile phone are optional but recommended, because PayPlug passes them to the card issuer during strong customer authentication and fills in the payment page with them. A French mobile number typed as 06 12 34 56 78 is sent in international form (+33 6 12 34 56 78); numbers from other countries need their international prefix.

• Description: shown to the customer on the PayPlug page, up to 80 characters. Merge tags work; the default is the form title and the entry number.
• Notifications: tick Send form notifications only after the customer has paid to hold the usual form notifications until the payment is confirmed. They are sent once, when the entry becomes Paid.
• Payment events: in the form notifications you can also choose Payment Completed, Payment Failed or Cancelled and Payment Refunded as the event.

The form and the PayPlug page

Use Gravity Forms product, quantity, option and total fields as usual. The amount sent to PayPlug is the total Gravity Forms calculated on your server, so a total changed in the browser cannot lower the price. The submit button can say Continue to payment, because the customer goes to the PayPlug page next.

When the customer comes back, they see your normal confirmation if the payment is paid. If PayPlug has not confirmed the payment yet, a short waiting message checks again by itself every few seconds. If the payment failed or was cancelled, the customer is told that nothing was charged and can return to the form.

Payment statuses

The entry screen

Every PayPlug entry has a PayPlug box on the right with the status, the amount, the PayPlug payment id, the order reference, the card (brand and last four digits), the failure code if there was one, and the refunded total. Test payments carry a Test badge.

• Refresh status reads the payment from PayPlug again and applies it.
• Refund with PayPlug sends a full or partial refund to the customer’s card. Type the amount in euros (the field starts with the amount left) and confirm.

Refunds

Before a refund is sent, the add-on reads the payment from PayPlug and checks that it is paid for the entry amount, in the entry’s mode, inside PayPlug’s refund period, and that the amount fits what is left (from 0.10 EUR). Each refund form can be used once, so a double click or a reloaded page cannot refund twice. Refunds are recorded on the entry as transactions with a note; when the whole amount has been refunded the entry becomes Refunded. Refunds you make in the PayPlug portal are recorded too, when PayPlug notifies your site.

Testing in Test mode

1. Leave the mode on Test and save your Test API key.
2. Open the form on your site, fill it in and continue to payment.
3. On the PayPlug page, pay with one of the PayPlug test cards from the PayPlug documentation. Test cards that are declined let you check the Failed path too.
4. Back on your site, check the confirmation, then the entry: it should be Paid with the Test badge, and the held notifications should have been sent.
5. Try a partial refund from the entry screen and check that it appears in the PayPlug portal.
6. Start another payment and click Cancel payment on the PayPlug page: the entry should show Cancelled.

Going live

1. Generate a Live API key in the PayPlug portal and paste it into the Live API key field.
2. Switch the mode to Live and save. The connection line should say Connected to PayPlug (Live).
3. Make one small real payment, check the entry and refund it from the entry screen.

For developers

• gravityextra_payplug_payment_fields filters the payment before it is sent (for example to add metadata). The amount, currency, return, cancel and notification addresses and the order reference cannot be changed by it.
• gravityextra_payplug_rate_limit changes the per-visitor limits (payment starts 10, return page 30, notifications 120 per minute).
• gravityextra_payplug_payments_per_hour changes the site-wide cap of new payments per hour (300).
• gravityextra_payplug_notification_base changes the base address of the notification link (for a site behind a proxy).

// Add the booking date to the PayPlug metadata for one form (ID 7).
add_filter( 'gravityextra_payplug_payment_fields', function ( $payment, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $payment;
    }
    $payment['metadata']['booking_date'] = rgar( $entry, '8' );
    return $payment;
}, 10, 4 );

How it differs

• Nothing is trusted from the browser or the notification: every result is read back from PayPlug with your key and checked against the entry’s payment id, order reference, amount, currency and mode before the entry changes.
• Each payment gets its own signed notification address. A notification with a wrong or missing signature is refused, and a repeated notification is dropped, so a payment can only be completed once.
• The mode is checked on every new payment: a Live key saved as the Test key (or the other way round) is caught at once and the payment is aborted before the customer pays.
• The cancel link and the status check abort open payments at PayPlug, so an old payment page cannot be paid after the entry was cancelled.
• Refunds from the entry screen are checked against PayPlug first and protected by a one-time form, and refunds made in the PayPlug portal are recorded too.
• Payment creation, the return page and notifications have per-visitor limits, and new payments have an hourly cap, so a flood of form posts cannot create payments without end.

Troubleshooting

Uninstall

Uninstalling the add-on from Forms → Settings → Uninstall removes its settings (including the encrypted keys), the status check schedule, its locks, counters and cached checks. Entries, their notes and transactions stay in Gravity Forms, and payments and refunds at PayPlug are not touched.

Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year. Questions? Contact GravityExtra support.