This document outlines the structure and usage of the Debit Payment API for processing Thai QR debit payments.
✅ API Overview
This API is used by merchants to initiate Thai debit payments using QR-based payment methods. The system will return a redirect URL for the user to complete the payment.
🔒 Endpoint
POST /transaction/s2s
Content-Type: application/json
📥 Request Payload
| Field | Type | Required | Description |
|---|---|---|---|
merchantid | string | Yes | Unique Merchant ID issued by the gateway |
password | string | Yes | API password or secret key |
payment_method.type | string | Yes | Payment type, use "THAI_DEBIT" |
trackid | string | Yes | Unique transaction reference from the merchant |
bill_currencycode | string | Yes | Currency code, e.g., "THB" |
bill_amount | string | Yes | Amount to be billed Min 100 |
bill_country | string | Yes | Country code (ISO Alpha-2), e.g., "MU" |
bill_customerip | string | Yes | IP address of the customer |
bill_email | string | Yes | Customer email address |
returnUrl | string | Yes | URL to redirect customer after payment |
serverUrl | string | Yes | URL to receive payment result as webhook |
payer_account_no | string | Yes | Customer’s debit account number |
payer_account_name | string | Yes | Name associated with the payer's account |
payer_bank_code | string | Yes | Bank code of the payer |
📦 Sample Request
{
"merchantid": "TEST001",
"password": "*",
"payment_method": {
"type": "THAI_DEBIT"
},
"trackid": "10012024",
"bill_currencycode": "THB",
"bill_amount": 1,
"bill_country": "MU",
"bill_customerip": "102.119.15.157",
"bill_email": "[email protected]",
"returnUrl": "https://webhook.site/7590c003-5bec-441e-b1d5-993d87bb35b6",
"serverUrl": "https://webhook.site/8d5db35a-ef94-4d7f-8c31-cc996c13b833",
"payer_account_no": "123456789012",
"payer_account_name": "Vivek N",
"payer_bank_code": "014"
}
📤 Response Payload
| Field | Type | Description |
|---|---|---|
type | string | Status of request (valid or error) |
result | string | Result of the transaction initialization |
responsecode | string | Numeric response code (9 means success) |
trackid | string | Same track ID provided in request |
merchantid | string | Echo of the merchant ID |
redirectUrl | string | URL to redirect the customer to complete payment |
token | string | Transaction token |
error_code_tag | string | Error code (if any) |
error_text | string | Error description (if any) |
transactionid | string | Unique ID generated by payment gateway |
📦 Sample Success Response
{
"type": "valid",
"result": "Processing",
"responsecode": "9",
"trackid": "123455",
"merchantid": "TEST001",
"redirectUrl": "https://api.key2payment.com/transaction/Redirect?ID=8913bfff-33be-4b87-b920-23a78d5ec8d2",
"token": "1d85ca154e754b4596128b00a5b21d1c",
"error_code_tag": null,
"error_text": null,
"transactionid": "1001547"
}
🔁 Webhook Notification (serverUrl)
After the transaction is processed, the system will POST a JSON payload to the provided serverUrl.
Make sure your server handles this notification to update the order/payment status.
🚦Response Code Meaning
| Response Code | Meaning |
|---|---|
| 9 | Processing |
| 0 | Success |
| 6 | Failed |
| Other values | As defined in error messages |
🧪 Testing Details
To simulate real-world success/failure flows in a sandbox/test environment:
| Condition | Simulated Outcome |
|---|---|
bill_amount ≤ 10000 THB | ✅ Success — transaction completes normally |
bill_amount > 10000 THB | ❌ Failure — transaction will be rejected |
Use amounts like 1000, 5000, or 9999.99 to simulate successful transactions.
Use amounts like 10000.01, 15000, etc., to trigger failure responses.