Project

General

Profile

Actions
History

Customer WebApp » Subscription »

BBL Integration

Detail for API on BBL integration.

API Payment

Module Summary

Item Value
Base path /api/v1/bank/apipayment
Purpose Receiver lookup, transfer confirmation, and post-transfer inquiry for BBL account, other-bank account, and PromptPay flows
Inbound content type application/json
Inbound auth None at route layer
Outbound auth to BBL Internal only: Basic Auth + RSA signature
Local transaction type API_PAYMENT
Supported paymentType BBL, OTH, PP
Supported receiverType BANKAC, NATID, MSISDN
Upstream transType CASHLESS

Endpoint Matrix

Method Path Upstream BBL transCode Purpose Local side effects
POST /validation LOOKUP_AC, LOOKUP_OTH_AC, LOOKUP_PP Validate receiver and create a local transaction Inserts apipayments + transactions; status becomes 1100 or 2000
POST /confirm TRANSFER_AC, TRANSFER_OTH_AC, TRANSFER_PP Execute transfer using a prior lookupRef Marks local transaction 5000; updates API Payment transmit time and transaction code
GET /inquiry/:transactionID INQUIRY Query transfer result using local transaction ID Updates stored BBL reference number on the API Payment record

POST /validation Request Contract

Field Type Required Constraints Notes
receiverValue string Yes Non-empty Receiver account / PromptPay target
receiverType string Yes BANKAC, NATID, MSISDN PP flow only allows NATID or MSISDN
receiverBankCode string Conditional Length must be 3 for paymentType=OTH Ignored for BBL; internally forced to 002
paymentType string Yes BBL, OTH, PP Selects lookup / confirm flow
amount float64 Yes Positive amount expected Used in downstream lookup
additionalRef string No None Passed through to BBL where applicable
customerCode int Yes Must map to existing customer data Used to compare stored customer name vs BBL receiver name

POST /validation Success Response

Field Type Description
responseCode string BBL/business result code
responseMesg string Human-readable message
lookupRef string BBL lookup reference, required for /confirm
receiverName string Receiver name returned by BBL
requestRef string BBL request reference generated by this service
transactionID string Local transactions.id generated by this service
storedFullname string Uppercased full name loaded from local customer data
customerNameMatch bool true when storedFullname == receiverName

POST /confirm Request Contract

Field Type Required Constraints Notes
receiverValue string Yes Non-empty Same logical receiver as in validation
receiverType string Yes BANKAC, NATID, MSISDN PP flow only allows NATID or MSISDN
receiverBankCode string Conditional Length must be 3 for paymentType=OTH BBL flow internally uses 002
paymentType string Yes BBL, OTH, PP Must match the intended transfer flow
amount float64 Yes Positive amount expected Passed to BBL confirm call
additionalRef string No None Optional pass-through
smsMobileNo string No None Only forwarded in PromptPay confirm flow
smsLanguage string No None Only forwarded in PromptPay confirm flow
lookupRef string Yes Non-empty Must come from /validation response
origRequestRef string Yes Non-empty Must be the requestRef from /validation, not the local transactionID

POST /confirm Success Response

Field Type Description
responseCode string BBL/business result code
responseMesg string Human-readable message
transactionID string Local transactions.id resolved from origRequestRef
customerID int Local customer ID from the transaction
bankRefNo string BBL bank transfer reference number

GET /inquiry/:transactionID Request Contract

Item Type Required Notes
transactionID path param Yes Local transactions.id, not BBL reference

GET /inquiry/:transactionID Success Response

Field Type Description
responseCode string BBL/business result code
responseMesg string Human-readable message
transactionID string Local transaction ID
customerID int Local customer ID
inqRspCode string BBL inquiry response code
inqRspMesg string BBL inquiry response message
origRequestRef string Original BBL request reference used in confirm
origTransDateTime string Original transmit time used in confirm
bankRefNo string BBL bank reference number

API Payment Status Lifecycle

Event Local status
Validation success and stored customer name matches BBL receiver name 1100 (VerifyStatus)
Validation success but stored customer name does not match BBL receiver name 2000 (WaitingApprovalStatus)
Confirm success 5000 (CompleteStatus)

API Payment Implementation Notes

Topic Detail
Route prefix The actual route prefix is /api/v1/bank/apipayment; it does not include /bbl
Error handling Handler returns HTTP 400 with {"error":"..."} on bind, validation, or usecase failures
Name matching Validation compares BBL receiverName with locally stored EN_NAME + EN_SURNAME; mismatch does not fail validation, but changes local status to waiting approval
Inquiry input model Inquiry reconstructs the outbound BBL payload from DB state; the caller only supplies local transactionID

ThaiQR

Module Summary

Item Value
Base path /api/v1/bank/bbl/thaiqr
Purpose Generate ThaiQR payloads, receive BBL callbacks, query payment status, and refund completed ThaiQR transactions
Inbound content type application/json
Local transaction type ThaiQR
OAuth model Local GET /access-token fetches BBL token; caller then passes that token payload back into POST /inquiry/:transactionID and POST /refund/:transactionID
Callback auth JWT signature in Signature header
Outbound auth to BBL Bearer token + RSA/JWT signature
Primary local lifecycle 1000 pending -> 1100 verified -> 5000 complete

Endpoint Matrix

Method Path Purpose Local side effects
GET /access-token Fetch BBL OAuth access token None
POST /generate-qr Create local pending ThaiQR transaction and generate QR string Inserts thaiqr + transactions; status becomes 1000
POST /verify Receive BBL verification callback Updates ThaiQR transaction date/time; status becomes 1100
POST /noti Receive final BBL payment notification callback Updates ThaiQR payment metadata; status becomes 5000
POST /inquiry/:transactionID Query BBL for ThaiQR payment result using local transaction ID None locally besides read-side lookup
POST /refund/:transactionID Refund a completed ThaiQR transaction Inserts refund transaction and updates refund status fields

GET /access-token Contract

Item Value
Request body None
Local method GET
Upstream method POST with application/x-www-form-urlencoded
Upstream grant type client_credentials
Upstream extra form field expireIn=86399

GET /access-token Success Response

Field Type Description
accessToken string OAuth bearer token for ThaiQR inquiry/refund
expiresIn string Token TTL from BBL
scope string Granted scope

POST /generate-qr Request Contract

Field Type Required Constraints Notes
transactionAmount float64 Yes <= 9999999999999.99 Amount encoded into QR and stored in DB
customerId string Yes Must parse to integer Used as local transaction customer ID

POST /generate-qr Success Response

Field Type Description
status string Common response wrapper status, expected success
data.qr.qrCode string Generated EMV ThaiQR payload
data.qr.billerId string Biller ID + suffix used in the QR
data.qr.reference1 string Generated reference 1
data.qr.reference2 string Generated reference 2

ThaiQR Callback Contract

Method Path Required headers Request body Success response Local side effects
POST /verify Signature, Request-Ref billerId, amount, transDate, transTime, reference1, reference2, reference3 responseCode="000", responseMesg="Success" plus response headers Request-Ref, Signature, Transmit-Date-Time Verifies JWT signature, updates ThaiQR date/time, sets status 1100
POST /noti Signature, Request-Ref type, and data.{billerId, amount, transDate, transTime, termType, fromBank, fromName, retryFlag, approvalCode, bankRef, reference1, reference2, reference3} responseCode="000", responseMesg="Success" plus response headers Request-Ref, Signature, Transmit-Date-Time Verifies JWT signature, updates bank/payment metadata, sets status 5000

POST /inquiry/:transactionID Request Contract

Item Type Required Notes
transactionID path param Yes Local transactions.id
accessToken string Yes Passed in request body using AccessTokenResponse shape
expiresIn string No Bound but not required by business logic
scope string No Bound but not required by business logic

POST /inquiry/:transactionID Success Response

Field Type Description
responseCode string BBL/business result code
responseMesg string Human-readable message
data.billerId string Biller ID
data.transDate string Payment date
data.transTime string Payment time
data.termType string Terminal type
data.amount string Paid amount
data.reference1 string ThaiQR reference 1
data.reference2 string ThaiQR reference 2
data.reference3 string ThaiQR reference 3
data.fromBank string Payer bank code
data.fromName string Payer display name
data.approvalCode string Approval code

POST /refund/:transactionID Request Contract

Item Type Required Notes
transactionID path param Yes Local transactions.id
accessToken string Yes Passed in request body using AccessTokenResponse shape
expiresIn string No Bound but not required by business logic
scope string No Bound but not required by business logic

POST /refund/:transactionID Success Response

Field Type Description
responseCode string Expected 000 on success
responseMesg string Expected Success on success

ThaiQR Refund Preconditions and Lifecycle

Step Rule / Result
Precondition Target local transaction must already be 5000 (CompleteStatus)
Precondition Target local transaction must have refunded=false
Refund verification success Creates refund transaction with status 3100 (VerifyRefundstatus)
Refund verification failure Creates refund transaction with status 3150 (VerifyRefundFailStatus)
Refund advice success Updates refund status to 3200 (AdviceRefundStatus) and marks original transaction refunded=true
Refund advice failure Updates refund status to 3250 (AdviceRefundFailStatus)
Refund reversal success Updates refund status to 3300 (ReversalRefundStaus)
Refund reversal failure Updates refund status to 3350 (ReversalRefundFailStaus)

ThaiQR Implementation Notes

Topic Detail
Route semantics The actual callback endpoints registered in the router are /verify and /noti
Error handling: access token Normal failures return HTTP 400 with {"message":"..."}; connection-reset case is mapped to response code 999
Error handling: generate QR Validation failures return common response with failure status; usecase failures return common error response
Error handling: verify/noti/refund Business-level failures still return HTTP 200, with non-000 responseCode in the response body
Token handoff /inquiry/:transactionID and /refund/:transactionID expect the caller to POST the previously obtained token payload in the request body rather than using an inbound Authorization header
TLS behavior Current ThaiQR outbound HTTP calls use clients with TLS verification disabled (InsecureSkipVerify=true)

Common Identifier Semantics

Field Meaning
transactionID Local transactions.id created by this service
requestRef BBL request reference generated by this service and sent in Request-Ref
origRequestRef Existing requestRef from a prior API Payment validation/confirm step
lookupRef BBL lookup reference returned by API Payment validation
bankRefNo BBL transfer reference returned in API Payment flows
bankRef BBL bank reference used in ThaiQR notification data
reference1, reference2, reference3 ThaiQR merchant/payment references stored in the thaiqr record

Common BBL Response Codes Seen in These Flows

Code Meaning
000 Success
052 Unknown Biller ID
054 System unavailable
209 Transaction not found
210 Time out
211 Invalid data
215 Invalid token
341 Service not ready
888 Other error
999 Connection reset by peer

Updated by Ryan Supawarapong 18 days ago · 1 revisions