VibeFox Pagar.me 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 when the store currency (or, on the Pay for order page, the order currency) is not BRL.

Pagar.me account: you need the secret keys of your Pagar.me account: the test key (sk_test_...) and, to go live, the live key (sk_...). They are in the Pagar.me dashboard under Development > Keys. Only the secret keys are used; the public key (pk_...) is not needed. Only the payment methods enabled in your Pagar.me account can be offered.

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_pagarme_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Pagar.me > 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 test secret key and, when you go live, the live secret key.

6. Create the webhook in the Pagar.me dashboard with the URL shown in the settings (see Configuration).

7. Turn on Enable / Disable and save. Make test payments with Test mode on, then turn it off to take real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Pagar.me. Under the title the page shows the current mode: TEST MODE (payments are created with the test secret key, no real charges) or LIVE. It warns you when the secret key of the current mode is missing (the payment method is then hidden at checkout), when the test key does not start with sk_test_, when the live key does not start with sk_ or is a test key, and when the store currency is not BRL. In the list of payment methods, Pagar.me is marked as needing setup until the key of the current mode is entered, and a test mode badge is shown while test mode is on.

General

Enable / Disable: Enable Pagar.me payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Pagar.me.

Description: the text shown under the payment method at checkout. Default: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

API keys

Copy the secret keys from the Pagar.me dashboard: Development > Keys. Pagar.me uses one API address for test and live payments; the key decides whether a payment is a test or real.

Test mode: Use the test secret key (no real charges). A TEST MODE note is shown at checkout while test mode is on. Status checks and refunds of an order always use the key of the mode in which its payment was created. Default: on.

Test secret key: the Pagar.me test secret key (sk_test_...). Used while test mode is on.

Live secret key: the Pagar.me live secret key (sk_...). Used when test mode is off. Keep it secret.

The single secret key of version 1.0 is moved automatically: a test key goes to Test secret key and test mode is turned on, otherwise it stays the live key and test mode is turned off.

Payment page

Payment methods: the methods offered on the Pagar.me payment page. Only choose methods enabled in your Pagar.me account. Default: Credit card, PIX and Boleto.

Credit card: authorized and captured at once.

PIX: instant payment by PIX.

Boleto: bank slip; the order waits on hold until it is paid.

Debit card: debit card payment.

Boleto due in (days): the number of days until the boleto is due, from 1 to 30. The order stays On hold until Pagar.me confirms the payment. Default: 3.

Payment notifications (webhook)

In the Pagar.me dashboard open Settings > Webhooks and create a webhook with the URL shown in this section. It looks like https://your-site/wc-api/webhook_wc_pagarme/. Copy it exactly as the settings show it.

Select these events:

order.paid: the Pagar.me order was paid.

order.payment_failed: the payment failed.

order.canceled: the Pagar.me order was canceled or expired.

charge.paid: a charge was paid, for example a PIX or boleto paid later.

charge.pending: a charge is waiting for payment, for example an issued boleto.

charge.refunded: a charge was refunded.

charge.chargedback: the card holder disputed a payment.

The webhook needs no password or signature. Its content is never trusted: the store takes only the Pagar.me order ID from it and reads that order from the Pagar.me API with the key of the mode it was created in. Notifications for orders of other stores on the same Pagar.me account are ignored. Without the webhook, PIX and boleto payments made later are only confirmed when the customer returns to the store.

Advanced

Debug log: Log API requests and notifications writes details to WooCommerce > Status > Logs, source wcp_pagarme_gateway. Errors are always logged. Logs contain no keys 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 Pagar.me) and places the order. A valid billing e-mail is required. The plugin creates a Pagar.me order for the order total in BRL, with the order lines, shipping and fees (or one line Order # with the order number when the lines cannot add up exactly), and sends the customer to the Pagar.me payment page. The customer's name, e-mail and, for Brazil, the phone number and billing address are passed to Pagar.me. CPF or CNPJ is taken from the fields of the Brazilian Market on WooCommerce plugin when they exist; otherwise the customer enters it on the Pagar.me page.

After paying, the customer returns to your store. The order is marked paid only after Pagar.me confirms it: the store reads the Pagar.me order from the API, and the paid amount and currency must match the order. A paid card payment, PIX or boleto marks the order paid. An issued PIX or boleto that is not paid yet puts the order On hold until Pagar.me confirms the payment by webhook.

If the customer comes back without paying, or the payment was declined or canceled, the customer goes to the Pay for order page with The Pagar.me payment was not completed. You can pay the order below. or The Pagar.me payment was declined or canceled. You can try again below.

When the customer pays again, the open Pagar.me payment page is reused if the amount and mode are the same; otherwise it is closed at Pagar.me before a new one is created. If the earlier attempt was paid in the meantime, or its PIX or boleto is still waiting, the order is updated without a new payment. If the earlier page cannot be closed, it stays matched to the order, so a payment made there is still recorded.

If Pagar.me cannot start the payment, the customer sees a short message, for example Could not connect to Pagar.me. Please try again in a moment., or the Pagar.me message about invalid billing details. The technical reason 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 card form inside your checkout, no saved cards, subscriptions or recurring payments, no installment rules, no split payments (marketplace), no authorize-only card payments and no Pagar.me Hub integration.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Pagar.me and has not paid or issued a PIX or boleto yet. A note shows the Pagar.me order ID and the mode.

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 Pagar.me order ID and the payment method. The transaction ID is the Pagar.me order ID (or_...).

On hold: a PIX or boleto was issued (or a card payment is in analysis) and is waiting for payment; or the boleto was paid only in part; or the paid amount or currency differs from the order; or a payment arrived after the order had been cancelled; or the order was paid at Pagar.me after the customer had switched it to another payment method; or a chargeback was opened on a paid order. The order note explains it. Review the order and set it to Processing, or refund the payment at Pagar.me.

Failed: the payment failed, or the Pagar.me order was canceled or expired (for example an unpaid boleto). Only the latest attempt of an unpaid order can fail it. The customer can pay again.

Refunded: the payment was refunded or canceled in Pagar.me.

Every Pagar.me status is applied once, so repeated webhooks or returns add no notes, e-mails or stock reductions. A paid order is never set back to pending or failed, and a cancelled or refunded order is never reopened. If a second Pagar.me order of the same WooCommerce order is paid, a note asks you to refund the duplicate in the Pagar.me dashboard.

Refunds

Open the order, click Refund, enter the amount and click Refund via Pagar.me (the button shows your payment method title). Full and partial refunds of card and PIX payments are supported, up to the amount still refundable at Pagar.me. The refund is sent with the key of the mode the payment was made in. A refund is recorded only when Pagar.me confirms it; otherwise WooCommerce shows the error, for example Pagar.me refused the refund: ... or Pagar.me did not confirm the refund, and no refund is recorded. A successful refund is added to the order notes with the charge ID.

Boleto payments can only be refunded to the customer's bank account. Refund them in the Pagar.me dashboard, then record the refund in WooCommerce manually, without Refund via Pagar.me.

A full refund or cancellation made in the Pagar.me dashboard arrives by webhook and sets the order to Refunded. A chargeback adds a note and puts a Processing or Completed order On hold.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Pagar.me. 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, Pagar.me 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

Pagar.me does not appear at checkout: check that the license is active, Enable / Disable is on, the secret key of the current mode is set (Test secret key in test mode, Live secret key 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 or On hold: the webhook is not working. In the Pagar.me dashboard check that the webhook exists for the account and mode you use, that its URL is exactly the one shown in the settings and that the events listed above are selected. The order is also checked when the customer returns to the store.

The webhook answers verification failed, retry later: the store could not read the Pagar.me order from the API, for example because the key of that mode is missing or the API did not answer. Pagar.me retries the webhook.

The webhook answers busy, retry later: the order was being updated by another request at the same moment. Pagar.me retries the webhook.

The webhook answers unknown order: the Pagar.me order was not created by this store, for example an order of another shop on the same account. Nothing is changed.

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

The customer sees Pagar.me payments are not available right now: the secret key is wrong or missing. Check the key of the current mode.

The customer sees Pagar.me could not start the payment: Pagar.me rejected the billing details. The message names the problem; the full reason is in the order notes.

The customer sees Pagar.me only supports payments in Brazilian Real (BRL): the order is in another currency, for example because of a currency switcher plugin.

Order is On hold after payment: read the order note. A PIX or boleto is waiting for payment, the paid amount or currency differed, or the payment came after the order was cancelled.

Refund fails for a boleto: boleto payments cannot be refunded through the API. Refund in the Pagar.me dashboard and record the refund manually.

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 and the logs of the plugin 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 Pagar.me data.

Pagar.me is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Pagar.me.