Payment Gateway Integration Guide for Thai Businesses

A payment gateway integration connects your website or app to a provider that accepts cards, PromptPay and other methods, and then tells your system reliably whether each payment succeeded. For most Thai businesses the safest pattern is to use the gateway's hosted or tokenized checkout so card data never touches your servers, confirm payments through verified webhooks, and reconcile every day against the gateway's settlement reports.

Choosing a payment gateway in Thailand

Most Thai merchants choose between a handful of providers, or use more than one. Fees, supported methods and onboarding terms change, so treat this as a starting point and get current quotes.

Beyond price, compare: settlement time, refund support through the API, recurring billing, installment options, sandbox quality, documentation, and whether you can reach local support when something breaks on a Friday night.

The payment flow, step by step

1. Create the order on your server first

Before calling the gateway, create an order with status pending and calculate the amount on the server from your own product and discount data. Never trust an amount sent from the browser or app.

2. Checkout and tokenization

There are three common patterns: redirect to the gateway's hosted payment page, embed the gateway's JavaScript or mobile SDK fields that turn card details into a token, or show a PromptPay QR generated for that specific order. In the first two, card numbers go straight from the customer's device to the gateway, and your server only ever sees a token.

3. 3-D Secure and the return URL

Card payments often require 3-D Secure authentication with the issuing bank, after which the customer is redirected back to your site. The return URL is for showing a friendly status page only. Customers close tabs and networks drop, so never mark an order paid just because the browser came back.

4. Webhooks are the source of truth

The gateway sends your server an event when a charge succeeds, fails, expires or is refunded. Your webhook handler should verify the event (check the signature, or re-fetch the charge from the gateway API), update the order exactly once, reply with a 2xx status quickly, and push slow work such as emails or stock updates to a background queue.

POST /webhooks/payments
1. Verify the signature, or fetch the charge by ID from the gateway API
2. Begin a database transaction
3. Insert event.id into processed_events (unique) -> if it already exists, return 200
4. Load the order from the charge metadata and lock the row
5. If charge is successful AND charge.amount == order.amount_satang: mark order paid
6. Commit and return 200
7. Enqueue follow-up jobs: receipt email, warehouse notification

A simplified event might look like this. Every gateway uses its own field names, so this is illustrative only:

{
  "id": "evt_123",
  "type": "charge.succeeded",
  "data": {
    "charge_id": "chrg_456",
    "amount": 159000,
    "currency": "THB",
    "metadata": { "order_id": "ORD-2026-0042" }
  }
}

Note the amount: many gateways express THB in satang, the smallest unit, so 159000 means 1,590.00 baht. Store money as integers, never as floating-point numbers.

5. Idempotency keys

Timeouts and retries are normal. Without protection, a retry can create a second charge or a second order. Send an idempotency key (for example, derived from the order ID) on "create charge" requests where the gateway supports it, and on your side put a unique constraint on the gateway's charge ID and event ID so each is processed only once. Gateways also retry webhooks, so duplicates will arrive.

6. Reconciliation

Once a day, match three lists: orders you marked paid, transactions the gateway recorded, and money that actually arrived in your bank account. Settlements are usually net of fees, refunds and chargebacks, and your accountant will need both gross and net figures. Flag any mismatch for a human to review instead of waiting for month-end.

7. Refunds and disputes

Issue refunds through the gateway API, support partial refunds, and store each refund as its own record linked to the original charge rather than editing the old one. How quickly money returns to a card depends on the issuing bank. For disputes (chargebacks), keep evidence such as delivery confirmations and customer communication.

Security and PCI DSS scope

PCI DSS is the card industry's security standard, and it applies to every business that accepts cards. The amount of work depends on how card data flows:

• Hosted payment page or gateway-hosted fields keep card data off your systems and usually put you in the smallest self-assessment scope. Ask your gateway or acquirer which questionnaire applies to your setup.
• Never store card numbers or CVV codes, and make sure request logging, error trackers and analytics never capture them.
• Use tokenization for repeat purchases or subscriptions: store the gateway's customer or card token, not the card.
• Keep secret API keys on the server, in environment variables or a secret manager, and rotate them if they leak. Only publishable keys belong in front-end code.
• Protect the checkout page with HTTPS, a strict Content Security Policy and control over third-party scripts, since injected scripts are a common way card data is stolen.
• Mind the PDPA for customer names, addresses and phone numbers stored with orders.

Common mistakes to avoid

• Marking orders paid on the browser redirect instead of the webhook
• Accepting the price or amount from the client
• No idempotency, leading to double charges or duplicate orders
• Webhook endpoints that do not verify the event
• Slow work inside the webhook handler, causing timeouts and retry storms
• Floating-point money instead of integer satang
• Ignoring pending and expired states, especially for PromptPay QR codes that time out
• Mixing test and live keys between environments
• Testing only the happy path, not declined cards, failed 3-D Secure or delayed webhooks
• No reconciliation until the accountant finds a gap at month-end

Timeline and budget

A single gateway with a basic checkout is a small piece of work. Refunds, subscriptions, multiple methods, reconciliation reports and an admin dashboard take longer. In Vectorkub's pricing, applications that include payment integration, user accounts and an admin dashboard usually fall in the Web & Mobile Application tier (approximately 80k to 120k THB over 2 to 3 months, depending on scope). For a wider view of project budgets, see our guide to website development cost in Thailand.

FAQ

Do I need PCI DSS certification to accept cards?

Every merchant that accepts cards must comply with PCI DSS, but how you validate compliance depends on your transaction volume and integration method. Using a hosted checkout or hosted fields keeps the burden small. Your gateway or acquirer will tell you what they require.

Can I accept PromptPay without a payment gateway?

Yes. A bank can give you a static PromptPay QR, but someone has to check each transfer by hand. To confirm payments automatically, use a gateway or bank API that generates a dynamic QR per order and notifies your system when it is paid.

Which payment gateway is cheapest in Thailand?

It depends on your mix of cards, QR and other methods, your volume and your negotiated terms. Ask two or three providers for quotes based on your real numbers, and weigh settlement speed and support, not only the fee percentage.

How long does payment gateway integration take?

A basic checkout with one gateway can take days to a couple of weeks of development. A full setup with refunds, subscriptions, reconciliation and back-office tools takes longer and should be tested thoroughly in the sandbox first.

Build it right the first time

Payments are where small shortcuts turn into real money lost. Our custom software development team builds checkout flows, webhook processing and reconciliation for Thai businesses on Go, NestJS and PostgreSQL. Talk to us about your payment setup and we will help you pick a gateway and scope the integration.