Bualuang Smart Bill Payment

Bill Payment Service real time notification on payment confirmation

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.

POST Smart bill notification (BBL > Merchant system)

API Initiator: Bank's System (BBL)
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]

Request Header

No.	Parameter	Type	Size	Description	Example/Values
1	Authorization	string	100	Basic authentication Token encode with Base64 String = [client_id] : [client_secret] Basic [Token]	Basic c3FIOG9vSGV4VHoAyg5 T1JvNnJoZ3ExaVNyQW w6WjRsanRKZG5lQk9q UE1BVQ
2	Signature	string	-	Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure
3	Request-Ref	string	20	Notify request reference (Unique)	TXN20171120-0000023
4	Transmit-Date-Time	string	29	Response transmit date time with Time zone format: ‘yyyy-MM-dd’T’HH:mm:ss.SSS+07:00’	2017-03-15T15:23:11.001+07:00

Request Body

No.	Parameter	Type	Description	Example/Values
1	data	Object	Object of Request Data

Data Object

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	2022-10-18
3	transTime	string	8	Y	Transaction Time HH:mm:ss	14:51:32
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	80
5	amount	string	16	Y	Payment amount = 13 digits + . + 2 decimal Ex. xxxx.xx	666.00
6	reference1	string	30	Y	First Reference number of the transaction from Partner	123456789
7	reference2	string	30	N	Second Reference number of the transaction from Partner	20171106151550
8	reference3	string	30	N	Third Reference number of the transaction from Partner	5555555
9	fromBank	string	3	Y	From bank code. Right-aligned. Left-padded with zeros.	002
10	fromBranch	string	6	N	From branch code.	0123
11	fromName	string	50	N	Payer name Eng/Thai(UTF-8)	ITTest
12	bankRef	string	25	N	BBL reference	2022101914273423001321408
13	approvalCode	string	6	N		123456
14	txnType	string	1	N	“C”: payment transaction “D”: payment was cancelled/deleted	C
15	retryFlag	string	1	Y	Notification retry flag “Y” for retry/resend message “N” for original message	N

Example request

{
  "billerId":"123456789012345",
  "fromBank":"002",
  "fromBranch":"0123",
  "amount":"5024.00",
  "approvalCode":"123456",
  "retryFlag":"N",
  "transTime":"14:51:32",
  "transDate":"2022-10-19",
  "termType":"80",
  "txnType":"C",
  "fromName":"ITTest",
  "reference1":"123456789",
  "reference2":"20171106151550",
  "reference3":"5555555",
  "bankRef":"2022101914273423001321408"
}

Response Header

No.	Parameter	Type	Size	Description	Example/Values
1	Signature	string	100	Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure
2	Request-Ref	string	30	Notify request reference (Unique)	TXN20171120-0000023
3	Transmit-Date-Time	string	29	Response transmit date time with Time zone format: ‘yyyy-MM-dd’T’HH:mm:ss.SSS+07:00’	2017-03-15T15:23:11.001+07:00

Response Body

No.	Parameter	Type	Size	Mandatory	Description	Example/Values
1	responseCode	string	3	Y	Response Code	0000
2	responseMsg	string	50	Y	Response Message	success

Example Response

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

Response Code

Status Code	Message Code	Message	Remark
200	052	Unknown Biller ID	Invalid Biller ID
401	-	Unauthorized	Authorization fail.
200	211	Invalid format Signature	Header in Response not have Signature
200	215	Invalid Token	Decode payload in JWT token not equal response payload
200	000	Success	Response success
200	054	Internal System Unavailable	Response of business backend
200	210	Time out	Time out
200	211	Invalid Data	Invalid business data
200	341	Service Provider not ready	Partner system error
200	888	Other Error	-

HTTP Error Response Codes

HTTP Status Code	Response 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