Nequi QR via dLocal
This feature is a Private Beta release. Contact Chargebee Support to enable Nequi QR via dLocal for your live and test sites.
Nequi QR is a QR-code-based payment method in Colombia. The customer scans a QR code displayed at checkout using the Nequi app, and completes the payment from that app. Chargebee supports Nequi QR as a payment method through the dLocal payment gateway.
Nequi QR is a one-time, scan-and-pay method. There is no enrollment, no stored payment method, and no reference ID, so it cannot be used to charge the customer again later. The payment is processed asynchronously: the transaction stays in a pending state after the QR code is generated, and Chargebee confirms the final status only after dLocal sends a webhook notification once the customer completes the scan and pays.
Supported countries and currencies
Nequi QR via dLocal supports the following country and currency. Refer to the dLocal Colombia documentation for the latest details.
| Country | Currency |
|---|---|
| Colombia | COP |
Chargebee always sends Colombia as the payer country for Nequi QR transactions, and rejects a Nequi QR payment intent created in any currency other than COP.
Payment features and workflows
The following table describes the supported features and behavior for Nequi QR via dLocal:
| Feature | Description | Supported | Default state | Configuration or behavior |
|---|---|---|---|---|
| Integration sync mode | Defines how payment requests are processed and how statuses are updated. | Yes (asynchronous only) | Asynchronous | dLocal generates the QR code immediately, then confirms the payment result through webhooks once the customer scans and pays. |
| Capture settings | Defines when funds are captured after authorization. | Yes | Auto capture | No configuration required. Auto capture is the only supported option. Manual capture is not available for Nequi QR. |
| Verification modes | Defines how payment methods are validated before payment. | No | Not applicable | Not applicable. Nequi QR is a one-time payment method with no stored payment method to verify. |
| Regulatory requirements support | Compliance requirements for the payment method. | Not applicable | Not applicable | Not applicable |
| Statement descriptor | Business name shown in the customer's statement. | No | Not applicable | Chargebee does not send a statement descriptor to dLocal for this method. |
| Chargeback management | Handles disputes and chargebacks. | No | Not applicable | Not supported. The customer completes the payment directly in the Nequi app. |
| Fraud management | Identifies high-risk transactions. | No | Not applicable | Not supported by Chargebee for this method. Risk screening is handled by dLocal and Nequi. |
| Transaction initiation type | Indicates whether the transaction is customer-initiated or merchant-initiated. | Customer-initiated only | Customer-initiated | Every Nequi QR payment requires the customer to scan a fresh QR code and pay. There is no merchant-initiated or recurring charge. |
| Error intelligence | Provides standardized failure categorization. | Yes | Enabled | No configuration required. |
| Gateway transaction details | Provides raw gateway responses. | Yes | Enabled | Available under Error details on the transaction page. |
| Addition of payment methods in the Chargebee Dashboard | Add a payment method outside a checkout. | No | Not applicable | Not supported. There is no reference ID or stored payment method to add — Nequi QR only exists in the context of a single payment. |
| Refunds | Returns funds to the customer's Nequi account. | Yes | Enabled | Full and partial refunds are supported once the payment is settled. A refund against a pending payment fails. |
| Void | Cancels an authorization before capture. | No | Not applicable | Not supported. Use a refund after the payment settles. |
Prerequisites
Ensure the following before configuring Nequi QR payments via dLocal:
- A dLocal merchant account with Nequi QR enabled. Contact the dLocal support team to activate Nequi QR for your account.
- dLocal is added and configured as a payment gateway in your Chargebee site.
- Your Chargebee site is enabled for COP collections.
Integration options
You can integrate Nequi QR via dLocal using the following methods:
| Integration method | Supported |
|---|---|
| Chargebee Checkout | In-app layout of Checkout - Supported Full Page Checkout - Supported |
| Chargebee Self-Serve Portal | Not supported. Nequi QR has no stored payment method to add or update from the customer portal. |
| Custom Checkout | Payment Components - Supported Chargebee.js (without Payment Components) - Supported API (Payment Intent) - Supported dLocal.js - Not supported |
Supported token formats
Nequi QR is a one-time payment method. There is no reference ID or stored payment method, so gateway tokens do not apply.
| Token type | Description | Supported | Token field | Token format |
|---|---|---|---|---|
| Chargebee Payment Intent | Recommended for a custom checkout built with Chargebee.js or Payment Components. | Yes | payment_intent[id] | payment_intent_id |
| Chargebee token | Legacy format. Not recommended for new integrations. | No | Not applicable | Not applicable |
| Gateway permanent token | A stored reference for recurring payments. | No | Not applicable | Not applicable. Nequi QR has no enrollment or reference ID to store. |
| Gateway temporary token | Short-lived token convertible to a permanent token. | No | Not applicable | Not applicable |
Configure Nequi QR in Chargebee
Follow these steps to enable Nequi QR in your Chargebee site:
- Log in to the Chargebee app.
- Go to Settings > Configure Chargebee > Payment Gateways.
- Select the relevant dLocal instance from the list.
- On the Configure dLocal page, turn on Nequi QR in the list of payment methods.
- Click Apply to save your changes.
Configure Smart Routing
When you enable Nequi QR through dLocal, Chargebee automatically adds a Smart Routing rule that sends COP transactions to that dLocal instance, as long as COP is enabled on your site and no Nequi QR rule exists for COP yet. If a rule already points to another gateway, Chargebee does not change it. Edit the rule so that Nequi QR transactions route to dLocal.
Follow these steps to modify the Smart Routing settings:
-
Go to Settings > Configure Chargebee > Payment Gateways.
-
Click Manage Rules under Smart Routing.
-
Go to the Nequi QR section and click Add a Gateway or Edit for the COP currency.
-
Select the dLocal instance that has Nequi QR enabled from the Choose a payment gateway drop-down menu.
-
Click Save.
Configure webhook notifications
Nequi QR payment statuses are confirmed asynchronously, so webhook notifications from dLocal are mandatory.
Chargebee registers and manages the dLocal webhook endpoint for your site. You do not need to create the endpoint manually in the dLocal dashboard.
dLocal sends notifications for the following updates, which Chargebee applies to the corresponding record:
| Notification | What Chargebee updates |
|---|---|
| Payment status update | Moves the transaction to success or failure based on the final dLocal payment status. |
| Refund status update | Marks the refund as complete or failed. |
Checkout flow
Your customer completes the following steps at checkout when paying with Nequi QR via dLocal:
-
The customer reviews the order on the Your cart page and clicks Proceed to Checkout.
-
The customer enters Account Details and Billing Address, selects Nequi QR, and clicks Pay. Chargebee generates and displays the QR code on the checkout page.
Chargebee displays the QR code on the checkout page. When the customer scans it, they complete the payment in the Nequi app. dLocal does not return a QR code in sandbox, so this scan step can only be completed in production.
Using Nequi QR with subscriptions
Nequi QR does not support recurring or merchant-initiated payments. There is no enrollment and no stored payment method, so Chargebee cannot charge the customer again without a new QR scan.
- Nequi QR can be used to collect a single payment, such as the first invoice on a subscription or a one-time charge.
- Chargebee cannot use Nequi QR to automatically collect subsequent renewals. The customer must return and scan a new QR code for every payment.
- Nequi QR cannot be added as a payment method from the Chargebee Dashboard or the customer portal, because there is no reference ID to store.
If you need automatic renewal collection, ask the customer to switch to a payment method that supports tokenization, such as a card or an enrollment-based wallet.
Testing in sandbox
Use the dLocal sandbox environment to validate the Nequi QR checkout flow.
Test payer details:
| Field | Value |
|---|---|
| Country | Colombia (CO) |
| Currency | COP |
| Document number | 123456789 |
dLocal does not return a QR code in the sandbox response for Nequi QR. QR generation cannot be tested in sandbox, so the checkout flow cannot be validated end to end in this environment. Validate the integration in production.
Testing in production
Before going live:
- Confirm that Nequi QR is enabled in your live dLocal account.
- Confirm that Nequi QR is turned on for the live dLocal gateway instance in Chargebee, and that Smart Routing sends COP transactions to that instance.
- Run an end-to-end transaction with a real Nequi app, because dLocal does not return a QR code in sandbox for this method.
- Verify that the transaction moves from pending to success after the webhook notification arrives.
- Confirm that the QR code expires and the payment fails if the customer does not complete the scan within the QR expiry window described in Limitations and important points.
Reconciliation
To reconcile transactions between Chargebee and dLocal:
- Retrieve the id_at_gateway value from the Chargebee transaction details.
- Locate the payment with the same ID in your dLocal reports.
- Match the transactions using this reference to ensure financial consistency.
Error codes and troubleshooting
Open the failed Nequi QR transaction and check Error details for the dLocal response. Error intelligence categorizes the failure. No additional configuration is required.
FAQs
1. Can customers use Nequi QR for recurring subscriptions?
No. Nequi QR is a one-time payment method with no enrollment or stored payment method. It can collect a single payment, such as the first invoice, but Chargebee cannot use it to automatically collect renewals.
2. Why is my Nequi QR transaction still pending?
Nequi QR is asynchronous. The transaction stays pending until the customer scans the QR code and completes the payment in the Nequi app, and dLocal sends the final status notification.
3. Can I capture a Nequi QR payment manually?
No. Nequi QR supports auto capture only. Manual capture and void are not available.
4. Does the billing address country affect Nequi QR?
No. Chargebee always sends Colombia as the payer country for Nequi QR, regardless of the billing address on the customer record.
5. Why doesn't the QR code appear in sandbox?
dLocal does not generate a QR code in the sandbox response for Nequi QR. QR generation is only available in production, so the checkout flow cannot be tested end-to-end in sandbox.
Limitations and important points
- Nequi QR is available only for Colombia and only in COP.
- Nequi QR is a one-time payment method. There is no enrollment, no reference ID, and no support for recurring or merchant-initiated charges.
- Manual capture and void are not supported. Use a refund after the payment settles.
- A refund against a payment that is still pending at dLocal fails.
- dLocal supports a QR code validity of up to 45 minutes for Nequi QR. The customer must scan and complete the payment before the QR code expires, or the payment fails. The Chargebee payment intent also expires, after 30 minutes by default, so a payment completed after the intent expires can fail even if the QR code is still valid.
- dLocal does not return a QR code in the sandbox response for Nequi QR. This is a sandbox limitation — QR generation and the checkout flow can only be tested in production.