PromptPay

Cash and Codes Bundle

PromptPay is Thailand's national real-time payment and QR infrastructure, widely used for bank transfers and merchant payments through mobile banking and e-wallet apps. It enables consumers to pay instantly using their bank account or e-wallets by scanning a QR code. PromptPay payments allow merchants to collect funds in real time through interoperable bank rails trusted across the country.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.

How it works

Web flow

1. The customer selects PromptPay as their payment method at checkout.
2. A QR code is displayed on the screen.
3. The customer logs into their bank app or e-wallet and scans the QR code.
4. The customer confirms the purchase using the desired app.
5. The merchant receives a success notification after confirmation.

Mobile browser flow

1. The customer selects PromptPay as their payment method at checkout.
2. A QR code is displayed on the screen. The customer takes a screenshot of the QR code.
3. The customer logs into their bank or e-wallet app on their mobile phone.
4. The customer loads the QR code screenshot using their app.
5. The customer confirms the purchase using the app.
6. The merchant receives a success notification after confirmation.

Payment confirmation

Once the transaction is successful, the customer receives a confirmation on their banking or e-wallet app, and the merchant is updated with the transaction status. EBANX sends you a notification confirming the successful transaction, allowing you to fulfill your customer's order.

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing or the production environment for live transactions.

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/direct

2. Create a PromptPay payment

   To create a PromptPay payment, define the parameters in your request. The following tables outline the required parameters for the payment process.

   Basic parameters

   Parameter	Requirement	Description
   integration_key	Required	Your EBANX integration key
   payment_type_code	Required	Set to promptpay
   country	Required	Set to th for Thailand

   Customer data

   Parameter	Requirement	Description
   name	Required	Customer name
   email	Required	Customer email
   phone_number	Optional	Customer phone

   Charge parameters

   Parameter	Requirement	Description
   merchant_payment_code	Required	Unique merchant payment code
   currency_code	Required	Supported value: THB
   amount_total	Required	Total amount to be charged

   Transaction limits

   PromptPay has a minimum amount of THB 20.00 and a maximum of THB 150,000.00. Please note these are generic limits; actual limits are subject to the type of wallet and bank app being used.

3. Send payment request

   Send the following request to initiate a PromptPay payment.

   cURL Request (Sandbox Example)

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "operation": "request",
       "payment": {
         "name": "John Doe",
         "email": "john.doe@example.com",
         "country": "th",
         "phone_number": "5555555555",
         "payment_type_code": "promptpay",
         "merchant_payment_code": "{{merchant_payment_code}}",
         "currency_code": "THB",
         "amount_total": 99.85,
         "redirect_url": "https://merchant.example.com/callback"
       }
     }'

   
   

   API Response Example

   A successful request will return a response similar to this:

   {
     "payment": {
       "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
       "country": "th",
       "merchant_payment_code": "{{merchant_payment_code}}",
       "order_number": null,
       "status": "PE",
       "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "99.85",
       "amount_ext": "99.85",
       "amount_iof": "1",
       "currency_rate": "1",
       "currency_ext": "THB",
       "due_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "instalments": "1",
       "payment_type_code": "promptpay",
       "pre_approved": false,
       "capture_available": null,
       "promptpay": {
         "qr_code_value": "{{qr_code_value}}",
         "expiration_date": "{{YYYY-MM-DD HH:mm:ss}}"
       }
     },
     "status": "SUCCESS"
   }

   • The qr_code_value contains a base64-encoded QR code image. On web, this is rendered as a QR code for the customer to scan.
   • On mobile web or app, users will need to download or screenshot the QR to be uploaded on their bank or e-wallet app.
   TIP

   PromptPay QR codes have an expiry period of 10 minutes. If a QR code is scanned after 10 minutes, the payment will fail. When testing in a sandbox, a simulator environment will be rendered to accept or decline the payment.

4. Monitor payment for status change

   At this stage, the payment will appear as pending (PE) in your

   EBANX Dashboardchevron_right

   After the user completes the payment, EBANX will send a CO (confirmed) payment status to the merchant.

   Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification that status has changed, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

5. Congratulations!

   You have successfully integrated PromptPay.

   For more information, refer to the

   Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.