QR Code Payments

This guide explains how to process QR code payments through the Villa Payment API using KBank's payment gateway.

Prerequisites

Before processing QR code payments, you must:

1. Create a KBank order using the KBank Order Management API
2. Obtain the order_id from the order creation response

Processing QR Payment

After creating an order, you can process the payment using KBank's payment gateway form. Here's how to implement it:

Example: Creating a KBank Order

Before processing the QR payment, you need to create a KBank order. Here's an example of how to do that:

curl -X POST {{API_BASE_URL}}/kbank/order \
  -H "Authorization: YOUR_COGNITO_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderid": "test_order_id",
    "source": "wechat"
  }'

Response

After creating the order, you will receive a response like this:

{
  "id": "order_test_222110adff3affb5844c497fa9c22366b5bc6",
  "object": "order",
  "created": "20250530205658833",
  "livemode": false,
  "amount": 300.0,
  "currency": "THB",
  "customer": null,
  "description": "Order 492500004632",
  "metadata": null,
  "status": "success",
  "reference_order": "4925000046321748613417.737979",
  "source_type": "qr",
  "additional_data": {
    "term": null,
    "mid": null,
    "tid": null,
    "smartpay_id": null,
    "campaign_id": null
  },
  "failure_code": null,
  "failure_message": null,
  "expire_time_seconds": 3600
}

Form Parameters

Parameter	Type	Description
data-apikey	string	Your KBank payment gateway API key
data-amount	string	Payment amount
data-payment-methods	string	Payment method (qr for QR code payments)
data-order-id	string	The order ID from KBank order creation

Response

After successful payment processing, you'll receive a response in this format:

{
  "id": "order_test_222110adff3affb5844c497fa9c22366b5bc6",
  "object": "order",
  "created": "20250530205658833",
  "livemode": false,
  "amount": 300.0,
  "currency": "THB",
  "customer": null,
  "description": "Order 492500004632",
  "metadata": null,
  "status": "success",
  "reference_order": "4925000046321748613417.737979",
  "source_type": "qr",
  "additional_data": {
    "term": null,
    "mid": null,
    "tid": null,
    "smartpay_id": null,
    "campaign_id": null
  },
  "failure_code": null,
  "failure_message": null,
  "expire_time_seconds": 3600
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the order
object	string	Object type (always "order")
created	string	Creation timestamp
livemode	boolean	Whether this is a live mode order
amount	number	Order amount
currency	string	Currency code (e.g., THB)
customer	object	Customer information (nullable)
description	string	Order description
metadata	object	Additional metadata (nullable)
status	string	Order status
reference_order	string	Reference order number
source_type	string	Source type of the payment (qr or wechat)
additional_data	object	Additional payment data
failure_code	string	Error code if payment failed (nullable)
failure_message	string	Error message if payment failed (nullable)
expire_time_seconds	integer	Time until order expires in seconds

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 500: Internal Server Error

Example error response:

{
  "error": {
    "code": "invalid_order",
    "message": "Invalid order ID."
  }
}

Best Practices

1. Always create an order first before initiating payment
2. Implement proper error handling
3. Store transaction IDs for reconciliation
4. Use HTTPS for all API calls
5. Monitor payment status
6. Handle payment expiration scenarios

Testing

For testing QR payments:

1. Use test user accounts
2. Create test orders
3. Verify payment processing
4. Test payment status checks
5. Validate error handling
6. Test expiration scenarios

Support

Need help with QR payments? Please contact our support team for assistance.