How to Take PagBank Payments with Gravity Forms (Card, PIX, Boleto)

PagBank, the payment service many Brazilians still know as PagSeguro, lets businesses take card, PIX and boleto payments on a page hosted by PagBank. If your class bookings, orders, registrations, fees or donations already run on Gravity Forms, you do not need a full shop to take those payments: the Gravity Forms PagBank Premium Add-on connects your forms to your own PagBank account. The customer fills in the form, pays on the PagBank page and comes back to your confirmation, and the entry is marked as paid only after PagBank’s signed notification has been checked and the order read back from PagBank. This guide shows how to set it up step by step, how to test it in the PagBank sandbox, and what happens behind the scenes.

Why take PagBank payments through Gravity Forms?

A form is often the most natural way to sell something that is not a product on a shelf: a seat in a class, a consultation fee, an event pass, a school or course fee, a deposit for a custom order. Gravity Forms already handles the fields, the conditional logic and the total. What it needs is a safe way to collect the money in reais. With PagBank your customers pay the way they already pay every day: PIX from their banking app, a credit card in installments, or a boleto at the bank, all on a page hosted by PagBank. With the add-on you keep everything else in Gravity Forms: the entry, the notes, the notifications and the refunds.

• Customers pay on the PagBank page, so card numbers and bank logins are never typed into your website.
• The amount is the total Gravity Forms calculated on your server, in reais, to the centavo.
• Entries show the real payment status, read from PagBank, not what the browser says.
• Refunds are one click away on the entry screen.

Forms that work well with PagBank

• Classes and workshops: seats, materials and options with quantities.
• Consultations and services: a fixed fee or a calculated amount for a booking.
• Schools and courses: enrolments, course fees, exam and event registrations, with installments on card.
• Clubs, NGOs and associations: memberships, event passes and donations (choose Donations in the feed).
• Made-to-order products: options that change the price, paid before work starts.

What you need

• Gravity Forms 2.9 or newer, with the currency set to Brazilian Real.
• A PagBank account: a sandbox token from the PagBank developer portal for testing, and a production token from your account (Sales → Integrations) for live payments.
• The Gravity Forms PagBank Premium Add-on and a license: one site $49 a year, five sites $69 a year, unlimited sites $199 a year.
• A public https site, so PagBank notifications can reach it.

Step 1: Install the add-on and connect your account

Upload and activate the add-on, then open Forms → Settings → PagBank and activate your license. Leave the mode on Test and paste your sandbox token. When you save, the add-on makes a read-only call to PagBank with it; the connection line turns green and the token is stored encrypted and shown masked from then on. There is no notification address to copy into PagBank: the add-on sends it with every checkout.

Step 2: Build the form

Build the form as you would for any payment: product fields with prices and quantities, options, a total, and the customer’s name, email, mobile number and CPF. The customer fields are optional, but when you map them the PagBank page is filled in for the customer, which saves typing on a phone. A CPF or CNPJ with wrong check digits is caught on your form, before the customer leaves your site. Change the submit button text to something like Continue to payment so customers know what comes next.

Step 3: Add a PagBank feed

In the form settings open PagBank and add a feed. Pick Products and Services (or Donations), the form total as the amount, and map the customer fields. Name the item the customer sees on the PagBank page (merge tags such as the form title and the entry number work), choose the payment methods, and, if you like, offer up to 12 interest-free installments on credit card. Tick the option to send form notifications only after the customer has paid, so your team does not start work on unpaid bookings.

Step 4: Test in the sandbox

Open the form on your site, fill it in and continue to payment. On the PagBank sandbox page, pay with a test card or the PIX test flow from the PagBank developer documentation. You come back to your confirmation, and the entry shows Paid with a Test badge. Try the other paths too: leave the page without paying and the entry ends as Cancelled when the page expires; choose boleto and the entry waits as Processing until PagBank reports the payment. Then refund part of the paid test payment from the entry screen and watch it appear as a refund on the entry.

What happens behind the scenes

When the form is submitted, the add-on creates the PagBank checkout from your server with one item for the total in centavos, a unique order reference, the payment methods, the installment terms, the customer’s details, a signed return link and the notification address. PagBank answers with the checkout and its payment page, and the add-on checks it before sending the customer anywhere: the checkout must be active, carry the right reference and total, and the page must be on a PagBank address, or the customer is told nothing was charged.

After the payment, PagBank posts the order to your site. Its x-authenticity-token header is a SHA-256 signature made with your token and the exact body; the add-on recomputes it and refuses anything that does not match. Even then the notification decides nothing on its own: the add-on reads the order from PagBank, and the entry is marked Paid only when the order carries the entry’s reference and the paid amount equals the entry amount. A repeated notification is dropped, so a payment can never be completed twice. The return page, a status check every five minutes and the Refresh status button read PagBank the same way, which is how a boleto paid days later still updates the entry.

A worked example

A pottery studio in São Paulo sells three-hour wheel-throwing classes at R$ 250,00 and glaze-and-firing add-ons at R$ 89,90 through a Gravity Forms booking form. Mariana books two seats and one add-on. Gravity Forms shows a total of R$ 589,90; the add-on creates a PagBank checkout with one item of 58990 centavos named “Pottery class booking #412”, her name, email, CPF and mobile number filled in, and up to three interest-free installments on card. She pays by PIX on the PagBank page and lands back on the studio’s confirmation: “Thank you! Your class is booked and paid.” Behind the scenes, the entry was marked Paid only after the signed notification was checked and PagBank confirmed the order paid for 58990 centavos. The held “Booking received” email went to the studio at that moment, not before. A week later Mariana can only come alone, so the studio refunds one seat, R$ 250,00, from the entry screen; the refund is recorded on the entry and the rest stays Paid.

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 before it changes.
• Notifications must carry the SHA-256 signature made with your token; forged or repeated notifications change nothing.
• The token is checked with PagBank when you save, and every entry keeps the mode (sandbox or production) it was created in.
• Installments are interest-free, so the amount collected always equals the form total.
• Refunds are checked against PagBank first, protected by a one-time form and reconciled with what PagBank reports; refunds made in your PagBank account show up on the entry.
• Per-visitor limits and an hourly cap stop a flood of form posts from creating checkouts without end.

Tips for smooth payments

• Map the customer’s name, email, CPF and mobile number: the PagBank page is filled in and the customer pays faster.
• Offer PIX: most customers pay within seconds from their banking app.
• Keep boleto on for customers who prefer it, and let the status check follow those payments for you.
• Hold form notifications until payment so your team only sees paid bookings.
• Use the Payment Completed notification event to send the customer a receipt from your site.

Step 5: Go live

Generate the production token in your PagBank account (Sales → Integrations → Generate token), paste it into the Live field, switch the mode to Live and save. Make sure the site runs on https so the notification address is sent with every checkout. Make one small real payment, check the entry, and refund it from the entry screen. Entries created in Test mode keep reading from the sandbox, so nothing mixes.

Questions

Do payment details reach my website?

No. The customer pays on the PagBank page. Your site only receives the PagBank checkout and order ids, the status, the payment method and the charge id.

Can I take payments in other currencies?

PagBank payments are in Brazilian reais, so the Gravity Forms currency must be BRL. Forms in another currency are refused before anything is sent to PagBank.

What if a notification never arrives?

The return page reads the checkout when the customer comes back, the status check reads every order PagBank has reported every five minutes, and you can click Refresh status on the entry at any time.

Can I refund part of a payment?

Yes. Type the amount on the entry screen; the add-on checks it fits what is left after earlier refunds. The entry becomes Refunded when the whole amount has been refunded.

Are subscriptions supported?

This add-on handles one-off payments: products, services and donations.

Get started

Read the setup guide for every setting, or get the Gravity Forms PagBank Premium Add-on and take your first PagBank payment through Gravity Forms today. Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year.