VibeFox dLocal for Adobe Commerce — Aide

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.

Store access: your store 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 order currency. Only the Magento conditions of the payment method apply (see Configuration).

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-dlocal-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/DlocalPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_DlocalPayment 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 dLocal Payment. 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. Keep Environment on Sandbox, paste the sandbox API key and API secret, set Enable to Yes, click Save Config and place a test order. When you are ready, enter the production credentials, switch Environment to Production and click Save Config.

The module adds the dLocal Go payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the dLocal Go payments and refunds. The notification URLs are sent with every payment and refund. Nothing has to be configured in the dLocal Go dashboard.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox dLocal Payment, 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 use a dot as the decimal separator, for example 9.99.

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 for the payment method (1 to 128 characters).); a Sort order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be a number, 0 or greater.).

After Save Config, while Enable is Yes in the Default Config, Magento shows dLocal: enter the API key and secret of the selected environment; the payment method is hidden until then. when a credential of the selected environment is missing, and dLocal: sandbox mode is active; no real money is charged. while Environment is Sandbox.

General

Title: the payment method name customers see at checkout. It is also stored in the order. Default: dLocal Go. Required, at most 128 characters.

Enable: shows or hides dLocal Go at checkout. It is shown only when the API key and API secret of the selected environment are set. Default: No.

Sort order: the position among the payment methods at checkout. A whole number.

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay with local cards, bank transfer or cash via dLocal Go.

Connection

Copy the API key and API secret from the dLocal Go dashboard, Payment integration: dashboard-sbx.dlocalgo.com (sandbox) or dashboard.dlocalgo.com (production).

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.

Live Api Key: your dLocal Go production API key.

Live Api Secret: your dLocal Go production API secret.

Sandbox Api Key: your dLocal Go sandbox API key.

Sandbox Api Secret: your dLocal Go sandbox API secret.

Magento stores the keys and secrets encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved value, type a new value to change it. The value is saved exactly as entered, including quotes and backslashes; only spaces at the start and end are removed. To delete a saved key or secret, clear the field and click Save Config.

Orders

Payment from Applicable Countries: All Allowed Countries offers dLocal Go for every country your store allows, Specific Countries only for the countries below.

Default country: dLocal Go shows the payment methods of the customer's country, taken from the billing address, then from the shipping address. This two-letter country code is used when the order has neither. Invalid values are saved as UY. Default: UY (Uruguay).

Payment from Specific Countries: offer dLocal Go only for billing addresses in these countries.

Minimum Order Total: offer dLocal Go only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum Order Total: offer dLocal Go only up to this order total, in the base currency. Empty or 0 means no maximum.

Auto-complete paid orders: when Yes, a paid order goes to Complete instead of Processing. Default: No.

Advanced

Debug log: writes the dLocal Go API requests and responses (payments and refunds) and failed confirmations to var/log/dlocal_p_debug.log.php in the Magento folder. The file cannot be opened from the web. API credentials, e-mail addresses and tokens are not logged. Errors and warnings are always written; the other entries only while this option is Yes. Default: No.

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 dLocal Go payments and refunds, the orders and their history always stay. Default: No.

Notification URLs and log

dLocal Go notification URLs: shows, for reference, the Payment notification URL and the Refund notification URL of the store view selected in Scope (the default store view in the Default Config). They look like https://your-store/wcpdlocalpayment/webhook/index and https://your-store/wcpdlocalpayment/refundwebhook/index. Each payment and each refund sends these URLs of the store view of the order to dLocal Go automatically.

Notifications are verified with the API key and API secret of the environment the payment was made in (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. Notifications are handled even when Enable is No or the license is not active. Without notifications, an order is confirmed only when the customer comes back to the store.

Debug log: shows the size and the latest entries of the log, or The log is empty. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default dLocal Go) and sees the description and the note You will be redirected to dLocal Go to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a dLocal Go payment for the order total in the order currency, rounded to the decimals of the currency, with the customer's country, name, e-mail and phone, and sends the customer to the dLocal Go payment page. The payment shows on the dLocal Go page as Order # and the Magento order number.

After paying, the customer returns to 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 comes back. Magento then creates the invoice with the dLocal payment ID as the transaction ID, the order moves to Processing (or Complete with Auto-complete paid orders) and the order e-mail is sent. The customer sees the standard order success page. If the order was put on hold, the success page shows Your payment is being reviewed by the store. A customer who comes back in another browser lands on the home page.

If dLocal Go has not confirmed the payment yet (for example a cash voucher not paid yet, or dLocal Go could not be reached), the customer sees dLocal Go has not confirmed your payment yet. Please do not pay again. with a Check again link. The order stays in Pending Payment and is invoiced as soon as dLocal Go confirms the payment.

If the customer leaves the dLocal Go page without paying, or the payment was declined or expired, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with The payment at dLocal Go was not completed, was declined or expired. Please try again or choose another method. The customer can pay again or choose another payment method. If dLocal Go reports a declined, expired or cancelled payment by notification, the waiting order is cancelled too. If the return link cannot be verified, the customer is back in the cart with We could not verify the dLocal Go payment.

If the payment cannot be started, for example because dLocal Go rejected the credentials or the customer's country and the order currency are not enabled in your dLocal Go account, the order is cancelled, the cart is restored and the customer sees We could not start the dLocal Go payment. Please try again or choose another payment method. The reason is written to the log. If the order already has a dLocal Go payment that is still open, the customer is sent back to the same payment page instead of a new one.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The module does not stop such a cancellation. If dLocal Go later reports a payment for a cancelled order, the order is not invoiced or re-opened: a note shows the actual payment, and you can refund it from the order page (see Orders and refunds).

The module works with the standard Magento checkout. It 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. dLocal Go 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 dLocal Go, but dLocal Go has not confirmed the payment yet, or the payment is still pending at dLocal Go. There is no invoice.

Processing or Complete: the payment was confirmed. The invoice is created with the dLocal payment ID as the transaction ID, and a note shows the payment ID, the environment and how it was confirmed (webhook or return). The order is Complete with Auto-complete paid orders = Yes.

On Hold: dLocal Go reported a different amount or currency than the order total, or the order was changed manually while the payment was open. No invoice is created. The note says the payment requires review and shows the actual payment. Compare with the dLocal Go dashboard, then fulfil the order or refund the payment.

Canceled: the customer left the dLocal Go page, the payment was declined, expired or cancelled, the payment could not be started, or the order was cancelled in Magento. A payment that arrives later does not re-open the order.

Closed: the payment was fully refunded with a credit memo.

A paid order is never changed by a later status. If a second payment arrives for an order or a cart that is already paid, nothing is invoiced again. A note asks you to refund the duplicate payment in the dLocal Go dashboard. The notes are order comments that the customer does not see.

dLocal Go payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once dLocal Go has reported the payment, dLocal Go transaction, dLocal Go status, dLocal Go amount (the amount and currency dLocal Go charged) and dLocal Go mode (sandbox or live). The customer sees only the payment method title.

Refunds

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 dLocal Go. 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 dLocal Go.

The refund is made in the currency dLocal Go charged, up to the amount it charged minus the amounts already refunded. For currencies without decimals, such as CLP and PYG, the refund is rounded to whole units, the same way the payment was. The refund is sent to the environment the payment was made in, with that environment's credentials. If dLocal Go refuses the refund, Magento shows dLocal refused the refund with the status and the credit memo is not created. After an accepted refund Magento records it with the dLocal refund ID as the transaction ID, and a note says dLocal Go refund requested with the refund ID and status. A full refund closes the order. Refunds are available once dLocal Go has confirmed the payment and the order has an invoice.

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. The credit memo stays; reconcile it and refund the customer again another way. If the result of a refund request is unknown (for example dLocal Go could not be reached), Magento shows dLocal refund could not be confirmed. Check its dashboard before retrying. and new refunds of the order are blocked with dLocal refund outcome is uncertain. Check the dLocal Go dashboard before retrying. until the refund is checked.

Refunds of an order on hold: an order put on hold after a mismatch has no invoice, so no credit memo can be made. The order page shows a dLocal payment review section with the amount actually captured and the amount still refundable. Enter the Refund amount (in the currency dLocal Go charged), optionally a Reason (private order note), and click Refund reviewed dLocal payment. The money is sent back through dLocal Go and a note is added; no invoice or credit memo is created. You need the permission to create credit memos. Resolve the held order separately.

Refunds made in the dLocal Go dashboard are not recorded as credit memos in Magento. If a refund notification for such a refund reaches the store, it is only added to the order notes. Create a credit memo with Refund Offline or 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 row of the VibeFox dLocal Payment 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-dlocal 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, dLocal Go 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 We could not start the dLocal Go payment. Please try again or choose another payment method. 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

dLocal Go does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the API key and API secret of the selected Environment are set: the sandbox fields for Sandbox, the live fields for Production. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. Orders with a zero total are not paid through dLocal Go.

The payment went through, but the order stays Pending Payment: no notification reached your store and the customer did not come back. Check that your server accepts requests from dLocal Go to the payment notification URL (firewall, basic authentication, no public address) and that the API key and secret of the environment of the payment are set. Turn on Debug log, look at the Debug log row and check the payment in the dLocal Go dashboard. As soon as a notification arrives or the customer opens Check again, the order is invoiced.

Notification answers Missing signature or Invalid signature or missing credentials: 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 or refund. dLocal Go retries the notification.

Notification answers Temporarily unavailable: the order was being updated by another request at the same moment, or an error occurred while the order was being updated. dLocal Go retries the notification. The reason is in the log.

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. Invalid JSON or payment ID or Payment ID or order reference mismatch means the notification does not match a payment of this store.

The notification URL shows Method not allowed in the browser: this is normal. The URL accepts only POST requests from dLocal Go.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification and return URLs too. The order is confirmed by the next notification that reaches the store or when the customer opens Check again.

The customer is back in the cart with We could not start the dLocal Go payment: dLocal Go rejected the credentials, the customer's country or the order currency is not enabled in your dLocal Go account, the credentials of the selected environment are empty, the module was disabled or the license is not active. The order of that attempt is cancelled. Errors of the dLocal Go API are always written to the log; look at the Debug log row.

A payment was made but the order is On Hold or Canceled: the paid amount or currency did not match the order, or the payment arrived after the order had been cancelled, for example by the Pending Payment Order Lifetime cron. Read the order notes, check the payment in the dLocal Go dashboard and use the dLocal payment review section to refund it if needed.

The Refund button is missing on the credit memo: start the credit memo from the invoice, not from the order page. An order without an invoice (Pending Payment, On Hold after a mismatch) cannot be refunded with a credit memo.

Refund fails with No confirmed dLocal payment was found for this order: dLocal Go has not confirmed a payment for the order. Refund only orders paid through dLocal Go.

For developers: the payment request can be changed with the Magento event dlocal_p_payment_data (transport body and the order), and the decimals of a currency with dlocal_p_currency_decimals (transport decimals and the currency).

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.

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_DlocalPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_DlocalPayment to remove the data, then bin/magento module:disable Vibefox_DlocalPayment, delete the folder app/code/Vibefox/DlocalPayment 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 dLocal Go payments 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.

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