VibeFox PagSeguro for Adobe Commerce — Ayuda

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension.

Currency: Brazilian Real (BRL). The payment method is shown only when the cart is in BRL. Your store can have another base currency, as long as the customer's cart currency is BRL.

HTTPS: your store 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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-pagseguro-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PagseguroPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PagseguroPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox PagSeguro Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the sandbox token and, to take real payments, the production token. Set Enable to Yes and click Save Config. Make test payments with Sandbox Mode = Yes, then set it to No to take real payments.

The module adds the PagSeguro / PagBank payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the PagBank payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox PagSeguro Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete Data on Uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a title of 1 to 128 characters. for an empty or too long Title, Sort order must be a whole number. and Order total must be zero or greater. for Minimum Order Total or Maximum Order Total.

The settings are one list of fields. Below them the group shows the Notification URL and, while Enable is Yes, the state of the current mode: SANDBOX MODE: no money is transferred. or LIVE mode uses the production token., Enter the token of the active payment mode. when the token of the current mode is missing (PagBank is then hidden at checkout), and the reminder PagBank supports Brazilian Real (BRL) only.

General

Enable: shows or hides PagBank at checkout. It is shown only when the token of the current mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: PagSeguro / PagBank. Required, at most 128 characters. While Sandbox Mode is Yes, (TEST MODE) is added after the title.

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

PagBank account

Sandbox Mode: new payments go to the PagBank sandbox with the sandbox token, and customers see SANDBOX MODE: no money is transferred. under the payment method. Sandbox and production tokens only work in their own environment. Existing payments always use their original environment: status checks and refunds of an order use the environment and token in which its payment was created. Default: Yes.

Sandbox token: the token of your PagBank sandbox account. Used while Sandbox Mode is Yes.

Production token: the PagBank production token, from PagBank account > Venda online > Integrações > Gerar token. Used when Sandbox Mode is No. Keep it secret.

Magento stores the tokens encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved token, type a new value to change it. To delete a saved token, clear the field and click Save Config.

Conditions

Payment from Applicable Countries: All Allowed Countries offers PagBank for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer PagBank only for billing addresses in these countries.

Minimum Order Total: offer PagBank only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer PagBank only up to this order total, in the base currency. Empty means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number; negative values are allowed.

Payment notifications

Notification URL: every payment tells PagBank where to report status changes, so there is nothing to configure in PagBank. The group shows the URL: it is the storefront address of the default store view and looks like https://your-store/wcppagsegurogateway/checkout/webhook/. Each payment sends the address of the store view where the order was placed. 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 environment in which the payment was created; an invalid signature is rejected. The notification body itself is never trusted: the module always reads the checkout and the PagBank order from the PagBank API (status, amount, currency) before an order is changed. Without notifications, the order is confirmed when the customer returns to the store after paying.

Advanced

Debug log: writes PagBank requests and notifications to var/log/wc_psg_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors are always logged; tokens and customer data are excluded. Default: No.

Log: below the settings the group shows the size and the latest entries of the log. Click Clear log to empty it.

Delete Data on Uninstall: when Yes, uninstalling the module with its data deletes the gateway settings, its cache and the log (see Uninstall). The license key is always removed. The PagBank payment history always stays, so old orders can still be refunded. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default PagSeguro / PagBank) and sees the description. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a PagBank checkout for the 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 VAT number of the billing address and a Brazilian phone number are filled in when the order 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 after 120 minutes.

After paying, the customer returns to your store. The order is marked paid only after PagBank confirms it: the module reads the payment from the PagBank API when the notification arrives or when the customer comes back, and a return alone never marks an order paid. Magento then creates the invoice with the PagBank charge ID, the order goes to Processing and the order e-mail is sent. The customer sees the standard order success page with PagBank payment confirmed. For a generated boleto or PIX, or a payment in analysis, the message is Awaiting PagBank payment confirmation (PIX / boleto or card in analysis). and the order is confirmed as soon as PagBank reports the payment. A customer who comes back in another browser lands on the home page with the same message. If PagBank cannot be reached when the customer comes back, a page shows We are confirming your PagBank payment. Do not pay again. with a Check again link.

If the payment was not completed (the customer left the PagBank page, the card was declined or the page expired), the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Your PagBank payment was not completed. You can try again.

When the customer places the order again, the previous PagBank checkout of the cart is deactivated first, so it can no longer be paid. If PagBank does not confirm the deactivation, no new payment is created. A payment made on the previous page before that still counts for the cart. A cart with a payment that is paid, waiting (PIX, boleto, analysis) or on review cannot be paid again.

If PagBank cannot start the payment, the customer is back in the cart with PagBank could not start payment. Please check your order before retrying. When no request was sent to PagBank for the cart yet, the order is cancelled and the cart is restored. When PagBank refused or did not answer the request, the order stays in Pending Payment for you to check; the technical reason is written to the log.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its open PagBank checkout is deactivated and can no longer be paid. If PagBank is confirming the payment of that order at the same moment, the cron leaves the order for its next run and goes on with the other orders.

The module works with the standard Magento checkout. It 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. PagBank is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to PagBank, but PagBank has not confirmed the payment yet, or a boleto or PIX was generated, or the payment is in analysis (with the note Awaiting PagBank payment confirmation (PIX / boleto / analysis).). There is no invoice.

Processing: the payment was confirmed with the expected amount and currency. The invoice is created with the PagBank charge ID as the transaction ID, and a note shows the charge and how it was confirmed (webhook, return or admin sync). For sandbox payments the note adds SANDBOX MODE: no money was received; do not ship this order.

On Hold: PagBank reported a different amount or currency than the order total, or the charge was already refunded; a card payment was authorized but not captured (capture it in the PagBank dashboard); or a payment arrived for an order you had put on hold. No invoice is created. The note explains it. Because the money is at PagBank, the order is moved to Processing before the hold, so Unhold returns it to Processing and Magento does not cancel it as an expired Pending Payment order. A charge captured later puts the order on hold again for Accept exact verified payment after review. If you decide not to keep such an order, refund or cancel the charge in PagBank, then use Unhold and Cancel.

Canceled: the payment was not completed or could not be started, a waiting PIX or boleto was cancelled by PagBank, or the order was cancelled in Magento. If a payment arrives after the order was cancelled, the order is not reopened; a note asks you to check the stock and accounting or to refund the payment in PagBank.

Closed: the payment was fully refunded with a credit memo.

Every PagBank status is applied once, so repeated notifications or returns add no notes or invoices. If a second payment arrives for a cart that is already paid, the paid order is not changed and a note asks you to refund the duplicate in the PagBank dashboard. The notes are order comments that the customer does not see.

PagBank payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, after the payment, PagBank order (the charge ID), Payment method and Environment. The customer sees only the payment method title. Below it the PagBank payment history block lists every PagBank checkout of the order with its environment, status, amount paid and refunded, and the refund operations. It is shown also when the module is disabled.

Sync PagBank payment reads the payment from PagBank again and applies its status, for example when a notification was missed. For an order on hold after a review case with a single PagBank attempt, the block also offers Accept exact verified payment after review, which works only when PagBank shows exactly one paid, unrefunded charge with the exact order total; the order is then released and invoiced. Refund actual payment; reconcile native accounting refunds the entered amount of a review payment in PagBank without a credit memo, for example after an amount mismatch; reconcile the order in Magento manually. These buttons need the Admin right to edit orders. If an action fails, the page shows PagBank action failed. Check the dashboard and payment history before trying again.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through PagBank. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through PagBank.

The refund is made in BRL with the exact credit memo amount, up to the amount PagBank charged minus the amounts already refunded. It is sent in the environment and with the token in which the payment was made. The refund is recorded only when PagBank confirms it. If PagBank refuses it, Magento shows the error, for example PagBank refund failed. Check the dashboard before retrying. or Refund exceeds the actual remaining PagBank charge., and the credit memo is not created. Refunds of boleto payments and partial refunds of PIX follow PagBank's rules. If a refund was sent but its result is unclear, the next refund of the order is refused with An earlier refund requires manual reconciliation before another refund. until you check it in PagBank. A full refund closes the order. Refunds are available once PagBank has confirmed the payment and the order has an invoice.

Refunds made in the PagBank dashboard are seen with the next notification and added to the order notes once (PagBank dashboard refund: … centavos.). The order and credit memos are not changed automatically. Create a credit memo with Refund Offline or update the order manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PagSeguro Gateway is the first row of the VibeFox PagSeguro Gateway group in Stores > Configuration > Sales > Payment Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-pagseguro and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store 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, no PagBank payment is created, the order is cancelled, the cart is restored and the customer sees PagBank could not start payment. Please check your order before retrying. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

PagBank does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the token of the current mode is set (Sandbox token with Sandbox Mode = Yes, Production token with No) and that the cart currency is BRL. The group shows Enter the token of the active payment mode. when the token is missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

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. Check that your store is reachable from the internet over HTTPS at the Notification URL, and turn on Debug log to see the notifications. You can also click Sync PagBank payment on the order page. A PIX, boleto or payment in analysis stays in Pending Payment until PagBank reports it as paid.

The notification answers Invalid signature.: the x-authenticity-token does not match the token of the environment in which the payment was made, or that token is not saved. Check that the right token is in the settings for the website of the order.

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

The notification answers Order not found.: the notification is for a cart that was not paid with this module in this store. Nothing is changed.

The notification URL shows POST required. in the browser: this is normal. The URL accepts only notifications from PagBank.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. The order is confirmed when the customer returns, with Sync PagBank payment or with a later notification.

The customer is back in the cart with PagBank could not start payment. Please check your order before retrying.: turn on Debug log and look at the Log below the settings. Common reasons are a missing or rejected token of the current mode, CPF/CNPJ or other billing details that PagBank does not accept, or an earlier PagBank request of the same cart without a clear result, which you have to check in the PagBank dashboard first.

Order is On Hold after payment: read the order notes (see Order statuses), compare the amounts in PagBank, then fulfil the order or refund the payment.

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 Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded with a credit memo; use Refund actual payment; reconcile native accounting or refund it in the PagBank dashboard.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_PagseguroPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PagseguroPayment to remove the data, then bin/magento module:disable Vibefox_PagseguroPayment, delete the folder app/code/Vibefox/PagseguroPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete Data on Uninstall is Yes, the gateway settings, its cache and the log are removed too. If it is No, the settings are kept for a re-install. The PagBank payment attempts and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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