Gravity Forms Swish Premium Add-on Setup Guide

The Gravity Forms Swish Premium Add-on connects Gravity Forms to your own Swish for merchants agreement in Sweden. When a form with a Swish feed is submitted, the add-on saves the exact total Gravity Forms calculated with the entry and creates a Swish payment request for it. The customer approves the payment in the Swish app with BankID. Card numbers and bank logins never come near your website.

When Swish reports the payment, the add-on reads the payment request back from Swish over your certificate connection and only then marks the entry Paid, with the Swish payment reference as the transaction ID. This guide covers installation, the certificate, every setting, the three ways customers pay, callbacks, the payment statuses, refunds, testing with the Merchant Swish Simulator 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 → Swish and activate your licence key. The Swish settings appear once the licence is active.
3. In Forms → Settings, set the Gravity Forms currency to Swedish Krona (SEK). Gravity Forms already knows the krona: prices show as 1 250,50 Kr.

Your Swish certificate

Swish identifies your site with a client certificate instead of an API key. You make it once in Swish Certificate Management (you log in with BankID; your bank registers who may do this):

1. On your own computer, create a 4096-bit RSA private key and a certificate request (CSR). Protect the key with a passphrase.
2. In Swish Certificate Management, enter your organisation number and Swish number, paste the CSR and choose PEM.
3. Save the certificate text you get back. It contains your certificate and the Swish certificates above it.
4. Paste the certificate text and the private key into the add-on settings, with the passphrase.

The certificate is valid for two years. The settings page shows its expiry date and warns 30 days before. If your certificate came as a .p12 file, convert it to PEM text first:

# Only if you have a .p12 file instead of PEM text (run on your own computer):
openssl pkcs12 -in certificate.p12 -clcerts -nokeys -out certificate.pem
openssl pkcs12 -in certificate.p12 -nocerts -out private-key.pem

Settings

When you save, the add-on checks that the private key opens with the passphrase and belongs to the certificate, that the certificate is valid and was made for your Swish number, and then asks Swish for a payment request that does not exist. Swish answers “not found” only when it accepts your certificate, so nothing is created. A certificate Swish refuses is not saved.

How customers pay

Map a phone field to Swish mobile number in the feed to offer the request to the phone. Leave the field optional: customers who leave it empty get the app button and the QR code. Numbers like 070-123 45 67 and +46 70 123 45 67 both work; the add-on turns them into the format Swish uses (46701234567). A number that cannot be a Swish number is refused on the form, before anything is sent.

The payment page

After submitting, the customer lands on a payment page of your site that shows the amount and what to do: open the Swish app, press the Open Swish button, or scan the QR code. The page asks your site every few seconds whether the payment is done; your site asks Swish. When Swish reports the payment as paid, the page moves on to your form’s confirmation. If the customer declines, cancels or lets the three minutes run out, the page says so and offers a new request to the phone or by QR code. A request is never repeated while one is still waiting, and never after Swish reports that the bank did not answer (code DS24): the customer is then asked to check the bank account and contact you.

Callbacks

Swish posts the outcome of each payment request and refund to the callback address the add-on sends with it. The address ends in /wp-json/gravityextra-swish/v1/callback and must use https on port 443.

Swish does not sign callbacks, so the add-on treats a callback only as a signal: it looks up which entry the request belongs to and then reads the request back from Swish over your certificate connection. If that read fails, the add-on answers with an error and Swish tries again. A status check every five minutes and the payment page pick up anything a callback missed.

The feed

• Transaction type: Products and Services, or Donations. The payment amount is the form total or one product field.
• Swish mobile number: optional; map it to a phone field.
• Message: shown to the customer in the Swish app, up to 50 characters. Swish accepts letters (including å, ä and ö), digits, spaces and :;.,?!()”; other characters become spaces. Merge tags work, for example “Bokning {entry_id}”.
• Notifications: hold the form notifications until the customer has paid (on by default).

Payment statuses

The entry screen

The Swish box on the entry shows the status, the amount, the Swish payment reference, your reference, the last four digits of the mobile number, how many payment requests were made and the last status Swish reported. Refresh status reads the payment and any open refunds from Swish 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 Swish. The full remaining amount is filled in for you; 250,50 and 250.50 both work.
• The add-on reads the payment back first, then sends the refund with the Swish Refund API. Swish pays it out within seconds, usually: the refund is recorded when Swish reports it paid, from the callback, the entry screen or the status check.
• Several partial refunds are possible, up to the paid amount, within 13 months of the payment. When the whole amount is refunded, the entry becomes Refunded.
• If Swish reports an error, nothing was refunded and the entry gets a note; you can refund again.
• If Swish does not answer a refund request, the add-on looks the refund up by its own id. When Swish has no such refund after ten minutes, it is released with a note.

Testing with the Merchant Swish Simulator

1. Download the Swish test certificate package from the Swish developer pages: it contains a test certificate, its key and the simulator’s root certificate.
2. Keep the add-on in Test mode, enter the test Swish number, paste the test certificate, key and passphrase, and paste the root certificate into the Test server root certificate field. Save: the connection line turns green.
3. Submit your form with a mobile number. The simulator answers like Swish and posts the callback to your site.
4. Check the entry: Paid, with the payment reference and a “Test — test payment” note. Try a partial refund.
5. Submit again without a number to see the app button and QR code on the payment page.

Going live

• Enter your live Swish number, paste your own certificate and key (and passphrase), leave the live server root certificate empty, switch to Live and save.
• Make one small real payment with your own phone and refund it.
• Your site must be on https and reachable from the internet for callbacks.

For developers

The filter gravityextra_swish_message changes the message shown in the Swish app (kept to the characters Swish accepts and 50 characters). The amount, the currency, the reference, the Swish number and the callback address are always set by the add-on. gravityextra_swish_min_minor and gravityextra_swish_max_minor change the smallest (1.00 SEK by default) and lower the largest payment in öre, gravityextra_swish_payments_per_hour changes the hourly cap of new payments (300 by default) and gravityextra_swish_temp_dir sets a private folder for the short-lived certificate files.

// Show the course date in the Swish app for one form (ID 7).
// The amount, currency, reference and Swish number cannot be changed here.
add_filter( 'gravityextra_swish_message', function ( $message, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $message;
    }
    return 'Kurs ' . rgar( $entry, '9' ) . ' bokning ' . rgar( $entry, 'id' );
}, 10, 4 );

How it differs

• It connects to your own Swish for merchants agreement directly, with your certificate, so the money goes straight to your bank account under your own agreement.
• The payment request is created on your server from the saved entry: the amount, the currency, the reference and your Swish number never come from the browser.
• Swish callbacks are not signed, so the add-on never trusts one on its own. It reads the payment request back from Swish over your certificate connection, and only a paid request with the entry’s reference, your Swish number, the amount and SEK marks the entry Paid.
• The customer is never left on a dead end: after a declined, cancelled or timed-out request, the payment page offers a new request to the phone or by QR code, for the same order and amount.
• Your certificate and key are stored encrypted, never shown again, and written to private temporary files only for the length of each call.

Troubleshooting

Uninstall

Deleting the add-on from the Plugins screen removes its settings (including the encrypted certificate, key and passphrase), schedules and temporary data. Entries, notes and payments at Swish stay as they are.

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