KBank Order Management

This guide explains how to create and manage KBank payment orders through the Villa Payment API.

API Base URLs

The Villa Payment API is available in two environments:

• Development: https://shop.villamarket.com/api/payment3devapi
• Production: https://shop.villamarket.com/api/payment3api

Replace {BASE_URL} in the examples below with the appropriate base URL for your environment.

Processing a QR Payment

To process a payment using QR code:

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

Request Parameters

Parameter	Type	Description
orderid	string	The ID of the order to process
source	string	Source of the QR payment (qr or wechat)

Response

{
  "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_amount",
    "message": "Invalid payment amount."
  }
}

Best Practices

1. Validate order data before submission
2. Handle API errors gracefully
3. Implement proper error logging
4. Use idempotency keys for retries
5. Monitor order status changes
6. Implement webhook notifications
7. Keep track of refund status

Testing

For testing order management:

1. Use test amounts
2. Test all payment methods
3. Verify order status changes
4. Test cancellation flow
5. Test refund process
6. Validate metadata handling