Gravity Forms PagBank Premium Add-on Setup Guide

The Gravity Forms PagBank Premium Add-on lets your Gravity Forms take payments in Brazilian reais through PagBank (PagSeguro). When a form is submitted, the add-on creates a PagBank checkout for the exact total and sends the customer to the PagBank payment page, where they pay by credit card, debit card, PIX or boleto. When PagBank notifies the payment, the add-on checks the signature, reads the order back from PagBank 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 the sandbox 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 an amount in reais with at most two decimals and at least R$ 1,00.
2. The entry is saved with the status Processing. The add-on creates a PagBank checkout on your server: one item for the total in centavos, a unique order reference, the payment methods and installments of the feed, the customer’s details when you map them, a signed return link and the notification address.
3. PagBank answers with the checkout and its payment page. Before the customer is sent there, the add-on checks that the checkout is active, carries the right reference and total, and that the page is on a PagBank address. If anything differs, the customer is told that nothing was charged and the entry is marked Failed.
4. The customer pays on the PagBank page by card, PIX or boleto. Payment details are entered on PagBank and never reach your website.
5. PagBank posts the order to your site, signed with your token. The add-on checks the signature, reads the order back from PagBank and updates the entry. The customer is sent back to your form page, where the confirmation appears as soon as the payment is confirmed.
6. The payment page stays open for two hours. A page that expires without a payment ends as Cancelled, and no money is taken.

Install and activate

1. In WordPress go to Plugins → Add New → Upload Plugin, upload the zip and activate it.
2. Open Forms → Settings → PagBank, 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 Brazilian Real.

Settings

Open Forms → Settings → PagBank. Each mode has its own token; only the token of the mode you choose is used for new checkouts. An entry always keeps the mode it was created in, so a checkout started in Test mode is still read from the sandbox after you switch to Live.

Getting your tokens

1. Sandbox: sign in to the PagBank developer portal, open Tokens and copy your token into the Test field, then save. The connection line turns green when PagBank accepts it.
2. Production: in your PagBank account open Sales → Integrations and click Generate token. Copy it into the Live field when you are ready for real payments.

Notifications and their signature

Every checkout tells PagBank where to post its notifications, so you do not set anything up in PagBank. PagBank signs each notification: the x-authenticity-token header is the SHA-256 of your token, a hyphen and the exact body. The add-on recomputes it with the token of the Test or Live mode and refuses anything that does not match. Even a signed notification is only a signal: the order is always read back from PagBank before the entry changes.

The feed

Open your form, go to Settings → PagBank and add a feed. Choose Products and Services or Donations and the payment amount (usually the form total). Then map the customer fields: the full name, email, CPF or CNPJ and mobile number fill in the PagBank page so the customer types less (they can still change them there). A CPF or CNPJ is checked before the entry is saved, and a Brazilian mobile number typed as (11) 98765-4321 or +55 11 98765-4321 is sent in PagBank’s format; other numbers are left out.

• Item name: shown on the PagBank page, up to 100 characters. Merge tags work; the default is the form title and the entry number.
• Payment methods: credit card, debit card (PagBank must approve it for your account), PIX and boleto. When none is ticked, credit card, PIX and boleto are offered.
• Installments: up to 12 interest-free installments on credit card. You pay the installment fee, so the customer pays exactly the form total and the amount always matches the entry.
• Statement name: optional, up to 17 letters, digits and spaces on the customer’s card statement.
• 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 PagBank page

Use Gravity Forms product, quantity, option and total fields as usual. The amount sent to PagBank is the total Gravity Forms calculated on your server, in centavos, 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 PagBank page next.

When the customer comes back, they see your normal confirmation if the payment is confirmed. A PIX payment usually arrives within seconds, and a short waiting message checks again by itself. A boleto is paid later at the bank, so the customer sees a message that the entry updates by itself once PagBank confirms the payment.

Payment statuses

The entry screen

Every PagBank entry has a PagBank box on the right with the status, the amount, the checkout id, the order id, the order reference, the payment method, the charge id, the response code if a card was declined, and the refunded total. Test payments carry a Test badge.

• Refresh status reads the checkout and its orders from PagBank again and applies them.
• Refund with PagBank sends a full or partial refund to the customer. Type the amount in reais (149,90 or 149.90 both work; the field starts with the amount left) and confirm.

Refunds

Before a refund is sent, the add-on reads the order from PagBank and checks that it is paid for the entry amount, and that the refund fits what is left after earlier refunds (from R$ 1,00). Each refund form can be used once, so a double click or a reloaded page cannot refund twice. The amount is reserved before PagBank is asked, and the refund is recorded on the entry, as a transaction with a note, as soon as the refunded total PagBank reports covers it. If PagBank does not answer, the amount stays reserved and the status check settles it. When the whole amount has been refunded the entry becomes Refunded. Refunds you make in your PagBank account are recorded too, the next time the order is read.

Testing in the sandbox

1. Leave the mode on Test and save your sandbox token.
2. Open the form on your site, fill it in and continue to payment.
3. On the PagBank sandbox page, pay with one of the test cards or the PIX test flow from the PagBank developer documentation.
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 watch it appear as a refund transaction.
6. Start another payment and leave the PagBank page without paying: the entry ends as Cancelled when the page expires.

Going live

1. Generate the production token in your PagBank account and paste it into the Live field.
2. Make sure your site runs on https, so the notification address is sent with every checkout.
3. Switch the mode to Live and save. The connection line should say Connected to PagBank (Live, production).
4. Make one small real payment, check the entry and refund it from the entry screen.

For developers

• gravityextra_pagbank_checkout_fields filters the checkout before it is sent. The item name and description, the customer block, the statement name, the payment methods and the redirect wait can be changed; the amount, the quantity, the reference, the installment terms and the return and notification addresses cannot.
• gravityextra_pagbank_max_centavos lowers the largest checkout the site accepts (PagBank’s own item maximum is R$ 9.999.999,00).
• gravityextra_pagbank_rate_limit changes the per-visitor limits (payment starts 10, return page 30, notifications 120 per minute).
• gravityextra_pagbank_payments_per_hour changes the site-wide cap of new checkouts per hour (300).
• gravityextra_pagbank_webhook_base changes the base address of the notifications (for a site behind a proxy).

// Add the class date to the item description on the PagBank page for one form (ID 7).
add_filter( 'gravityextra_pagbank_checkout_fields', function ( $checkout, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $checkout;
    }
    $checkout['items'][0]['description'] = 'Class on ' . rgar( $entry, '8' );
    return $checkout;
}, 10, 4 );

How it differs

• Nothing is trusted from the browser or the notification body: every result is read back from PagBank and checked against the entry’s reference and amount before the entry changes.
• Notifications must carry the SHA-256 signature made with your token; anything else is refused, and a repeated notification is dropped, so a payment can only be completed once.
• The token is checked with PagBank when you save, stored encrypted, and each entry stays with the mode it was created in.
• Installments are interest-free, so the amount PagBank collects always equals the form total.
• Refunds from the entry screen are checked against PagBank first, protected by a one-time form, reserved while PagBank processes them and reconciled with the refunded total PagBank reports; refunds made in your PagBank account are recorded too.
• Payment creation, the return page and notifications have per-visitor limits, and new checkouts have an hourly cap, so a flood of form posts cannot create checkouts without end.

Troubleshooting

Uninstall

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

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