POST

/v1/qr-codes

Generate QR Code

Create a PromptPay QR code for customer payments. The customer scans the QR code with their banking app to complete the payment.

Overview

Generate a PromptPay QR code that customers can scan to make payments. The QR code contains payment information and links directly to the customer's banking app. Once scanned and paid, you'll receive a webhook notification about the payment status.

Note:

Client information (name, bank name, bank account) is optional. If you provide it, we'll use it for payment tracking. If not provided, our system will automatically handle and retrieve this information when the payment is processed. For merchant operations, use the metadata field to include client ID, profile information, or merchant account details.

How It Works:

Merchant generates QR code with amount and reference
QR code is displayed to customer (on screen, printed, etc.)
Customer scans QR code with their banking app (PromptPay enabled)
Payment is processed automatically through the bank
Merchant receives webhook notification when payment completes

Request

Request Body

Required and optional fields

Required Fields

amount

required

Payment amount in smallest currency unit (e.g., 100 = 10000 THB). Minimum: 1 THB, Maximum: 2,000,000 THB

currency

required

ISO 4217 currency code. Currently supports: THB (Thai Baht)

Optional Fields

client_name

optional

Full name of the client/customer making the payment. If not provided, our system will handle it automatically.

client_bank_name

optional

Name of the client's bank (e.g., "Bangkok Bank", "Kasikorn Bank", "Siam Commercial Bank"). If not provided, our system will handle it automatically.

client_bank_account

optional

Client's bank account number. If not provided, our system will handle it automatically when the payment is processed.

reference

optional

Your reference ID for this payment (e.g., order ID, invoice number). Max 35 characters.

expiry_minutes

optional

QR code expiry time in minutes (default: 15 minutes). QR code becomes invalid after expiry.

metadata

optional

Additional metadata object for storing custom data. Useful for merchant client IDs, profiles, or any other business-specific information. This data will be included in webhook notifications.

Example metadata:

{
  "client_id": "CLIENT-12345",
  "client_profile": "premium",
  "merchant_account_id": "MERCHANT-67890",
  "additional_info": "Any custom data"
}

idempotency_key

recommended

Unique key to prevent duplicate QR code generation. Learn more

Code Examples

curl -X POST "https://api.demo-gateway.com/v1/qr-codes" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 10000,
  "currency": "THB",
  "reference": "ORDER-12345",
  "client_name": "John Doe",
  "client_bank_name": "Bangkok Bank",
  "client_bank_account": "1234567890",
  "expiry_minutes": 15,
  "metadata": {
    "client_id": "CLIENT-12345",
    "client_profile": "premium",
    "merchant_account_id": "MERCHANT-67890",
    "additional_info": "Any additional data you need"
  }
}'

Response

Status Codes

200

QR code generated successfully

400

Invalid request data

401

Authentication failed

422

Amount out of range or invalid currency

Success Response

Example response for a successful request

{
  "qr_code_id": "qr_1234567890abcdef",
  "qr_data": "00020101021153037645802TH29370016A0000006770101120112345678901234567890215ORDER-1234552041000053037645802TH6304ABCD",
  "qr_image_url": "https://api.demo-gateway.com/v1/qr-codes/qr_1234567890abcdef/image",
  "amount": 10000,
  "currency": "THB",
  "reference": "ORDER-12345",
  "client_name": "John Doe",
  "client_bank_name": "Bangkok Bank",
  "client_bank_account": "1234567890",
  "expires_at": "2024-01-15T10:45:00Z",
  "payment_id": "pay_1234567890abcdef",
  "status": "pending",
  "metadata": {
    "client_id": "CLIENT-12345",
    "client_profile": "premium",
    "merchant_account_id": "MERCHANT-67890",
    "additional_info": "Any additional data you need"
  }
}

Error Response

Example response for an error

{
  "error": {
    "code": "invalid_amount",
    "message": "Amount must be between 1 and 2000000 THB",
    "type": "validation_error"
  }
}

QR Code Response Fields

Understanding the Response

qr_data

The raw QR code data string. Use this to generate a QR code image using any QR code library.

qr_image_url

Pre-generated QR code image URL. You can display this directly or download it.

payment_id

The payment ID associated with this QR code. Use this to check payment status.

client_name

The client name you provided in the request. Included in the response for verification.

client_bank_name

The client's bank name. Used for payment routing and tracking.

client_bank_account

The client's bank account number. Used to identify the payment source.

metadata

The metadata object you provided. This will be included in webhook notifications for your reference.

expires_at

Timestamp when the QR code expires. After this time, the QR code is no longer valid.

Payment Flow

What Happens After QR Generation

Display QR Code

Show the QR code to your customer (on screen, printed receipt, etc.)

Customer Scans

Customer opens their banking app and scans the QR code

Payment Processing

Payment is automatically processed through PromptPay network

Webhook Notification

You receive a webhook when payment succeeds or fails

Best Practices

QR Code Implementation Tips

•
Client Information: Client name, bank name, and account number are optional. If you have this information, you can provide it for better tracking. If not provided, our system will automatically handle and retrieve it when the payment is processed.
•
Metadata for Casinos: Use the metadata field to store client IDs, profiles, merchant account IDs, or any other business-specific information. This data will be included in webhook notifications.
•
Display Size: Ensure QR code is large enough to scan easily (minimum 200x200 pixels recommended)
•
Expiry Handling: Monitor QR code expiry and regenerate if needed before customer scans
•
Polling vs Webhooks: Use webhooks for real-time updates, but also poll payment status as a backup
•
Reference IDs: Use meaningful reference IDs to track payments in your system

Related Endpoints

GET /v1/payments/{id} - Check Payment Status POST /v1/webhooks - Configure Webhooks