EN
EUR
Back

VibeFox dLocal for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active.

PHP: 8.0 or later. The plugin refuses to activate on an older PHP or WordPress version.

Site access: your site must be reachable from the internet, and use HTTPS in production, so that dLocal Go can deliver payment notifications. A firewall, maintenance mode or basic authentication can block them.

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 plugin does not limit them. dLocal Go decides which payment methods are offered for the customer's country and the store currency.

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

2. Click Activate. WooCommerce must be active.

3. Open the settings: WooCommerce > Settings > Payments > dLocal Go > 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. Choose the Environment and paste the API key and API secret of that environment (see Configuration).

6. Turn on Enable/Disable and save. Test a payment in sandbox, then switch Environment to Production.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > dLocal Go. The page title 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. While sandbox is selected and the gateway is enabled, it shows Sandbox mode is active: payments are simulated, no money is charged. In the list of payment methods, dLocal Go is marked as needing setup until the credentials are set, and shows Test mode in sandbox.

General

Enable/Disable: Enable dLocal Go turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: dLocal Go.

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). All credential fields are password fields.

Environment: which credentials and which dLocal Go servers are used.

Sandbox (test): test payments with the sandbox credentials (default).
Production: real payments with the production credentials.

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.

Payment

Default country: dLocal Go shows the payment methods of the customer's country, taken from the billing address, then from the shipping address. This country is used when the order has neither. Default: Uruguay.

Auto-complete orders: Set paid orders to "Completed" instead of "Processing". The status is set at once, with one set of e-mails. Default: off.

Notifications (IPN)

The notifications tell your store that a payment or a refund has changed. The plugin sends the notification URLs to dLocal Go with every payment and refund, so nothing has to be configured in the dLocal Go dashboard. This section of the settings shows both URLs:

Payment IPN: looks like https://your-site/wc-api/dlocal_p_ipn/ (on sites without pretty permalinks /?wc-api=dlocal_p_ipn).
Refund IPN: looks like https://your-site/wc-api/dlocal_p_refund_ipn/.

Notifications are verified with your API secret (HMAC-SHA256). Notifications without a valid signature are rejected. 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 updated only when the customer comes back to the store.

Advanced

Debug log: Log API requests and notifications writes details to WooCommerce > Status > Logs, source wcp_dlocal_payment, without API credentials or personal data. Errors are always logged. Default: off.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). Default: off.

Checkout

The customer chooses the payment method (by default dLocal Go) and places the order. The plugin creates a dLocal Go payment for the order total in the order 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 order number. In sandbox mode the checkout shows Sandbox mode: no real payment is made. under the payment method.

After paying, the customer returns to the order received page of your store. 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 lands on that page.

If the customer leaves the dLocal Go page without paying, the customer comes back to the checkout (or to the Pay for order page) 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. If the payment turns out to be paid, the customer is sent to the order received page. An older payment link of the same order can still be paid after a retry.

If dLocal Go cannot start the payment, the customer sees a short message without technical details, for example dLocal could not start the payment: followed by the reason from dLocal, and can choose another method. This also happens when the customer's country and the store currency are not enabled in your dLocal Go account. The technical reason is written to the log.

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

Pending payment: the customer was sent to dLocal Go and has not paid yet, or the payment is pending at dLocal Go (for example a cash voucher not paid yet). Each new payment attempt is noted on the order with its dLocal payment ID, amount and environment.

Processing or Completed: the payment was confirmed. The order is Processing (the WooCommerce default), or Completed with Auto-complete orders on. The transaction ID is the dLocal payment ID.

On hold: dLocal Go reported a different amount or currency than the order total, or the payment arrived after the order had been cancelled. The order note explains it. Compare with the dLocal Go dashboard and fulfil the order or refund the payment.

Failed: the latest payment attempt was rejected or expired. The customer can try again.

Cancelled: dLocal Go reported the latest payment attempt as cancelled.

Only the latest payment attempt can fail or cancel an unpaid order. A paid order is never reopened by an old notification. 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.

Refunds

Open the order, click Refund, enter the amount and click Refund via dLocal Go. Full and partial refunds are supported for orders paid through dLocal Go. 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, WooCommerce shows the error and no refund is recorded. An accepted refund is added to the order notes with the refund ID and status.

dLocal Go then reports the final refund status by the refund notification, and it is added to the order 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. Review the WooCommerce refund recorded for it: delete it and refund again, or refund the customer another way.

Refunds made in the dLocal Go dashboard are not recorded as WooCommerce refunds and usually add no order note. If needed, create a manual refund in WooCommerce without Refund via dLocal Go.

License key

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

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.

The payment went through, but the order stays Pending payment: dLocal Go could not reach the notification URL (firewall, maintenance mode, basic authentication) and the customer did not return to the order received page. Check WooCommerce > Status > Logs, source wcp_dlocal_payment, and the payment in the dLocal Go dashboard. As soon as a notification arrives or the customer opens the order received page, the order is updated.

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 both environments, 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 selected environment are missing. 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 Order not found: the payment does not belong to an order of this store, 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.

Order is On hold after payment: read the order note. The paid amount or currency differed from the order, 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.

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.

For developers, the plugin documentation lists the filters dlocal_p_payment_data, dlocal_p_currency_decimals and dlocal_p_icon.

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 are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

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