Bualuang Smart Bill Payment

Bill Payment Service real time notification on payment confirmation

API Security

Digital Signature & Structure (JWT)

JSON Web Token (JWT) is a fundamental security component for Bangkok Bank APIs. In every API request to the Bangkok Bank API Gateway, inclusion of a JWT in the header is crucial. This token, resulting from payload encryption using the merchant's private key, undergoes verification by Bangkok Bank using the merchant-provided public key. This process ensures the validity of the request, augmenting our OAuth Authentication for dual-layer security against cyber threats such as man-in-the-middle attacks.

In general, JSON Web Tokens (JWTs) consist of three main components: the Token Header, the Token Payload, and the Signature. These components work together to encode information securely for transmission between parties.

Understanding how Bangkok Bank implements JWT is crucial for successful integration. The following steps outline what are required from a developer's perspective:

Preparing the Public and Private Key pair
- Before initiating any API requests, merchants need to generate a secure Public and Private Key pair. These keys will be crucial for the cryptographic operations involved in JWT processing.
Preparing the Payload
- As part of an API request, merchants construct a JSON payload containing essential information. This JSON payload serves as the basis for the JWT claim and carries details pertinent to the specific request.
- This JSON payload is used as the JWT claim.
Generating the JWT
- The merchant uses their private key to sign the JWT. This involves encoding the header and payload, concatenating them, and then applying the signature algorithm using the private key.
- The result is the JWT.
Verifying the JWT
- Bangkok Bank, upon receiving the API request, uses the merchant's public key to verify the JWT.
- The signature is verified, and claims within the payload are extracted and validated.

Remark:

The signature token follows the standard JSON Web Token format RFC 7519

By following these steps, merchants can seamlessly integrate JWT authentication with Bangkok Bank's API, ensuring secure and reliable communication. It is recommended to securely store and manage the generated keys throughout the implementation process.

For more details on how to generate JWT for Digital Signature, please refer to our guide here.

API Overview & Specification

Using bill payment API, Bangkok Bank system will send the payment confirmation notification to merchant's system via provided notification endpoint during onboarding. This API provides merchant's system with near real-time status about the status of payment transactions.

In case that the bank is unable to send the payment confirmation due to connection lost or timeout, the bank will attempt to make retry (max 3 retries).

POST {MERCHANT_NOTIFICATION_URL}

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

PROD:
{MERCHANT_NOTIFICATION_URL}

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Basic authentication Token encode with Base64 String = {username}:{password} Basic {token}	`Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ`
Signature	String		Y	Digital Signature sign with JWT RSA256	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Notify request reference (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Response transmit date time with Time zone Format yyyy-MM-dd’T’HH:mm:ss.SSS+\|-hh:mm	`2017-03-15T15:23:11.001+07:00`

Request Body

Parameter	Type	Size	Mandatory	Description	Example/Values
data	Object
data .billerId	String	15	Y	TaxId and Suffix of the Payee	`123456789012345`
data .transDate	String	10	Y	Transaction date Format yyyy-MM-dd	`2022-10-18`
data .transTime	String	8	Y	Transaction time Format HH:mm:ss	`15:21:35`
data .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`
data .amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx	`500.00`
data .reference1	String	30	Y	First Reference number of the transaction from Partner	`123456789`
data .reference2	String	30	N	Second Reference number of the transaction from Partner	`20171106151550`
data .reference3	String	30	N	Third Reference number of the transaction from Partner	`5555555`
data .fromBank	String	3	Y	From bank code. Right-aligned. Left-padded with zeros.	`002`
data .fromBranch	String	6	N	From branch code.	`0123`
data .fromName	String	50	N	Payer name Eng/Thai (UTF-8)	`ITTest`
data .bankRef	String	25	N	BBL reference	`2022101914273423001321408`
data .approvalCode	String	6	N		`123456`
data .txnType	String	1	N	C: payment transaction D: payment was cancelled/deleted	`C`
data .retryFlag	String	1	Y	Notification retry flag: Y: for retry/resend message N: for original message	`N`

Request Body Example

{
    "data": {
        "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 Body

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

Response Body Example (Success)

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

Response Body Example (Failure)

{
    "responseMesg": "Invalid data",
    "responseCode": "211"
}

Response HTTP Status

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