Balance & Banks
Bank List
Fetch the public bank master keyed by bank_code, used to set receiver_bank_provider on withdrawals
GET /v1/banks
Returns the master list of Thai banks. Each entry's bank_code is the value you send in receiver_bank_provider when creating a withdrawal.
This is the only endpoint under
/v1 that does not require authentication (no API key / HMAC), because it is static reference data (the Thai bank master) that doesn't depend on any merchant.Endpoint
- Method / Path:
GET /v1/banks - Auth: none (public)
- Cache: the response carries the header
Cache-Control: public, max-age=3600— the data is static, so cache it on your side (at least 1 hour permax-age) instead of refetching on every request.
Response shape
The response is a JSON object (map) where the key of each entry is its bank_code (e.g. "SCB", "KBANK") — not an array. Each entry has these fields:
| Field | Type | Description |
|---|---|---|
bank_code | string | The bank's alias code (canonical enum), e.g. "SCB" — use this value to identify the bank on a withdrawal (send it as receiver_bank_provider). |
bank_number | string | The 3-digit BOT bank code, e.g. "014" — display / reference only. Do not use it to identify the bank on a withdrawal. |
name_th | string | Short Thai name, e.g. "ไทยพาณิชย์". |
fullname_th | string | Full Thai name, e.g. "ธนาคารไทยพาณิชย์". |
name_en | string | English name, e.g. "The Siam Commercial Bank". |
bank_code vs bank_number
bank_codeis the value that actually "identifies the bank" in the system. When creating a withdrawal (POST /v1/withdrawals, fieldreceiver_bank_provider) you must send abank_codeonly. The system validates it against the master — an unknown value returns errorINVALID_BANK(HTTP 422). The comparison is case-insensitive ("scb"or"SCB"both work; the system normalizes to uppercase).bank_number(the 3-digit BOT code) is display / reference only. The system does not use it to match or identify a bank. Never sendbank_numbertoreceiver_bank_provider.
Rails like PromptPay / TrueMoney are payment rails, not banks in this list — they do not appear in
/v1/banks and cannot be used as a bank_code.Example request
cURL
curl -X GET 'https://api.unkpay.co/v1/banks'
Example response (200 OK)
{
"SCB": {
"name_th": "ไทยพาณิชย์",
"fullname_th": "ธนาคารไทยพาณิชย์",
"name_en": "The Siam Commercial Bank",
"bank_code": "SCB",
"bank_number": "014"
},
"KBANK": {
"name_th": "กสิกรไทย",
"fullname_th": "ธนาคารกสิกรไทย",
"name_en": "Kasikorn Bank",
"bank_code": "KBANK",
"bank_number": "004"
},
"BBL": {
"name_th": "กรุงเทพ",
"fullname_th": "ธนาคารกรุงเทพ",
"name_en": "Bangkok Bank",
"bank_code": "BBL",
"bank_number": "002"
}
}
The example above is truncated. The real master currently has many banks (e.g. BBL, KBANK, KTB, TTB, SCB, BAY, GSB, KKP, etc.). Fetch from this endpoint and cache it — don't hardcode the list on your side.
Diagram coming soon — Example of the merchant-side bank-selection dropdown populated from GET /v1/banks (showing name_th + bank_number, sending bank_code to the backend)