# PromptPay

## Introduction

PromptPay is Thailand's national QR code payment service, supporting online payments through QR code scanning. Users can complete payments with bank apps or e-wallets that support PromptPay, providing a convenient and secure payment experience for merchants and customers in Thailand.

| Attribute | Support Status |
|  --- | --- |
| Payment Mode | QR Code |
| Integration Products | API Only |
| Supported Currencies | THB |
| Payment Flow | QR Code |
| Auto-capture payment | ✅ |
| Authorization | ❌ |
| Capture | ❌ |
| Partial Capture | ❌ |
| Void | ❌ |
| Partial Void | ❌ |
| Refund | ❌ |
| Partial Refund | ❌ |
| Dispute | ❌ |
| Recurring Subscription | ❌ |
| 3DS | ❌ |


It has the following advantages:

- Fast and convenient payment experience
- Widely used in the Thailand market
- Secure QR code-based transactions
- Support for online payments
- Compatible with major Thai banks and e-wallets


## API Only Integration

**API Only** is the only supported integration path for PromptPay. Call [Initiate Transaction](/payments/apis/payments/openapi/transaction/payments-opl_1) and display the returned `payment.payment_data.qr_code` on your page. Hosted Checkout, Component, PaymentLink, and Billing are not supported.

See [API Only](/payments/docs/transaction/web/api-only) for shared API Only prerequisites (keys, webhook, and so on).

1. Configure the payment result **webhook** URL.
2. Call [Initiate Transaction](/payments/apis/payments/openapi/transaction/payments-opl_1) with `payment.payment_method` set to `PROMPT_PAY`.


#### Request Example

```json
{
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m_your_unique_transaction_id",
  "amount": 9212230,
  "currency": "THB",
  "payment_type": "PURCHASE",
  "expire_time": "2026-06-03T18:30:00+0800",
  "address_collection": "AUTO",
  "return_url": "https://your-domain.com/return",
  "notify_url": "https://your-domain.com/webhook",
  "goods": [
    {
      "name": "Headphones",
      "quantity": 3,
      "price": 199.99,
      "link": "https://example.com/products/headphones"
    },
    {
      "name": "Headphones",
      "quantity": 2,
      "price": 199.99,
      "link": "https://example.com/products/headphones"
    }
  ],
  "customer": {
    "name": "Alice Garcia",
    "email": "alice.garcia3423@yahoo.com",
    "phone": "+1234567890",
    "id": "CUST_your_customer_id",
    "order_ip": "127.0.0.1",
    "pay_ip": "127.0.0.1"
  },
  "bill": {
    "first_name": "Charlie",
    "last_name": "Moore",
    "email": "bill703@yahoo.com",
    "phone_number": "+1234567890",
    "address_line1": "789 Pine Road",
    "country": "IT",
    "state": "New York",
    "city": "Paris",
    "postal_code": "43238",
    "area_code": "44",
    "descriptor": "DESC2GB347",
    "billing_address_collection": "AUTO"
  },
  "shipping": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "ship2476@qq.com",
    "phone_number": "+1234567890",
    "address_line1": "789 Pine Road",
    "country": "GB",
    "state": "England",
    "city": "London",
    "postal_code": "85745",
    "area_code": "44"
  },
  "payment": {
    "payment_method": "PROMPT_PAY",
    "shopper_reference": "shopper_ref_xxxxxxxxxxxx"
  },
  "browser": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    "color_depth": "24",
    "language": "zh-CN",
    "java_enabled": true,
    "device_type": "MOBILE",
    "terminal_type": "WEB",
    "device_os": "IOS",
    "timezone_offset": "-07:10",
    "screen_height": "1080",
    "screen_width": "1920",
    "cookies": "cookie_xxxxxxxxxxxx",
    "device_finger_print_id": "fp_xxxxxxxxxxxxxxxxxxxx"
  }
}
```

#### Response Example

```json
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "YOUR_MERCHANT_ID",
    "trans_id": "m_your_unique_transaction_id",
    "order_id": "GW_your_order_id",
    "status": "PROCESSING",
    "amount": 9212230,
    "currency": "THB",
    "expire_time": "2026-06-04T18:27:00+08:00",
    "payment": {
      "payment_method": "PROMPT_PAY",
      "payment_data": {
        "next_action": "SCAN_CODE",
        "qr_code": "https://uat-checkout.payloco.com/#/simulation?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&authTraceId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&channelResponseId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&paymentCur=THB&paymentAmount=9212230"
      }
    }
  }
}
```

- `payment.payment_method`: payment method used.
- `payment.payment_data.next_action`: `SCAN_CODE` — payer scans the QR code.
- `payment.payment_data.qr_code`: QR URL or payload for display.


Poll status with **Transaction Query** below.

Refunds (full or partial) are **not supported** for PromptPay at this time.

## Transaction Query

Query transaction status by `order_id` and/or `trans_id`.

[Query Transaction](/payments/apis/payments/openapi/transaction/payments-query-opl_1)

#### Request Example

```json
{
  "merchant_id": "YOUR_MERCHANT_ID",
  "trans_id": "m_your_unique_transaction_id",
  "order_id": "GW_your_order_id"
}
```

#### Response Example

```json
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "YOUR_MERCHANT_ID",
    "trans_id": "m_your_unique_transaction_id",
    "order_id": "GW_your_order_id",
    "status": "SUCCESS",
    "error_code": "0000",
    "error_description": "request success",
    "amount": 9212230,
    "currency": "THB",
    "pay_finish_time": "2026-06-03T18:35:12+08:00"
  }
}
```