บริการชำระค่าสินค้าด้วยคิวอาร์โค้ด

บริการรับชำระเงินผ่าน QR Code สะดวก ปลอดภัย ชำระได้ทุกธนาคาร

QR Payments

Technical flow

Digital Signature Token Structure

The signature token follows the standard JSON Web Token format RFC 7519 contains the
following claims (elements)

Token HEADER

Claim	Description	Example
typ	Type	JWT
alg	Algorithm	RS256
Body Claim	API Request Payload / API Response Payload	API JSON Request Payload/API JSON Response Payload
"exp" (Expiration Time) Claim	Now + 1 Day (timestamp)	1655995873
"Iat" (Issued At) Claim	Time to create token (timestamp)	1655967073
jti (JWT ID) Claim	UUID	ba7544f4-a7c5-4362-8009-51f1ab25 e132

Verify Token Signature

RSASHA256(base64UrlEncode(header) + "." +base64UrlEncode(payload),Public key,Private key)

Guide to generating certificate for JWT Signature:

Generating a Private Key (Used for signing digital signatures.) :
```
openssl genrsa -aes256 -out private_key.pem 2048 
```
Generating a Public Key (Used for validation digital signatures.):
```
openssl rsa -pubout -in private_key.pem -out public_key.pem
```

For production, it is not recommended to use the self-sign certificate.

oAuth Client Credentials

POST /oauth/accesstoken

Header

Parameter	Type	Size	Description	Example/Values
Authorization	string	100	Basic authentication Token encode with Base64 String = [client_id] : [client_secret] Basic [Token]	Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ

Header request example

curl --request POST ' https://api-sandbox.bangkokbank.com/oauth/accesstoken' \
--header 'Authorization: Basic b2hSQllvMExBVkE5RVJ2MERZeGJNb3FnRWpCT3B5WjU6WUNCam50RWlBazN2Y2NGdw==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=READ CREATE' \
--data-urlencode 'grant_type=client_credentials'

Form parameter

Parameter	Type	Size	Description	Example/Values
grant_type	string	20	oAuth grant type	“client_credentials”

grant_type=client_credentials

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
accessToken	string	100	Y	Token for call API	ds9PIkzbNwXffsDHLPW4auli0NAN
expiresIn	string	100	Y	Time to expire token	86399
scope	string	100	N	Scope token defined by BBL depending on sub-service	Null, READ

{
   "accessToken":"VAGw4iJj5peD2fXlVsI2GhS1Hblp",
   "expiresIn":"86399",
   "scope":""
}

Thai QR Inquiry API

Web Services: RESTful JSON
HTTP Method: POST
Character encoding: UTF-8
Content Type: application/json
Authorization: Bearer authentication(oAuth token Client Credential grant type)
Request URL: /biller/v1/qr-inquiry

https://api-sandbox.bangkokbank.com/biller/v1/qr-inquiry

Technical flow

POST /biller/v1/qr-inquiry

Request Header

No.	Parameter	Type	Size	Description	Example/Values
1	Authorization	string	100	Access token of oAuth token Client Credential type Bearer [accessToken]	Bearer ylSkZIjbdWybfsUQe9BqP0LH 5Z
2	Signature	string	-	Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure
3	Tansmit-Date Time	string	29	Request transmit date and time with Time zone Format: ‘yyyy-MM-dd’T’HH:mm:ss. SSS+\|-hh:mm’	2017-03-15T15:23:11.001+07:00
4	Request-Ref	string	30	Transaction tracking no. (Unique)	TXN20171120-0000023

Example header request

curl -X POST \
  https://api-sandbox.bangkokbank.com/biller/v1/qr-inquiry \
  -H 'authorization: Bearer Rmr5dpGTBwaDtWq4SXDndOq9f70k' \
  -H 'cache-control: no-cache' \
  -H 'signature: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJib2R5Ijoie1xyXG4gICAgXCJiaWxsZXJJZFwiOlwiMTIzNDU2Nzg5MDEyMzRcIixcclxuICAgIFwidHJhbnNEYXRlXCI6XCIyMDE3LTExLTA2XCIsXHJcbiAgICBcImFtb3VudFwiOjE1MDAuNzUsXHJcbiAgICBcInJlZmVyZW5jZTFcIjpcIjU1NTU1NTU1XCIsXHJcbiAgICBcInJlZmVyZW5jZTJcIjpcIjIwMTcxMTA2MTIyNTUwXCJcclxufSIsImV4cCI6MTY1NjQzMDg0MCwiaWF0IjoxNjU2NDAyMDQwLCJqdGkiOiIyNTY0MDE4MC1iMjJjLTQ3N2MtYWQzMy0xMDUyNzA0OThmZGYifQ.LkDu-2cyg_DuhcmUiT6_nVWUMpI5rjHr8CRqhCCRvQ-NAr6s6jgMXFXdHpKOZHdbUIz_fyVYzXk2Biw9DQ8Zu_xFMLXyuAzREv64tLOd9K0RHqh_-GmlqpFKa46EoKi0EdNp3MGfnUsuT5VG2z7fWypTFj5mSblvUoL4bXRKHCnhCuO7jGvieCYOmChrq6AqusIDD-t8xuk1boj247GF9VwP-nbMgLIdYUxhNEgsFh0xQm3aJgyrOdnGXXUgX0JosXp3q4dEauZBYIo3mOl_ZgfIHxRCGyu1d1Ns4vTfytv6ccG0Ba6IMgU6_LKopHsEm9kwW9TsXWJ2Nqj8F1zEXi_peN3S-fwLW1ooqzc_Rwp7k0pl6YXzCC_vhJUSRV_s_0kZmkbBpAcPjIPESO6ziF_wSEYZaEwLwZcg8Qti-pk7Gc6suTZkNINpHGWmOVCkLpy9CfBOeuibnca1xH7st_lVe1FW_QM72kVyZvs_NKbKM2FJ5PHrr9wv5wbjzncuRKv8RjIxYw-px0oWsMHtS3Fiy6ZBwAdtvIe0zrGdQNS58SxuQNsIqkIjpQj2bwKrrQkFEml_4uKOYpMbi_2QTvi9EDS8az_ZlAjxa18L0F0kVteUKrm-mkBJasrlFUGAu5L0ZvalrPMqMKP99gg5xag7o5zeZZilVl0aN-LBB38' \
  -d '{
    "billerId":"123456789012345",
    "transDate":"2017-11-06",
    "amount":"1500.75",
    "reference1":"123456789",
    "reference2":"20171106122550"
}'

Request Body

No	Parameter	Type	Size	Mandatory	Description	Example/Values
1	billerId	string	15	Y	TaxId and Suffix of the Payee	123456789012301
2	transDate	string	10	N	Transaction date yyyy-MM-dd	2023-03-15
3	amount	string	16	Y	Payment amount = 13 digits + . + 2 decimal Ex. xxxx.xx	1500.25
4	reference1	string	30	Y	First Reference number of the transaction from Merchant	123456789
5	reference2	string	30	N	Second Reference number of the transaction from Merchant	1124579998
6	reference3	string	30	N	Third Reference number of the transaction from Merchant	1124579998

Example request

{
   "billerId":"123456789012345",
   "amount":”5024.00”,
   "reference3":"",
   "transDate":"2022-11-16",
   "reference1":"123456789",
   "reference2":"077259"
}

Response body

No	Parameter	Type	Size	Mandatory	Description	Example/Values
1	responseCode	string	3	Y	000 if successful transmitted request to Provider Service and received response	000
2	responseMesg	string	50	Y	Error message
3	data	Object		N	Object Response

Example Response

{ "responseCode":"000",
  "responseMesg":"Success",
  "data":{
     "billerId":"123456789012345",
     "transDate":"2022-11-16",
     "transTime":"15:34:56",
     "termType":"80",
     "amount":"5024.00",
     "reference1":"123456789",
     "reference2":"077259",
     "fromBank":"001",
     "fromName":"ITTest",
     "bankRef":"2022111615350123001449008",
     "approvalCode":"395992"
  }
}

Mapping Data Object Response Body

No.	Parameter	Type	Size	Mandatory	Description	Example/Values
1	billerId	string	15	Y	TaxId and Suffix of the Payee	123456789012345
2	transDate	string	10	Y	Transaction date yyyy-MM-dd	2017-11-06
3	transTime	string	8	Y	Transaction Time HH:mm:ss	17:57:50
4	termType	string	2	Y	Terminal Type (Channel) 10 –IVR 20 -KIOSK 30 -ATM 40 -EDC/POS 50 -COUNTER 60 –IBANKING 70 -CDM 80 -MBANKING	10
5	amount	string	16	Y	Payment amount = 13 digits + . + 2 decimal Ex. “xxxx.xx”	1500.75
6	reference1	string	30	Y		120213405
7	reference2	string	30	N		120213405
8	reference3	string	30	N		120213405
9	fromBank	string	3	Y	From bank code. Right-aligned. Left-padded with zeros.	001
10	fromName	string	50	N	Payer name Eng/Thai(UTF-8)	ITTest
11	bankRef	string	25	N	BBL reference
12	approvalCode	string	6	N		123456

Thai QR Verify Online API

API Initiator: Bangkok Bank

Web Services: RESTful JSON
HTTP Method: POST
Character encoding: UTF-8
Content-Type: application/json
Authorization: Basic Authentication Format: Basic (Base64Encode(Username:Password))
Request URL: https://[MERCHANT_CALLBACK_URL]

Technical flow

POST /biller/v1/qr-verify

Request Header

Parameter	Type	Size	Description	Example/Values
Authorization	string	100	Basic authentication Token encode with Base64 String = [client_id] : [client_secret] Basic [Token]	Basic c3FIOG9vSGV4VHoAyg 5T1JvNnJoZ3ExaVNyQW w6WjRsanRKZG5lQk9qU E1BVQ
Signature	string	-	Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure

Response header

Parameter	Type	Size	Description	Example/Values
Signature	string	-	Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure

Request body

No	Parameter	Type	Size	Mandatory	Description	Example/Values
1	billerId	string	15	Y	TaxId and Suffix of the Payee	123456789012301
2	transDate	string	10	N	Transaction date yyyy-MM-dd	2018-03-15
3	amount	string	18	Y	Payment amount 2 decimal Ex. xxxx.xx	1500.25
4	reference1	string	30	Y	First Reference number of the transaction from Merchant	12345678901230 0
5	reference2	string	30	N	Second Reference number of the transaction from Merchant	1124579998
6	reference3	string	30	N	Third Reference number of the transaction from Merchant	1124579998

Example request

{
   "billerId":"123456789012345",
   "amount":"1500.75”,
   "transTime":"16:24:37",
   "reference3":"",
   "transDate":"2022-10-12",
   "reference1":"123456789",
   "reference2":"077259"
}

Response body

Name	Type	Size	Mandatory	Description	Example/Values
responseCode	string	3	Y	Response Code	000
responseMesg	string	50	Y	Response Message	success
shopName	string	50	N	Merchant/Shop English Name This field can be English CAPITAL letter, Numeric (0-9) and special characters.	123456789012301

Example response

{
   "responseMesg":"Success",
   "responseCode":"000",
   "shopName":"ITTest"
}

Thai QR Notification API

API Initiator: Bangkok Bank

Web Services: RESTful JSON
HTTP Method: POST
Character encoding: UTF-8
Content-Type: application/json
Authorization: Basic
Authentication Format: Basic (Base64Encode(Username:Password))
Request URL: https://[MERCHANT_CALLBACK_URL]

POST QR Notification (BBL > Merchant system)

Request Header

Parameter	Type	Size	Description	Example/Values
Authorization	string	100	Basic authentication Token encode with Base64 String =[client_id] : [client_secret] Basic [Token]	Basic c3FIOG9vSGV4VHoAyg 5T1JvNnJoZ3ExaVNyQW w 6WjRsanRKZG5lQk9qU E1BVQ
Signature	string	-	Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure

Request Body

Parameter	Type	Description	Example/Values
data	Object	Object of Request Data
type	string	Type of Notification	ThaiQR

Example Request

{
  "type":"ThaiQR",
  "data":{
    "billerId":"123456789012345",
    "fromBank":"002",
    "amount":"5024.00",
    "approvalCode":"172455",
    "retryFlag":"N",
    "transTime":"14:27:28",
    "transDate":"2022-10-19",
    "termType":"80",
    "fromName":"ITTest",
    "reference1":"123456789",
    "reference2":"077259",
    "bankRef":"2022101914273423001321408"
  }
}

Response Header

Parameter	Type	Size	Description	Example/Values
signature	string	-	Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	string	3	Y	Response Code	000
responseMesg	string	50	Y	Response Message	success

Example Response

{
   "responseMesg":"Success",
   "responseCode":"000"
}

Response Code

Response Code Mapping for Thai QR Inquiry Online

Status Code	Message Code	Message	Remark
200	000	Success	Success
200	211	Invalid data	Header in Response missing have Signature or Invalid Request body parameters or Response of business backend
401	-	Unauthorized	Authorization fail ( Access token or JWT Signature)
403	052	Unknown Biller ID	Biller ID or Service Code not register
200	054	System unavailable	Response of business backend
200	209	Transaction not found	Transaction not found
200	210	Time out	Time out
200	341	Service not ready	Response of business backend
200	888	Other errors	Response of business backend

Response Code Mapping for Thai QR Verify Online

Status Code	Message Code	Message	Remark
200	000	Success	Success
200	211	Invalid data response	Header in Response not have Signature or Invalid JSON. Invalid Basic Authentication Token.
200	215	Invalid token	Invalid JWT Token.
401	-	Unauthorized	Authorization fail ( Access token or JWT Signature)
403	052	Unknown Biller ID	Biller ID or Service Code not register
200	054	System unavailable	Response of business backend
200	209	Transaction not found	Transaction not found
200	210	Time out	Time out
200	341	Service Provider not ready	Partner system error
200	888	Other errors	Response of business backend

Response Code Mapping for Thai QR Notification

Status Code	Message Code	Message	Remark
200	000	Success	Success
200	211	Invalid data response	Header in Response not have Signature or Invalid JSON. Invalid Basic Authentication Token.
200	215	Invalid token	Invalid JWT Token.
401	-	Unauthorized	Authorization fail ( Access token or JWT Signature)
403	052	Unknown Biller ID	Biller ID or Service Code not register
200	054	System unavailable	Response of business backend
200	209	Transaction not found	Transaction not found
200	210	Time out	Time out
200	341	Service Provider not ready	Partner system error
200	888	Other errors	Response of business backend

HTTP Error Response Code

Status Code	Reason Phrase
200	Success
401	Unauthorized
403	Forbidden
400	Bad Request
404	Resource not found
429	Too many requests
500	Internal Error
503/504	Service Unavailable