VibeFox PagSeguro for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Currency: Brazilian Real (BRL). The payment method is hidden at checkout when the store (or, on the Pay for order page, the order) currency is not BRL.

HTTPS: your site must be reachable from the internet over HTTPS so that PagBank can deliver payment notifications.

PagBank account: a production token for real payments and a sandbox token for tests. Production: log in to your PagBank account, open Venda online > Integrações and click Gerar token; PagBank sends the token by e-mail. Sandbox: create a sandbox account in the PagBank developer portal and copy its token. Sandbox and production tokens only work in their own environment.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_pagseguro_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the sandbox token and, to take real payments, the production token.

6. Turn on Enable / Disable and save. Make test payments with Sandbox Mode on, then switch it off to take real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > PagSeguro / PagBank. Under the title the page shows the current mode: SANDBOX MODE (payments are created in the PagBank sandbox, no real charges) or LIVE (payments are created with the production token). It warns you when the token of the current mode is missing (the payment method is then hidden at checkout) and when the store currency is not BRL. In the list of payment methods, PagBank is marked as needing setup until the token of the current mode is entered, and a test mode badge is shown while sandbox mode is on.

General

Enable / Disable: Enable PagSeguro/PagBank payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: PagSeguro / PagBank.

Description: the text shown under the payment method at checkout. Default: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

PagBank account

The section explains where to get the tokens and links to your PagBank account and to the PagBank page about tokens.

Sandbox Mode: Enable sandbox/test mode (no real charges). New payments go to the PagBank sandbox with the sandbox token, and a SANDBOX MODE note is shown at checkout. Status checks and refunds of an order always use the environment and token in which its payment was created. Default: on.

Sandbox token: the PagBank sandbox token. Used while sandbox mode is on.

Production token: the PagBank production token. Used when sandbox mode is off. Keep it secret.

The single token of version 1.0 is moved automatically: if sandbox mode was on, it becomes the sandbox token, otherwise it stays the production token.

Payment notifications

Every payment tells PagBank where to report status changes, so there is nothing to configure in PagBank. The section shows the notification URL. It looks like https://your-site/wc-api/webhook_wc_pagseguro/. The address must be reachable from the internet over HTTPS.

Notifications that carry an x-authenticity-token header are checked with the token of the order's environment; an invalid signature is rejected. The notification body itself is never trusted: the plugin always reads the checkout and the PagBank order from the PagBank API (status, amount, currency) before the order changes.

Advanced

Debug log: Log API requests and notifications writes details to WooCommerce > Status > Logs, source wcp_pagseguro_gateway. Errors are always logged. Logs contain no tokens and no customer data. Default: off.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default PagSeguro / PagBank) and places the order. The plugin creates a PagBank checkout for the exact order total in BRL as one item, Order # with the order number and your store name, and sends the customer to the PagBank payment page. The customer's name and e-mail, the CPF or CNPJ from the fields of the Brazilian Market on WooCommerce plugin and a Brazilian phone number are filled in when the store has them; the customer can complete or correct them on the PagBank page. The customer pays with the methods enabled in your PagBank account, for example credit card, PIX or boleto.

The payment page expires 5 minutes before the WooCommerce Hold stock timer cancels the unpaid order (at least 10 minutes), or after 120 minutes when stock is not held.

After paying, the customer returns to the store. The return is checked the same way as a notification: the plugin reads the payment from the PagBank API, and a return alone never marks an order paid. A paid order, or a payment that is waiting (boleto, PIX, analysis), goes to the order received page; the order is confirmed by the notification if PagBank has not reported it yet.

If the payment was not completed, the customer goes back to the Pay for order page with The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. or The payment was declined by PagBank. Please try again with another card or payment method. If the payment was cancelled and the order with it, the customer goes to the cart with The PagBank payment was cancelled, so the order was cancelled.

When the customer pays again, the open PagBank checkout is reused if the amount and environment are the same and it does not expire within 10 minutes. Otherwise the previous checkout is deactivated, so it can no longer be paid. A payment made on the previous page before that still counts for the order.

If PagBank cannot start the payment, the customer sees a short message, for example PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. or Could not connect to PagBank. Please try again in a moment. The reason from PagBank is added to the order notes.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin has no on-site card form, no saved cards, no subscriptions or recurring payments and no split payments or marketplaces. Payment methods and installments are those configured in your PagBank account.

Orders and refunds

Order statuses

Pending payment: the customer was sent to PagBank and has not paid yet. A note shows the PagBank checkout ID and the environment. If the payment page expires without payment, a note says so and the status does not change.

Processing: the payment was confirmed. This is the standard WooCommerce status after payment; orders with only virtual downloadable products become Completed. The order note shows the amount, the payment method and the PagBank charge ID, which is also the transaction ID of the order.

On hold: a boleto or PIX was generated and is waiting for payment; the payment is in analysis; a card payment was authorized but not captured (capture it in PagBank); the paid amount or currency does not match the order; or a payment arrived after WooCommerce had cancelled the unpaid order (check stock, then complete the order or refund the payment in PagBank). The order note explains it.

Failed: the payment was declined. The customer can pay again from the Pay for order page.

Cancelled: the payment was cancelled, for example an expired boleto or PIX.

Refunded: the payment was fully refunded in the PagBank dashboard.

Every PagBank status is applied once, so repeated notifications or returns add no notes, e-mails or stock reductions. If a second payment arrives for an order that is already paid, a note asks you to refund it in PagBank.

Refunds

Open the order, click Refund, enter the amount and click Refund via PagSeguro / PagBank (the button shows your payment method title). Full and partial refunds are supported. The refund is sent in the environment and with the token in which the payment was made. A refund is recorded only when PagBank confirms it; otherwise WooCommerce shows the error, for example PagBank refund failed: ... or PagBank did not confirm the refund, and nothing is recorded. Refunds of boleto payments and partial refunds of PIX follow PagBank's rules. A successful refund is added to the order notes with the charge ID.

Refunds made in the PagBank dashboard are not imported as WooCommerce refund lines. A full refund sets the order to Refunded; a partial refund adds a note with the refunded amount, and you can add the refund to the order manually.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > PagSeguro / PagBank. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, PagBank is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

PagBank does not appear at checkout: check that the license is active, Enable / Disable is on, the token of the current mode is set (Sandbox token in sandbox mode, Production token in live mode) and the store currency is BRL. The settings page shows a warning in each case.

The payment went through, but the order stays Pending payment: PagBank has not reported the payment yet and the customer did not return to the store. The order is updated as soon as the notification arrives. Check that your site is reachable from the internet over HTTPS, and look at WooCommerce > Status > Logs, source wcp_pagseguro_gateway.

The notification answers Invalid signature: the x-authenticity-token does not match the token of the environment the order was paid in. Check that the right token is in the settings.

The notification answers Verification failed, retry later: the PagBank API could not be reached, the token of the order's environment is missing, or the order was being updated by another request at the same moment. PagBank retries the notification.

The notification answers Order not found: the order does not exist in this store or is paid with another payment method. Nothing is changed.

The customer sees This order is already being processed: a notification or the customer's return was updating the order at the same moment. The customer can try again after a moment.

The customer sees PagBank payments are temporarily unavailable: the token of the current mode is missing or PagBank rejected it.

The customer sees PagSeguro/PagBank only accepts payments in Brazilian Real (BRL): the order is in another currency.

Order is On hold with an amount/currency does not match note: PagBank reported a payment whose amount or currency differs from the order total, for example because the order was edited after the payment page was created. Compare the amounts in PagBank and complete or refund the order manually.

Refund fails with a message about the token: the payment was made in the sandbox or in production, and the token of that environment is missing or rejected. Enter the right token and try again.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the other options of the plugin and its logs are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, transaction IDs and PagBank data.

PagSeguro and PagBank are trademarks of their respective owner. This plugin is not affiliated with or endorsed by PagSeguro or PagBank.