Finansia Portal

# BBL Integration

Detail for API on BBL integration.

- [API Payment](#API-Payment)

- [ThaiQR](#ThaiQR)

## 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 |