Gravity Forms SumUp Premium Add-on Setup Guide

The Gravity Forms SumUp Premium Add-on connects Gravity Forms to your SumUp merchant account for online payments. When a form is submitted, the add-on creates a SumUp checkout for the exact form total and sends the customer to the SumUp hosted checkout page, where they pay with the payment methods available on your account. This guide covers the setup, every setting, how payments are confirmed, refunds, testing and going live. Card readers and in-person payments are not part of this add-on.

Requirements

• WordPress 6.5 or newer, PHP 7.4 or newer, and Gravity Forms 2.9 or newer.
• A SumUp merchant account that can take online payments, and a SumUp sandbox merchant account for testing (created in the SumUp dashboard under Developer Settings → Sandboxes).
• Gravity Forms set to the currency of your SumUp account.
• An https website, so SumUp can send payment updates to it.
• A GravityExtra licence key for the add-on.

Step 1: Install and activate the licence

Upload the plugin zip in Plugins → Add New → Upload Plugin, activate it, then open Forms → Settings → SumUp and activate your licence key. All payment features (settings, feeds, payments, payment updates, the status check and entry actions) need an active licence.

Step 2: Get the merchant code and a secret API key

1. Log in to the SumUp dashboard and switch to your sandbox merchant account (the account menu shows a clear sandbox warning). Note its merchant code.
2. Open Settings → For Developers → Toolkit → API Keys and create a key. Copy the secret key (sup_sk_…); SumUp shows it only once. The public key (sup_pk_…) does not work here.
3. Later, for Live, do the same in your real merchant account.

Step 3: Connect the add-on

In Forms → Settings → SumUp, keep the mode on Test, enter the merchant code and the secret API key of the sandbox account, and save. The add-on asks SumUp for the account with this key, so nothing is created. If SumUp refuses the key, if the key belongs to another account, or if a real account is entered under Test (or a sandbox account under Live), the key is not saved and the field tells you why. The connection line then shows the account type, the merchant code and the account currency.

Step 4: Currency and amounts

SumUp takes online payments only in the currency of your account. Set the Gravity Forms currency in Forms → Settings to the account currency shown on the connection line; the currency line turns red if they differ, and payments are refused before anything is sent. The amount sent is the exact total Gravity Forms worked out on the server; nothing from the browser is used.

Step 5: Create the feed

Open your form, then Settings → SumUp → Add New. Choose Products and Services (or Donations) and the payment amount (usually the form total), and write the description you will see with the payment in your SumUp dashboard; merge tags such as {form_title} #{entry_id} work. Tick “Send form notifications only after the customer has paid” to hold the notifications until the payment is confirmed. The customer enters their payment details on the SumUp page, so no customer fields are mapped.

How payments are confirmed

1. On submit, the form is checked on the server: licence, connection, account currency, decimals, limits, the per-visitor limit and the hourly cap.
2. A checkout is created with the amount, the currency, your merchant code, a unique reference for this attempt, the description, a signed return address, the payment update address and an expiry.
3. The answer must carry your reference and merchant code, the amount and currency sent, and a hosted checkout address on SumUp’s checkout host. Otherwise the customer stays on the form and is told nothing was charged. If SumUp does not answer in time, the add-on looks for the checkout by its reference instead of creating a second one.
4. The customer pays on the SumUp page; the success page has a button back to your site.
5. When a payment update arrives, when the customer comes back, every five minutes and when you click Refresh status, the add-on reads the checkout back from SumUp.
6. Only a PAID checkout with a successful transaction for the entry amount and currency, your reference and your merchant code marks the entry Paid. The transaction code and payment type are added to the note.

Refunds

On a paid entry, enter the amount in the SumUp box and click Refund with SumUp. The add-on reads the checkout back first, then asks SumUp to refund that amount of the transaction, and records the refund on the entry when the transaction read back from SumUp shows it.

• Full or partial: several refunds are possible, up to the paid amount minus what is refunded or still waiting.
• A refund SumUp shows as pending is kept as “Refund pending” and recorded by the status check when SumUp completes it.
• Refunds made in your SumUp dashboard are recorded too, when you click Refresh status.
• The entry becomes Refunded when the whole amount is refunded. A failed refund is never recorded; a note asks you to check the dashboard.
• If SumUp does not answer a refund request clearly, new refunds are blocked for an hour so you can check the transaction in your SumUp dashboard first.

Developer hooks

• gravityextra_sumup_description: change the description of the checkout (the amount, currency, reference and merchant code are always set by the add-on).
• gravityextra_sumup_currencies: limit the currencies that can be paid.
• gravityextra_sumup_max_minor: lower the largest payment (in minor units).
• gravityextra_sumup_rate_limit and gravityextra_sumup_payments_per_hour: per-visitor limits and the hourly cap.
• gravityextra_sumup_notify_url: change the payment update address.

// Put the service date in the SumUp description of one form (ID 7).
// The amount, currency, reference and merchant code cannot be changed here.
add_filter( 'gravityextra_sumup_description', function ( $description, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $description;
    }
    return 'Bike service on ' . rgar( $entry, '8' ) . ' / booking ' . rgar( $entry, 'id' );
}, 10, 4 );

// Payments only up to 2,000.00 in the account currency (minor units).
add_filter( 'gravityextra_sumup_max_minor', function () {
    return 200000;
} );

Testing

Use your sandbox merchant account in Test mode: sandbox accounts never move real money. Submit your form, pay with one of the test cards from the SumUp developer documentation and check that the entry becomes Paid with the transaction code and a test payment note. In the sandbox, an amount of 11.00 always fails, so you can check a declined payment too. Then send a partial refund from the entry.

Going live

Enter the merchant code and secret API key of your real account in the Live fields, switch the mode to Live and save. Each entry remembers the mode and merchant code it was created with, so test entries are still read back from the sandbox. Make one small real payment and refund it.

Troubleshooting

• “Online payment is not available in …”: the Gravity Forms currency is not the currency of your SumUp account. Change it in Forms → Settings.
• The key is not saved: read the message under the field. Use the secret key (sup_sk_…) of the account whose merchant code you entered.
• Entries stay Processing: the customer has not paid yet, or the site is not on https so SumUp cannot send updates. Click Refresh status on the entry; the five-minute status check also reads it.
• A payment is Failed but the customer paid later: the next update or Refresh status marks it Paid.

Uninstall

Deleting the plugin removes its settings (including the encrypted keys), schedules, locks and counters. Checkouts, payments and refunds in your SumUp account stay as they are.