VibeFox Pagar.me for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Currency: Brazilian Real (BRL). The payment method is hidden for carts in any other currency.

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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Pagar.me Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the test secret key and, when you go live, the live secret key.

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

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

On install the module creates two order statuses, Awaiting Pagar.me payment and Pagar.me payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Pagar.me Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields 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 default currency of the shop is not BRL.

Pagar.me

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

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Pagar.me. Required.

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: uses the test secret key, no real charges. While it is on, customers see TEST MODE — Use test credentials. No real charges. under the payment method. 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.

Saved keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secret keys: tick a key and click Save to remove it. An empty field keeps the saved value.

Payment page

Payment methods: the methods offered on the Pagar.me payment page. Only choose methods enabled in your Pagar.me account. If none is ticked, the default methods are used. Default: Credit card, PIX and Boleto.

Credit card: authorized and captured at once.

PIX: instant payment by PIX.

Boleto: bank slip; the order waits in Awaiting Pagar.me payment 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 Awaiting Pagar.me payment until Pagar.me confirms the payment. Default: 3. Another value is refused on save with Boleto due in (days): enter a number from 1 to 30.

Payment notifications (webhook)

In the Pagar.me dashboard open Settings > Webhooks and create a webhook with the URL shown in Webhook URL in this section. With friendly URLs it looks like https://your-shop/module/wcp_pagarme_gateway/webhook, possibly with a language code such as /en/. Copy it exactly as the settings show it.

Select these events (they are also listed in this section):

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 shop 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 shops 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 shop.

Advanced

Debug log: logs API requests and notifications to logs/wc_pgm_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged. Keys and customer data are not logged. Default: off.

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

Delete Data on Uninstall: when on, uninstalling the module removes the gateway settings and the log. Orders, their Pagar.me payment data (needed for refunds) and the order statuses are kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Pagar.me) and confirms. A valid e-mail is required. The module creates a Pagar.me order for the cart total in BRL, with the cart lines, shipping and gift wrapping (or one line Order # with the cart number when the cart has discounts), and sends the customer to the Pagar.me payment page. No order exists in your shop yet at this point.

The customer's name and e-mail are passed to Pagar.me. CPF or CNPJ is taken from the Identification number field of the address, or from VAT number; a Brazilian mobile number is passed as well. The billing address is passed only for a Brazilian address with an 8-digit CEP and a state. PrestaShop has no Brazilian states by default, so the customer usually enters the address on the Pagar.me page. Without a CPF or CNPJ the customer enters it there too.

After paying, the customer returns to your shop. The order is marked paid only after Pagar.me confirms it: the shop reads the Pagar.me order from the API, and the paid amount and currency must match the cart. A paid card payment, PIX or boleto creates the order in Payment accepted, and the customer sees the standard order confirmation page with Your payment with Pagar.me has been received. An issued PIX or boleto that is not paid yet creates the order in Awaiting Pagar.me payment, and the page shows Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Each later return reads the Pagar.me order again, so a PIX or boleto paid in the meantime is applied even when the webhook did not arrive. If the payment of such an order failed or expired, the page shows Your Pagar.me payment was not completed. Please contact us about this order.

If the customer comes back without paying, the customer is back at checkout with The Pagar.me payment was not completed. You can pay the order below. If the payment was declined or canceled, the message is The Pagar.me payment was declined or canceled. You can try again below. The cart is kept. If the order already exists and its payment failed or expired, the message is The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. If Pagar.me could not be reached, a Payment confirmation page asks the customer not to pay again and offers Check again and Back to checkout.

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 created without a new payment. If the earlier page cannot be closed, it stays matched to the cart, so a payment made there is still recorded.

If Pagar.me cannot start the payment, the customer stays at checkout with 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 written to the log.

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module 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

No order yet: the customer was sent to Pagar.me and has not paid or issued a PIX or boleto yet. Only the cart exists.

Payment accepted: the payment was confirmed. The payment is recorded with the Pagar.me order ID (or_...) as the transaction ID, and a note shows the Pagar.me order and the payment method.

Awaiting Pagar.me payment: a PIX or boleto was issued (or a card payment is in analysis) and is waiting for payment. The order moves to Payment accepted when Pagar.me confirms the payment.

Pagar.me payment on hold: the boleto was paid only in part; or the paid amount or currency differs from the order (for example, the cart was changed after the payment started); or the payment arrived after the order had been cancelled; or a chargeback was opened on a paid order. The note explains it. Check the order and fulfil it or refund the payment.

Payment error: the payment of an awaiting or held order failed, or its Pagar.me order was canceled or expired (for example an unpaid boleto). If Pagar.me reports a payment later, the order still moves to Payment accepted.

Refunded: the payment was fully refunded through the module, or refunded or canceled in Pagar.me.

Every Pagar.me status is applied once, so repeated webhooks or returns add no notes or payments. If a second Pagar.me order of the same cart is paid, a note asks you to refund the duplicate in the Pagar.me dashboard.

Pagar.me payment block

The order page shows a Pagar.me payment block with the Pagar.me order ID and charge IDs, the payment method, the status, the amount paid and refunded, a Test mode badge for test payments, the refund history and the Pagar.me notes of the order.

Refunds

In the Pagar.me payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Pagar.me. Confirm the question Refund this amount through Pagar.me? This cannot be undone. Full and partial refunds of card and PIX payments are supported. You need the right to edit orders. You can refund up to the amount Pagar.me actually took, so after an amount mismatch the limit is what the customer paid, not the order total. The refund is sent with the key of the mode the payment was made in, so that mode's secret key must be set. A refund is recorded only when Pagar.me confirms it; otherwise the block 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 refund history and the notes with the charge ID. A full refund sets the order to Refunded. A partial refund does not change the status. Refunds are available once Pagar.me has reported the payment.

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

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Pagar.me.

A full refund or cancellation made in the Pagar.me dashboard arrives by webhook, sets the order to Refunded and adds a note. A chargeback adds a note and puts a paid order in Pagar.me payment on hold.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Pagar.me Gateway is the first block on Modules > Module Manager > VibeFox Pagar.me Gateway > Configure, 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 shop. Below them are the line Product: presta-payment-pagarme and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency is BRL. The settings page shows a warning when the key is missing. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created or the order stays Awaiting Pagar.me payment: 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 Webhook URL and that the events listed above are selected. The order is also checked each time the customer returns to the shop.

The webhook answers verification failed, retry later: the shop 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: the cart was being updated by another request at the same moment, or the order could not be created (for example, the module is disabled). Pagar.me retries the webhook. Turn on Debug log to see the reason.

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

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, for example the CPF in the Identification number field of the address. The message names the problem; the full reason is in the log.

The customer sees Pagar.me only supports payments in Brazilian Real (BRL): the cart is in another currency.

The customer sees This order already has a Pagar.me payment that the store has to review: an earlier payment of the cart needs your review. Check the Pagar.me dashboard and the log.

Order is Pagar.me payment on hold after payment: read the notes in the Pagar.me payment block (see Order statuses), then fulfil the order or refund the payment.

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

Refund fails with a message about the mode: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it and try again.

Developers can change the Pagar.me order data before it is sent with the hook actionWcpPagarmeOrderData.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Pagar.me Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete Data on Uninstall is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The Pagar.me payment data of orders and the order statuses Awaiting Pagar.me payment and Pagar.me payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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