Gravity Forms Przelewy24 Premium Add-on Setup Guide

The Gravity Forms Przelewy24 Premium Add-on connects Gravity Forms to your own Przelewy24 account. When a form with a Przelewy24 feed is submitted, the add-on registers a Przelewy24 transaction for the exact total Gravity Forms calculated and sends the customer to the Przelewy24 payment page, where they choose how to pay: a fast bank transfer (pay-by-link), BLIK, a card, or any other method active on your account. Payment details are entered at Przelewy24, never on your website.

When Przelewy24 reports the payment, the add-on checks the signature with your CRC key, reads the transaction back from Przelewy24, verifies it (the confirmation Przelewy24 needs before it settles the money) and only then marks the entry Paid. This guide covers installation, every setting, the feed, what the customer sees, the payment statuses, refunds, testing in the sandbox 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 → Przelewy24 and activate your licence key. The Przelewy24 settings appear once the licence is active.
3. Set the Gravity Forms currency (Forms → Settings) to Polish Zloty, or to EUR, GBP or CZK if Przelewy24 has enabled that currency on your account.

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

Currencies and amounts

Polish złoty, euro, pound sterling and Czech koruna are all built into Gravity Forms with two decimals, so prices such as zł 1.250,00, 1.250,00 €, £1,250.00 or 1 250,00 Kč are read correctly both in the browser and on the server. The add-on sends the total to Przelewy24 in the smallest unit, as Przelewy24 asks: zł 149,90 becomes 14990 grosze. Totals with more than two decimals, below 1.00 or in a currency that is not enabled are refused before anything is sent to Przelewy24.

When you type a price in a product field, use the format Gravity Forms shows (for example zł 1.250,00) or a plain number without a thousands separator (1250). A bare 1.250 is read by Gravity Forms as 1.25 in every currency that uses a comma as the decimal mark.

Settings

When you save, the add-on asks Przelewy24 to confirm the shop ID and API key of each mode (a check that changes nothing in your account). Keys Przelewy24 refuses are not saved, and the error tells you which mode to check. The CRC key cannot be checked without a transaction: if it is wrong, Przelewy24 refuses the first payment, the entry is marked Failed and the note names the CRC key.

Notifications from Przelewy24

Every transaction carries the address Przelewy24 calls when the payment is made (https://your-site/?callback=gfprzelewy24), so there is nothing to set up in the Przelewy24 panel. For each notification the add-on:

1. limits how many notifications one address can send per minute;
2. finds the entry by the session reference it created for that payment, and checks the signature with the CRC key of the mode the payment was made in;
3. checks that the merchant, the shop, the amount and the currency are the entry’s own;
4. reads the transaction back from Przelewy24 and verifies it, then marks the entry Paid and sends the held notifications.

A notification with a wrong signature is refused. If verification fails (for example Przelewy24 is briefly unreachable), the add-on answers with an error, so Przelewy24 sends the notification again a few minutes later. A repeated notification never completes a payment twice.

The feed

Open the form, go to Settings → Przelewy24 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: Przelewy24 sends its payment confirmation there, up to 50 characters). First name, last name, address, city, postal code, country and phone are optional and help the customer on the Przelewy24 page.
• Description: shown with the transaction at Przelewy24. Merge tags work; the default is {form_title} #{entry_id}.
• 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 registers the transaction and sends them to the Przelewy24 payment page in the language you chose, where they pick a payment method and pay. Przelewy24 then sends them back to the form page. The add-on reads the payment from Przelewy24 and shows your confirmation as soon as the payment is verified. While a bank transfer is still on its way, the page shows “Confirming your payment” and checks again by itself every few seconds. If the customer cancelled, the page says no payment was received and that they have not been charged, with a link back to the form.

Payment statuses

The entry screen

Every entry paid through Przelewy24 has a Przelewy24 box with the status, the amount, the Przelewy24 transaction number, the session reference, the payment method number, the transfer title and any refunds. Sandbox payments carry a “Sandbox — test payment” badge. Refresh status reads the transaction and its refunds from Przelewy24 again (and verifies a payment that is still waiting for it). 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 Przelewy24. Amounts can be typed as 149,90, 1.250,00 or 1250.00. The add-on first reads the transaction from Przelewy24 to make sure it is paid and verified with the entry amount, then sends the refund. Przelewy24 makes refunds in the background, so the entry shows “Refund requested” until Przelewy24 confirms it with a signed refund notification or the status check sees it. The refund is then recorded once. 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 Przelewy24 does not answer, the request stays reserved (“do not refund again”) and the status check records it if Przelewy24 made it, or frees it after an hour with a note.
• If Przelewy24 rejects a refund, the reservation is released with a note.
• Refunds made in the Przelewy24 panel are recorded when you click Refresh status.
• Staff need the Gravity Forms “edit entries” permission; administrators always can.

Testing in the sandbox

1. In the Przelewy24 panel, open My account → SANDBOX account to switch the sandbox on, then copy the sandbox merchant ID, CRC key and API key from the sandbox panel.
2. Keep the mode on Sandbox, paste the three values and save. The connection line should say “Connected to Przelewy24 (Sandbox)”.
3. Add a feed, open the form on a page that Przelewy24 can reach over the internet, and pay a small amount on the sandbox payment page.
4. Check that the entry becomes Paid, the transaction number appears in the Przelewy24 box, and the payment appears in the sandbox panel.
5. Make a partial refund and click Refresh status a little later to see it confirmed.

Going live

• Paste the live merchant ID, CRC key and API key from the live panel and switch the mode to Live.
• Make sure the site uses https and is reachable from the internet, so Przelewy24 can send its notifications.
• Make one small real payment and refund it to confirm everything end to end.
• Entries started in the sandbox keep using the sandbox keys, so switching modes never mixes the two.

For developers

The filter gravityextra_przelewy24_register_fields can change the description, the customer details, the language, the payment time limit (timeLimit, minutes, 0-99), the channel bitmask (channel), a payment method number (method) and the transfer title (transferLabel). The amount, currency, session, merchant and shop, the return and notification addresses and the signature are always set by the add-on. Other filters: gravityextra_przelewy24_max_cents (lower the largest payment), gravityextra_przelewy24_rate_limit, gravityextra_przelewy24_payments_per_hour and gravityextra_przelewy24_notify_base (the base of the notification address, for sites behind a proxy).

// Give customers of one form (ID 7) 15 minutes to pay and show only BLIK and bank transfers
// (channel bitmask 8192 + 2). The amount, currency, session and addresses cannot be changed here.
add_filter( 'gravityextra_przelewy24_register_fields', function ( $fields, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $fields;
    }
    $fields['timeLimit']   = 15;
    $fields['channel']     = 8192 + 2;
    $fields['description'] = 'Warsztaty ' . rgar( $entry, '8' ) . ' / zgłoszenie ' . rgar( $entry, 'id' );
    return $fields;
}, 10, 4 );

How it differs

• It connects to your own Przelewy24 merchant account directly with the Przelewy24 REST API, so the money is settled by Przelewy24 to your account under your own Przelewy24 agreement, and the payment page shows every method you have switched on there.
• It runs the verification step Przelewy24 asks for on every payment, and only a successful verification marks the entry Paid. Without it Przelewy24 does not settle the money.
• It never trusts the return address or the notification on its own: the notification signature is checked with your CRC key, the transaction is read back from Przelewy24, and the session, amount and currency must match the entry.
• Refunds, including several partial refunds, are made from the Gravity Forms entry and recorded only when Przelewy24 confirms them.

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 transactions at Przelewy24 are kept.

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