Accepting PromptPay on Your Website: A Complete Technical Guide 2026

PromptPay has become Thailand's dominant payment method for both consumers and merchants. Integrating it into your website requires more than understanding the payment flow—you need solid knowledge of webhooks, server-side verification, and security best practices. This guide covers every technical aspect of accepting PromptPay.

What is PromptPay and Why It Matters for E-Commerce

PromptPay is Thailand's national QR code payment system, developed by the Bank of Thailand to simplify mobile money transfers. Instead of memorizing long bank account numbers, users send money using a PromptPay ID—typically a phone number, national ID, or tax number. For website operators, supporting PromptPay is nearly essential to reach Thai customers effectively.

• National QR code payment system developed and operated by Thailand's central bank
• Users send money using a PromptPay ID (phone, national ID, or tax number) instead of account numbers
• Registration happens inside existing bank apps; no separate account creation needed
• Real-time settlement with strong consumer trust and widespread adoption across Thailand S1_CODE:

The QR Code Payment Flow: Step-by-Step

When a customer selects PromptPay at checkout, your server generates a QR code in EMV format containing transaction details: the amount, the merchant's PromptPay ID, and a reference number. The customer scans the QR using their smartphone, which opens their bank app to confirm the transfer. Simultaneously, the payment gateway's servers send a webhook callback to your website's backend, notifying your system that the payment completed.

• Customer taps PromptPay and a QR code appears on checkout
• Scanning opens their bank app automatically with transaction details pre-filled
• They authenticate and confirm using PIN or fingerprint in their bank's secure environment
• Gateway's servers send webhook to your backend confirming payment completion S2_CODE:

Payment Gateway Categories: How to Choose

Several categories of payment solutions support PromptPay. Third-party payment gateways are all-in-one platforms that handle multiple payment methods including PromptPay, abstracting away compliance complexity. Bank merchant APIs offer deeper control but require more technical expertise. E-commerce platform plugins provide the easiest setup with minimal coding, though less customization potential.

• Third-party payment gateways supporting multiple payment methods
• Direct merchant APIs from commercial banks or fintech companies
• Pre-built plugins for popular platforms (WooCommerce, Shopify, custom frameworks)
• Trade-offs: ease of setup vs. transaction fees vs. customization control S3_CODE:

Integration Steps: From Registration to Live

Integration typically follows a standard sequence. First, register with a payment provider that supports PromptPay. Second, retrieve your API credentials and store them securely. Third, install the provider's SDK or library. Fourth, build a backend endpoint to receive and validate webhook notifications. Fifth, test the entire flow in a sandbox environment before enabling live transactions.

• Register with your chosen provider and complete merchant boarding
• Retrieve and securely store API credentials in environment variables
• Install their SDK/library into your codebase
• Build a webhook-receiving endpoint with signature validation
• Deploy to production only after comprehensive sandbox validation S4_CODE:

Webhooks and Server-Side Payment Verification

A webhook is an HTTP callback—the payment gateway sends a POST request to your server whenever transaction status changes. Your backend must validate the webhook by checking its cryptographic signature using a secret key only your server and the gateway know. This validation prevents attackers from forging fake payment notifications. Never assume a payment succeeded based on client-side signals alone.

• Webhook is a server-to-server notification that cannot be spoofed by clients
• Payload includes transaction ID, amount, status, timestamp, and cryptographic signature
• Always validate signatures using shared secret; never skip this step
• Client-side signals (JavaScript) are unreliable and can be manipulated S5_CODE: { "event_id": "evt_1h8k9j2k", "transaction": { "id": "txn_a8f9e7d3", "reference_number": "ORD-20260706-5423", "amount": 1250.00, "currency": "THB", "status": "COMPLETED" }, "signature": "hmac_sha256_generated_using_shared_secret_key" }

PromptPay vs Credit Card Gateways: Key Differences

PromptPay and credit card payments differ fundamentally. Credit card transactions require customers to enter sensitive card data that flows through your website. PromptPay requires no card data; instead, customers authenticate within their bank's app. Credit card processing mandates PCI-DSS compliance, a stringent standard that restricts what payment data your servers can touch. PromptPay avoids this entirely.

• Credit card requires sensitive card data on your website
• PromptPay keeps all data inside the customer's bank app—safer architecture
• Credit card compliance means strict PCI-DSS burden on your infrastructure
• PromptPay offloads security compliance to regulated financial institutions
• PromptPay is final and non-reversible; credit cards allow chargeback disputes S6_CODE:

Critical Security Considerations for Merchants

Security in PromptPay integration centers on server-side validation and credential management. Never trust client-side payment signals. Store API secrets in environment variables on your backend server; never hardcode them. Use HTTPS exclusively for webhook endpoints. Validate webhook signatures using the shared secret via HMAC-SHA256. Log all webhook events for auditing, and idempotently handle duplicate webhooks by checking if a transaction ID was already processed.

• Validate webhook signatures server-side every time using shared secret
• Never hardcode or expose API secrets in version control or frontend
• Use HTTPS exclusively for all webhook endpoints—reject HTTP requests
• Implement rate limiting to prevent webhook endpoint abuse
• Log all webhooks with timestamps for auditing and dispute resolution S7_CODE:

Best Practices and Implementation Tips

Implement these best practices: use a unique reference ID for each transaction. Send a confirmation email immediately upon successful webhook verification. Log all webhook events to a database table for auditing. Implement exponential backoff retry logic for failed webhook deliveries. Consider using a message queue to process webhooks asynchronously for resilience during traffic spikes.

• Use unique, immutable reference IDs per transaction for accurate order matching
• Send immediate confirmation emails after webhook verification with order details
• Store all webhook payloads in a database for auditing, debugging, and disputes
• Handle webhook retries and timeouts gracefully with exponential backoff S8_CODE: