VibeFox dLocal for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Shop access: your shop must be reachable from the internet, and use HTTPS in production, so that dLocal Go can deliver payment notifications.
dLocal Go account: you need the API key and the API secret from the dLocal Go dashboard, Payment integration section: dashboard-sbx.dlocalgo.com for sandbox, dashboard.dlocalgo.com for production. Sandbox and production use different credentials. The enterprise dLocal Payments API (X-Login / X-Trans-Key credentials) is a different product and is not supported.
Countries and currencies: the module does not limit them. dLocal Go decides which payment methods are offered for the customer's country and the cart currency. Only the PrestaShop payment restrictions apply.
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 dLocal Payment 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. Choose the Environment and paste the API key and API secret of that environment (see Configuration).
5. Turn on Enable/Disable and click Save. Test a payment in sandbox, then switch Environment to Production.
On install the module creates the order status dLocal 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 dLocal Payment > Configure. Each section has its own Save button, which saves the whole page. The title of the first section shows SANDBOX or PRODUCTION. Until the API key and secret of the selected environment are entered, the page warns you that the payment method is hidden at checkout, for example Enter the sandbox API key and secret: until then the payment method is hidden at checkout. While sandbox is selected and the payment method is enabled, it shows Sandbox mode is active: payments are simulated, no money is charged.
dLocal Go
Enable/Disable: Enable dLocal Go 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: dLocal Go. Required.
Description: the text shown under the payment method at checkout. Default: Pay with local cards, bank transfer or cash via dLocal Go.
API credentials
Copy the API key and API secret from the dLocal Go dashboard, Payment integration: dashboard-sbx.dlocalgo.com (sandbox) or dashboard.dlocalgo.com (production). The section links to both dashboards.
Environment: which credentials and which dLocal Go servers are used for new payments.
Refunds and notifications of a payment always use the credentials of the environment it was made in, so keep the credentials of the other environment while its payments are still open or may be refunded.
Sandbox API Key: your dLocal Go sandbox API key.
Sandbox API Secret: your dLocal Go sandbox API secret.
Production API Key: your dLocal Go production API key.
Production API Secret: your dLocal Go production API secret.
Saved keys and secrets 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 credentials: tick a key or secret and click Save to remove it. An empty field keeps the saved value.
Payment
Default country: dLocal Go shows the payment methods of the customer's country, taken from the invoice address, then from the delivery address. This country is used when the cart has neither. Default: Uruguay.
Auto-complete orders: sets paid orders to Delivered instead of Payment accepted. The status is set at once, with one status change. Default: off.
Notifications (IPN): the notifications tell your shop that a payment or a refund has changed. The module sends the notification URLs to dLocal Go with every payment and refund, so nothing has to be configured in the dLocal Go dashboard. This field shows both URLs:
Notifications are verified with your API secret (HMAC-SHA256). Notifications without a valid signature are rejected. A notification must be signed with the credentials of the environment the payment was made in. After that, the status, amount and currency of the payment are always read again from the dLocal Go API; the content of the notification is not trusted. Without notifications, an order is created only when the customer comes back to the shop.
Advanced
Debug log: writes dLocal Go requests and notifications to logs/dlocal_p_debug.log.php in the module folder. The file cannot be opened from the web. API credentials and personal data are not logged. Errors and warnings are always written; the other entries only while this option is on. 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. The order payment data (dLocal payments and refunds) and the order status dLocal payment on hold always stay, so existing orders keep working. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default dLocal Go). In sandbox mode the checkout shows Sandbox mode: no real payment is made. under the payment method. After confirming, the module creates a dLocal Go payment for the cart total in the cart currency, with the customer's country, name, e-mail and phone, and sends the customer to the dLocal Go payment page. There the customer pays with a method of their country. The payment shows on the dLocal Go page as Order # and the cart number. No order exists yet at this point.
After paying, the customer returns to your shop. The order is marked paid only after dLocal Go confirms it: by the signed notification or by a server-side request to the dLocal Go API when the customer comes back. The order is then created and the customer sees the standard order confirmation page with Your payment with dLocal Go has been received. If the order was put on hold, the page shows Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. If dLocal Go has not confirmed the payment yet (for example a cash voucher not paid yet, or dLocal Go could not be reached), a Payment confirmation page asks the customer not to pay again and offers Check again and Back to checkout. The order is created as soon as dLocal Go confirms the payment.
If the customer leaves the dLocal Go page without paying, the customer comes back to the checkout and sees The payment at dLocal Go was not completed. You can try again or choose another payment method. If the payment was declined or expired, the message is Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. The cart is kept. Each new attempt creates a new dLocal Go payment; an older payment link of the same cart can still be paid and creates the order.
If dLocal Go cannot start the payment, the customer stays at checkout with a short message, for example dLocal could not start the payment: followed by the reason from dLocal. This also happens when the customer's country and the cart currency are not enabled in your dLocal Go account. If dLocal Go rejects your credentials, the customer sees This payment method is temporarily unavailable. Please choose another payment method or contact us. The technical reason is written to the log.
The notifications work while the shop is in maintenance mode and are not blocked by the country restriction of your shop.
The module takes one-time payments on the dLocal Go page only. It has no card form on your site, no saved cards, no subscriptions and no separate authorize and capture.
Orders and refunds
Order statuses
No order yet: the customer was sent to dLocal Go and has not paid, or the payment is still pending at dLocal Go. Only the cart exists.
Payment accepted or Delivered: the payment was confirmed. The order is Payment accepted, or Delivered with Auto-complete orders on. The payment is recorded with the dLocal payment ID as the transaction ID, and a note shows the environment and the payment ID.
dLocal payment on hold: dLocal Go reported a different amount or currency than the cart total (for example, the cart was changed in another tab after the payment started), or the payment arrived after the order had been cancelled. The note explains it. Compare with the dLocal Go dashboard and fulfil the order or refund the payment.
Refunded: the payment was fully refunded through the module.
A declined, expired or cancelled payment never changes an existing order. If a second payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the duplicate payment in the dLocal Go dashboard.
dLocal Go payment block
The order page shows a dLocal Go payment block with the dLocal payment ID, the environment (with a Sandbox badge for test payments), the payment status, the amount dLocal Go charged and the amount refunded, the refund form, the refund history and the dLocal Go notes of the order.
Refunds
In the dLocal Go payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via dLocal Go. Confirm the question Refund this amount through dLocal Go? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders; access to the Modules pages is not needed. Refunds are made in the amount and currency dLocal Go charged, so after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total. The refund is sent to the environment the payment was made in, with that environment's credentials. If dLocal Go does not accept the refund, the block shows the error and no refund is recorded. An accepted refund is added to the refund history and the notes with the refund ID, status and reason. A full refund sets the order to Refunded. A partial refund does not change the status.
dLocal Go then reports the final refund status by the refund notification, and it is added to the notes. If dLocal Go later rejects or cancels a refund that it had accepted, the note warns that the money was not returned to the customer. Refund the customer again or another way.
The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through dLocal Go. Refunds made in the dLocal Go dashboard are not recorded as refunds in PrestaShop and usually add no note. Update the order manually if needed.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox dLocal Payment is the first block on Modules > Module Manager > VibeFox dLocal Payment > 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-dlocal 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, dLocal Go 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
dLocal Go does not appear at checkout: check that the license is active, Enable/Disable is on and the API key and API secret of the selected Environment are set. The settings page shows a warning when they are 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: dLocal Go could not reach the notification URL (firewall, basic authentication, no public address) and the customer did not come back to the shop. Turn on Debug log, look at the Log field and check the payment in the dLocal Go dashboard. As soon as a notification arrives or the customer opens Check again, the order is created.
Notification answers Missing signature or Invalid signature: the API key and secret in the settings do not belong to the account that sent the notification. Notifications are checked with the credentials of the environment of the payment, so payments started before you switched Environment are still confirmed, as long as the credentials of their environment stay in the settings.
Notification answers Gateway not configured: the credentials of the payment's environment are missing. Enter them; dLocal Go retries the notification.
Notification answers API verification failed: the dLocal Go API could not be reached to read the payment. dLocal Go retries the notification.
Notification answers Temporarily unavailable: the order was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). dLocal Go retries the notification. The reason is in the log.
Notification answers Order not found: the payment does not belong to a cart of this shop, for example it was created by another site with the same dLocal Go account.
The customer sees This payment method is temporarily unavailable: dLocal Go rejected the API key or secret. Check the credentials of the selected environment.
The customer sees Payment gateway is not properly configured: the credentials of the selected environment are missing.
Order is dLocal payment on hold after payment: read the notes in the dLocal Go payment block. The paid amount or currency differed from the cart, or the payment came after the order was cancelled. Fulfil the order or refund the payment.
Refund fails with a message about missing credentials: the payment was made in the other environment, and its credentials are not set. Enter them and try again.
For developers, the module documentation lists the hooks actionWcpDlocalPaymentData and actionWcpDlocalCurrencyDecimals.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox dLocal Payment 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 dLocal payments and refunds of orders and the order status dLocal 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.
dLocal is a trademark of its respective owner. This module is not affiliated with or endorsed by dLocal.