Thai QR via dLocal
This feature is a Private Beta release. Contact Chargebee Support to enable Thai QR via dLocal for your live and test sites.
Thai QR is a QR-code-based payment method in Thailand. The customer scans a QR code displayed at checkout using their banking or e-wallet app, and completes the payment from that app. Chargebee supports Thai QR as a payment method through the dLocal payment gateway.
Thai 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
Thai QR via dLocal supports the following country and currency. Refer to the dLocal Thailand documentation for the latest details.
| Country | Currency |
|---|---|
| Thailand | THB |
Chargebee always sends Thailand as the payer country for Thai QR transactions, and rejects a Thai QR payment intent created in any currency other than THB.
Payment features and workflows
The following table describes the supported features and behavior for Thai 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 Thai QR. |
| Verification modes | Defines how payment methods are validated before payment. | No | Not applicable | Not applicable. Thai 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 their banking or e-wallet app. |
| Fraud management | Identifies high-risk transactions. | No | Not applicable | Not supported by Chargebee for this method. Risk screening is handled by dLocal and the customer's bank or app. |
| Transaction initiation type | Indicates whether the transaction is customer-initiated or merchant-initiated. | Customer-initiated only | Customer-initiated | Every Thai 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 — Thai QR only exists in the context of a single payment. |
| Refunds | Returns funds to the customer's bank or e-wallet 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 Thai QR payments via dLocal:
- A dLocal merchant account with Thai QR enabled. Contact the dLocal support team to activate Thai QR for your account.
- dLocal is added and configured as a payment gateway in your Chargebee site.
- Your Chargebee site is enabled for THB collections.
Integration options
You can integrate Thai 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. Thai 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
Thai 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. Thai 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 Thai QR in Chargebee
Follow these steps to enable Thai 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 Thai QR in the list of payment methods.
- Click Apply to save your changes.
Configure Smart Routing
When you enable Thai QR through dLocal, Chargebee automatically adds a Smart Routing rule that sends THB transactions to that dLocal instance, as long as THB is enabled on your site and no Thai QR rule exists for THB yet. If a rule already points to another gateway, Chargebee does not change it. Edit the rule so that Thai 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 Thai QR section and click Add a Gateway or Edit for the THB currency.
-
Select the dLocal instance that has Thai QR enabled from the Choose a payment gateway drop-down menu.
-
Click Save.
Configure webhook notifications
Thai 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 Thai 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 Thai QR, and clicks Pay. Chargebee generates and displays the QR code on the checkout page.
-
The customer scans the QR code using their banking or e-wallet app.
-
The customer reviews and approves the payment inside their app.
-
Chargebee marks the transaction as successful or failed when it receives the status from dLocal, and the order confirmation page appears.
Using Thai QR with subscriptions
Thai 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.
- Thai 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 Thai QR to automatically collect subsequent renewals. The customer must return and scan a new QR code for every payment.
- Thai 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 Thai QR checkout flow.
Test payer details:
| Field | Value |
|---|---|
| Country | Thailand (TH) |
| Currency | THB |
| Document number | 1234567890123 |
The QR code returned by dLocal in sandbox is a static test QR. Scanning it does not open a real banking or e-wallet app. It only displays a "Test QR" message, and there is no way to simulate a completed scan-and-pay result from the QR itself. Use sandbox to validate QR generation and checkout rendering, and validate status handling separately using dLocal's test notifications.
Testing in production
Before going live:
- Confirm that Thai QR is enabled in your live dLocal account.
- Confirm that Thai QR is turned on for the live dLocal gateway instance in Chargebee, and that Smart Routing sends THB transactions to that instance.
- Run an end-to-end transaction with a real banking or e-wallet app, because the sandbox QR cannot be scanned to complete a payment.
- 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 Thai 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 Thai QR for recurring subscriptions?
No. Thai 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 Thai QR transaction still pending?
Thai QR is asynchronous. The transaction stays pending until the customer scans the QR code and completes the payment in their app, and dLocal sends the final status notification.
3. Can I capture a Thai QR payment manually?
No. Thai QR supports auto capture only. Manual capture and void are not available.
4. Does the billing address country affect Thai QR?
No. Chargebee always sends Thailand as the payer country for Thai QR, regardless of the billing address on the customer record.
5. Why doesn't scanning the QR code work in sandbox?
The sandbox QR code is a static test image. Scanning it only shows a "Test QR" message and does not open a real banking or e-wallet app, so you cannot complete an end-to-end scan-and-pay simulation in sandbox.
Limitations and important points
- Thai QR is available only for Thailand and only in THB.
- Thai 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.
- The QR code is valid for up to 10 minutes, which is dLocal's maximum for Thai QR. The customer must scan and complete the payment within that time, or the payment fails.