VibeFox Pagar.me for Adobe Commerce — Help
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 and JSON extensions.
Currency: Brazilian Real (BRL). The payment method is shown only when the cart currency is BRL and the cart total is greater than zero.
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
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-pagarme-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PagarmePayment/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_PagarmePayment 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 Pagar.me 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 test secret key and, when you go live, the live secret key. Create the webhook in the Pagar.me dashboard with the URL shown in the settings (see Configuration). Set Enable Pagar.me to Yes and click Save Config. Make test payments with Test mode = Yes, then set it to No to take real payments.
The module adds the Pagar.me payment method to the Magento checkout. It is off after installation (Enable Pagar.me = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Pagar.me payment attempts and refunds.
Configuration
All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Pagar.me 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. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99". The fields are listed below in the order of the page.
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title of 1 to 128 characters.); a Sort order that is not a whole number (Sort order must be a whole number.); a Boleto due in (days) outside 1 to 30 (Boleto due in (days): enter a number from 1 to 30.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be zero or greater.).
When Enable Pagar.me is Yes, the Payment notifications row shows warnings for the Default Config values: TEST MODE: no money is transferred. or LIVE mode uses the live secret key.; Enter the secret key of the active payment mode. when the key of the current mode is missing (the payment method is then hidden at checkout); The test secret key must start with sk_test_.; The live secret key must start with sk_ and must not be a test key.; and always Pagar.me supports Brazilian Real (BRL) only.
General
Enable Pagar.me: shows or hides Pagar.me at checkout. It is shown only when the secret key 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: Pagar.me. Required, at most 128 characters.
Description: the text shown under the payment method when the customer selects it at checkout. Default: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.
Sort order: the position among the payment methods at checkout. A whole number.
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: new payments are created with the test secret key, no real charges. While it is on, customers see TEST MODE: no money is transferred. 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: Yes.
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.
Magento stores the keys encrypted and shows only a mask (******) after saving, as the note under the fields says: Stored encrypted. Keep ****** to preserve; empty the field to remove. Key format warnings do not block saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved key, clear the field and click Save Config. A key with an unexpected prefix is saved, and the warning is shown in the Payment notifications row.
Payment page
Payment methods: the methods offered on the Pagar.me payment page. Only choose methods enabled in your Pagar.me account. If no known method is saved, the default methods are used. Default: Credit card, PIX and Boleto.
Boleto due in (days): the number of days until the boleto is due, from 1 to 30. Default: 3. See the note about Pending Payment Order Lifetime under Checkout.
Conditions
Payment from Applicable Countries: All Allowed Countries offers Pagar.me for every country your store allows, Specific Countries only for the countries below.
Payment from Specific Countries: offer Pagar.me only for billing addresses in these countries.
Minimum Order Total: offer Pagar.me only from this order total, in the base currency of your store. Empty means no minimum.
Maximum Order Total: offer Pagar.me only up to this order total, in the base currency. Empty means no maximum.
Payment notifications (webhook)
The Payment notifications row shows the Webhook URL. It is the storefront address of the default store view and looks like https://your-store/wcppagarmegateway/checkout/webhook/. In the Pagar.me dashboard open Settings > Webhooks, create a webhook with this URL and copy the URL exactly as the settings show it. Use the HTTPS address of your live store.
Select these events (they are also listed in this row):
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, from the settings of the store of the order. Notifications for Pagar.me orders that this store did not create are ignored. Without the webhook, PIX and boleto payments made later are confirmed only when the customer returns to the store or when you click Sync Pagar.me payment on the order page.
Advanced
Debug Log: writes API requests and notifications to var/log/wc_pgm_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always written. Keys, e-mail addresses, phone numbers and CPF/CNPJ are not logged. Default: No.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Pagar.me payment attempts and refunds always stay, so old orders can still be refunded. Default: No.
Checkout
At the payment step the customer chooses the payment method (by default Pagar.me) 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 Pagar.me order for the order total in BRL, with the order items, shipping and taxes (or one item Order # with the order number when the items cannot express the total exactly, for example with discounts), and sends the customer to the Pagar.me payment page.
The customer's name and e-mail are passed to Pagar.me. CPF or CNPJ is taken from the VAT Number field of the billing address (11 or 14 digits); a Brazilian mobile number is passed as well. The billing address is passed only for a Brazilian address with an 8-digit CEP, a street, a city and a state; otherwise the customer enters it on the Pagar.me page. Without a CPF or CNPJ the customer enters it there too.
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. Magento then creates the invoice and sends the order e-mail, and the customer sees the standard order success page with Pagar.me payment confirmed. An issued PIX or boleto that is not paid yet, or a card payment in analysis, leaves the order in Pending Payment, and the success page shows Awaiting Pagar.me payment confirmation (PIX / boleto or card in analysis). The webhook confirms the order as soon as the payment is made. A customer who comes back in another browser lands on the home page with the same message.
If the customer comes back without paying, or the payment was declined or canceled, the order is cancelled (the stock goes back), its Pagar.me order is closed, and the customer is back in the cart with Your Pagar.me payment was not completed. You can try again. The cart is restored. If Pagar.me could not be reached, a plain page asks the customer We are confirming your Pagar.me payment. Do not pay again. and offers Check again. If the payment needs your review (see Order statuses), the customer sees Your Pagar.me payment requires review. Do not pay again.
When the customer pays the same cart again, the open Pagar.me payment page is reused if the order, the amount and the mode are the same; otherwise it is closed at Pagar.me before a new one is created. If an earlier payment of the cart was paid in the meantime, or its PIX or boleto is still waiting, no new payment is created: the new order is cancelled with the note This cart already has a Pagar.me payment. Do not pay again. If the earlier page cannot be closed, it stays matched to the cart, so a payment made there is still recorded.
If the payment cannot start before anything is sent to Pagar.me (for example the module was switched off, the key is missing or the license is not active), the order is cancelled, the cart is restored and the customer sees Pagar.me could not start payment. Please check your order before retrying. in the cart. If Pagar.me rejects or does not answer the request to create the payment, the customer sees the same message, but the order stays in Pending Payment and the cart is not restored, so that a payment of unknown state is not repeated. Check such orders in the Pagar.me dashboard and cancel them in Magento. 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 Pagar.me order is closed and can no longer be paid. The default lifetime is 480 minutes (8 hours), shorter than a boleto that is due in days. If you offer boleto, set the lifetime longer than Boleto due in (days), for example 5760 minutes for the default of 3 days. A payment that arrives after the order was cancelled is not applied: the order gets a note to review it.
The module works with the standard Magento checkout. It 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. Pagar.me 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 Pagar.me, but Pagar.me has not confirmed the payment yet. An issued PIX or boleto, or a card payment in analysis, adds the note Awaiting Pagar.me payment confirmation (PIX / boleto or card in analysis). A failed or expired payment reported by webhook adds Pagar.me payment was declined, canceled or expired. There is no invoice.
Processing: the payment was confirmed. The invoice is created with the Pagar.me order ID (or_...) in the transaction ID, and a note says how it was confirmed, for example Pagar.me payment confirmed by webhook. with the Pagar.me order. Test payments add TEST MODE: no money was received; do not ship this order.
On Hold: the boleto was paid only in part (Pagar.me payment is underpaid. Review the dashboard before fulfilment.); the paid amount or currency differs from the order (Pagar.me paid amount or currency differs from the order. No paid invoice was created.); a payment arrived for an order you had put on hold; or a chargeback was opened on a paid order. Without an invoice, check the payment in the Pagar.me dashboard. To accept an underpaid or mismatched payment after your review, use Accept exact verified payment after review in the Pagar.me payment history: the store reads the Pagar.me order again and creates the invoice only if the amount and currency now match exactly and nothing was refunded. Otherwise it shows Only an exact, unrefunded Pagar.me payment on review Hold can be accepted.
Canceled: the customer did not complete the payment, the payment could not be started, or the order was cancelled in Magento. A payment that arrives later adds Pagar.me payment arrived after cancellation or refund. Review the dashboard and native accounting.; the order is not reopened.
Closed: the payment was fully refunded with a credit memo.
Every Pagar.me status is applied once, so repeated webhooks or returns add no notes or invoices. If a second Pagar.me order of the same cart is paid, a note on the paid order says Pagar.me received another payment for this cart. Refund the duplicate in the dashboard. The notes are order comments that the customer does not see.
Pagar.me payment information
On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, after the payment was confirmed, Pagar.me order, Payment method and Environment (test or live). The customer sees only the payment method title.
Below the order the section Pagar.me payment history lists every Pagar.me payment attempt of the order with its environment, status, payment method, and the amounts paid and refunded, and the refund operations. It is shown also when the module is switched off. The button Sync Pagar.me payment reads the latest attempt from the Pagar.me API again and applies its status; the result is shown as Pagar.me verification result: and the status. The buttons need the permission to edit orders.
Refunds
Card and PIX payments: 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 Pagar.me. 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 Pagar.me.
The refund is made in BRL from the paid Pagar.me charge with the most amount left, up to the amount Pagar.me actually took minus the amounts already refunded. It 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. If Pagar.me does not accept the refund, Magento shows the error and the credit memo is not created, for example Refund exceeds the actual remaining Pagar.me charge., Pagar.me refund failed. Check the dashboard before retrying. or Pagar.me did not confirm the refund. Reconcile before retrying. When the result of a refund is unknown, further refunds of the order are blocked with An earlier refund requires manual reconciliation before another refund. until it is checked. A full refund closes the order. Refunds are available once Pagar.me has confirmed the payment and the order has an invoice.
Boleto payments can only be refunded to the customer's bank account: Boleto payments can only be refunded to the customer bank account in the Pagar.me dashboard. Record native accounting manually. Refund them in the Pagar.me dashboard, then create a credit memo with Refund Offline.
For an order On Hold without an invoice, the Pagar.me payment history offers an amount field and Refund actual payment; reconcile native accounting. It refunds a card or PIX payment through Pagar.me without a credit memo and adds a note; record the refund in Magento yourself.
Refunds made in the Pagar.me dashboard and chargebacks arrive by webhook and add the note Pagar.me reports refunded. Review the dashboard and record native accounting; no automatic credit memo was created. (for a chargeback: Pagar.me reports chargedback. and the same text). A chargeback also puts the order On Hold. The order and credit memos are not changed automatically; create a credit memo with Refund Offline if needed. The same note can appear after a full refund that you made with a credit memo; then nothing else is needed.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Pagar.me Gateway is the first row of the VibeFox Pagar.me 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-pagarme 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, Pagar.me is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees Pagar.me 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
Pagar.me does not appear at checkout: check that the license is active and Enable Pagar.me is Yes for the website of the store, and that the current mode has a secret key: Test secret key in test mode, Live secret key in live mode. The Payment notifications row shows a warning when the key is missing. Check that the cart currency is BRL and the total is greater than zero, 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: 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. Click Sync Pagar.me payment on the order page to check the payment at once. The order is also checked each time 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: the cart was being updated by another request at the same moment, or an error occurred while the order was being updated. 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 store, for example an order of another store on the same account. Nothing is changed.
The webhook URL shows method not allowed in the browser: this is normal. The URL accepts only requests from Pagar.me.
Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Pagar.me retries the webhook later, and the order is also confirmed when the customer returns or with Sync Pagar.me payment.
Boleto orders are cancelled before the boleto is due: the Magento cron cancels orders in Pending Payment after the Pending Payment Order Lifetime. Set it longer than Boleto due in (days) (see Checkout).
The customer sees "Pagar.me could not start payment. Please check your order before retrying.": turn on Debug Log and look at the Log field. A wrong or missing key of the current mode, an inactive license, a request rejected by Pagar.me, or an earlier request to create a payment for this cart that got no clear answer gives this message. If the order stayed in Pending Payment, check it in the Pagar.me dashboard and cancel it in Magento.
Order is On Hold after payment: read the order notes (see Order statuses), then fulfil the order with Accept exact verified payment after review 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 with Refund Offline.
Refund fails although the payment exists: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it 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.
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.
Developers can change the Pagar.me order data before it is sent with the Magento event wc_pgm_order_data.
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_PagarmePayment. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PagarmePayment to remove the data, then bin/magento module:disable Vibefox_PagarmePayment, delete the folder app/code/Vibefox/PagarmePayment and run bin/magento setup:upgrade.
The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Pagar.me 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.
Pagar.me is a trademark of its respective owner. This module is not affiliated with or endorsed by Pagar.me.