QR Payment

Enables you to receive secure, convenient QR Code payments from any bank’s mobile banking system

API Security

Bangkok Bank leverages several security and authentication protocols for the safeguard of all parties involved. This section describes the OAuth (open-standard Authorization) protocol and JWT (JSON Web Token) standards that we require you to adhere to harness this API.

Prerequisites:

Merchants must be registered with Bangkok Bank developer portal to obtain the Consumer ID and Consumer secret keys for application integration purposes.
Always use HTTPS (TLS 1.2) to ensure the security of data in transit.
Keep your consumer secret and access tokens always secure.
Access tokens should be handled and stored securely, and never exposed to unauthorized parties.

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.

Generate Access Token (OAuth Client Credential)

Bangkok Bank’s Authorization follows OAuth v2.0 client credentials grant type to secure authentication between servers. The following flow diagram illustrates the client’s credentials flow with Bangkok Bank API Gateway serving as the authorization server.

A request is made to Bangkok Bank API Gateway (the API proxy), and Bangkok Bank API Gateway is responsible for validating the access token before passing the API call along to the target backend systems.

Here is the summary of the steps required to implement the client credentials code grant type.

Client requests an access token
To receive an access token, the client POSTs an API call to Bangkok Bank API Gateway with the values for consumer ID and consumer secret obtained from a registered developer app.
Bangkok Bank API Gateway validates the credential
The API calls are sent to the OAuth service. This endpoint has a policy attached to it that validates the app's credentials from the client. This policy validates whether a client application is authorized or not.
Bangkok Bank API Gateway validates the credential
If the credentials are valid, Gateway then returns an access token to the client valid for 24 hours. If not, an error is returned.

With a valid access token, the client can make calls to the protected API.

POST /oauth/accesstoken

Web Services: RESTful JSON

HTTP Method: POST

Character encoding: UTF-8

Content Type: application/x-www-form-urlencoded

Request URL

Sandbox:
https://api-sandbox.bangkokbank.com/oauth/accesstoken
PROD:
https://api.bangkokbank.com/oauth/accesstoken

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Basic authentication Token encode with Base64 String = {consumerKey}:{consumerSecret} Basic {token}	`Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ`

Request Body

Parameter	Type	Size	Mandatory	Description	Example/Values
grant_type	String	20	Y	OAuth grant type	`client_credentials`
scope	String	50	N	Scope of access proxy	`READ CREATE`

Request Example

curl --request POST 'https://{{api-host}}/oAuth/accesstoken' \
--header 'Authorization: Basic QkF6V29tNGxLa3VVTjdNVVYxTFlPR2hyMllkS0ZoUVc6R01idmJScVRYN3NrT1FWVQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=CREATE READ' \
--data-urlencode '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	Y	Scope token	`READ CREATE`

Response Body Example (Success)

{
    "accessToken": "ds9PIkzbNwXffsDHLPW4auli0NAN",
    "expiresIn": "86399",
    "scope": "READ CREATE"
}

Response Body Example (Failure)

{
    "responseCode": "1001",
    "responseMesg": "grant_type not found"
}

API Overview & Specification

Thai QR Code Generation

This API, as part of the broad product suite, specifically enables you to offer Thai QR payment capabilities to your customers through your application solution. The QR code is generated on request at checkout and has your business details and the purchase value embedded. This allows the customer to scan and make payment to you with confidence knowing they are transferring money to the correct business and of the correct value.

Thai QR Verify Online

When a customer scans the QR code from mobile banking, Bangkok Bank Gateway sends an API request to merchant specified endpoint with QR information to verify the eligibility of QR code before allowing the buyers to make the payment.

Thai QR Notification

When a customer confirms payment of a QR payment transaction, Bangkok Bank Gateway sends an API request with payment details to merchant's provided notification URL endpoint

Pull Payment Transaction

This API, as part of the broad product suite, specifically enables you to offer Thai QR payment capabilities to your customers through your application solution.

This is an optional flow subsequent to the core payment process described in the previous section. Pull Payment Transaction API allows verification and information retrieval by using the Transaction Reference embedded in the payment slip (mini-QR) generated from the transaction completed through mobile banking application.

Thai QR Inquiry - for QR code generated by merchant

If notification is not received, then Partner will inquire transaction result via "Thai QR Inquiry API".

Thai QR Payment Inquiry - for QR code generated through Thai QR Code Generation API

This API, as part of the broad product suite, specifically enables you to offer Thai QR payment capabilities to your customers through your application solution. The Payment Inquiry is used to inquire about the payment transaction status by using the qrCodeId that the merchant system receives on the request QR step.

This is an optional flow after the core payment process described in the previous section. In case merchant system does not receive notification; merchant system can use this API to check the payment status.

Thai QR Refund

This API, as part of the broad product suite, specifically enables you to offer Thai QR refund capabilities to your customers through your application solution. This is an optional flow after the core payment process described in the previous section. Upon successful QR payment transaction through Bangkok Bank, your customers can make refunds request for the purchased goods or services.

The Refund API consists of three main functions:

Refund Verification
This function verifies whether a specific payment transaction has been successfully completed and is eligible for a refund. If verification is successful, the system will mark the transaction as it refundable.
Refund Advice
After successful Refund Verification, this function is used to initiate the refund process.
Refund Reversal
This function allows for cancelling a refund incase refund verification timeout. However, a refund reversal cannot be performed once the Refund Advice has been completed.

Scenario Example

(A: Refund Verification + B: Refund Advice)
Merchant must use these API endpoints to initiate a success Refund for Thai QR payment.
- Customer is looking to return goods or services and initiate a request for refund.
- Cashier enters transaction details and request refund via Merchant Application (For example, POS).
- Merchant systems then request refund verification to initiate flow by using the Refund Verification API (must be before 11pm same day of the payment)
  If timeout, merchant system must cancel by requesting refund reversal and retry refund verification again.
- Merchant systems verify transaction status whether refunds are possible or not.
- Merchant systems requests refund advice to confirm refund (before 11pm same day)
  If timeout, merchant systems can retry refund advice
- Merchant systems then receive response for the refund and payment status.
- Customers receives refund payment successfully.
(A: Refund Verification timeout + C: Refund Reversal)
Merchant must use these API endpoints to cancel a refund request if timeout occurs, to request a new refund transaction, please resend the API request via scenario #1.
- Merchant systems request refund verification API to initiate the refund (must be before 11pm same day of the payment).
- Time out occurs for refund verification API.
- If timeout occurs, merchant system must cancel the refund request via refund reversal API.
- Merchant systems then receive response for the refund reversal API.

To perform successful refund, merchant system must then retry or execute API sequence as shown on the scenario #1 above again.

POST /biller/v1/qr-generate

Web Services: RESTful JSON

HTTP Method: POST

Character encoding: UTF-8

Content Type: application/json

Authorization: Bearer authentication (OAuth token Client Credential grant type)

Sequence Flow

After the customer check outs and selects to Pay with QR Code, Merchant system authenticates with Bangkok Bank API Gateway by getting access token from OAuth Endpoint.
Merchant system submits transaction details with access token and secured JWT claims via QR Code Generation API endpoint to Bangkok Bank API Gateway.
Bangkok Bank API Gateway then response qr code data with details to Merchant system.
Merchant system display QR code image to the customer, customer then scans presented QR image and complete payment transaction.

Request URL

Sandbox:
https://api-sandbox.bangkokbank.com/biller/v1/qr-generate
PROD:
https://api.bangkokbank.com/biller/v1/qr-generate

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Bearer {accessToken}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Format yyyy-MM-dd’T’HH:mm:ss.SSS+\|-hh:mm	`2017-03-15T15:23:11.855+07:00`

Request Body

Parameter	Type	Size	Mandatory	Description	Example/Values
requestDate	String	10	Y	Transaction date Format yyyy-MM-dd	`2019-12-31`
requestTime	String	8	Y	Transaction time Format HH:mm:ss	`17:50:50`
merchantName	String	50	Y	Merchant/Shop English Name	`ABC SHOP`
merchantCountry	String	2	Y	Country of Merchant	`TH`
amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`500.00`
cardNetworkPermList	Object[]
cardNetworkPermList[] .cardNetworkPerm	String	2	Y	Card network code for transaction’s payment channel: 01: PromptPay	`01`
qrPromptpayInfo	Object
qrPromptpayInfo .billerId	String	15	Y	TaxId and Suffix of the Payee	`010555604520701`
qrPromptpayInfo .reference1	String	20	Y	First Reference number of the transaction from Merchant Text A-Z capital letters	`002123456789001`
qrPromptpayInfo .reference2	String	20	N	Second Reference number of the transaction from Merchant Text A-Z capital letters	`70012345000000123456`
qrPromptpayInfo .reference3	String	20	N	Third Reference number of the transaction from Merchant Text A-Z capital letters	`5301234231112342`

Request Body Example

{
    "requestDate": "2018-12-31",
    "requestTime": "17:50:50",
    "merchantName": "ABC SHOP",
    "merchantCountry": "TH",
    "amount": "500.00",
    "cardNetworkPermList": [
        {
            "cardNetworkPerm": "01"
        }
    ],
    "qrPromptpayInfo": {
        "billerId": "010555604520701",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}

Request Example

curl --location --globoff 'https://{{api-host}}/biller/v1/qr-generate' \
--header 'Authorization: Bearer {{access-token}}' \
--header 'Signature: {{request-signature}}' \
--header 'Request-Ref: TXN20231120-0000023' \
--header 'Transmit-Date-Time: 2017-03-15T15:23:11.001+07:00' \
--header 'Content-Type: application/json' \
--data '{
    "requestDate": "2018-12-31",
    "requestTime": "17:50:50",
    "merchantName": "ABC SHOP",
    "merchantCountry": "TH",
    "amount": "500.00",
    "cardNetworkPermList": [
        {
            "cardNetworkPerm": "01"
        }
    ],
    "qrPromptpayInfo": {
        "billerId": "010555604520701",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	3	Y	Response Code	`000`
responseMesg	String	50	Y	Response Message	`success`
data	Object
data .qrCodeId	String	20	Y	Unique identifier of QR code, used for inquiry	`114455`
data .qrReference	String	20	Y	QR reference generated by BBL backend, for display/printing only, NOT used for inquiry	`602GBB00000000000000`
data .qrData	String	500	Y	QR code data, for generate QR image	`00020101021230610016A000000677010112011501075360003745302101112221112030414225303764540520.025802TH5908DEF SHOP6304FAA4`
data .cardNetworkPermList	Object[]
data .cardNetworkPermList[] .cardNetworkCode	String	2	Y	Card network code for transaction’s payment channel: 01: PromptPay	`01`

Response Body Example (Success)

{
    "responseMesg": "Success",
    "responseCode": "000",
    "data": {
        "qrCodeId": "114455",
        "qrReference": "602GBB00000000000000",
        "qrData": "00020101021230610016A000000677010112011501075360003745302101112221112030414225303764540520.025802TH5908DEF SHOP6304FAA4",
        "cardNetworkList": [
            {
                "cardNetworkCode": "01"
            }
        ]
    }
}

Response Body Example (Failure)

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

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
400	211	Invalid format Signature	Header in response does not have signature.
400	211	Invalid data	Invalid JSON Invalid request input Invalid fields validation
401			Invalid access token Invalid signature No response body
403	052	Unknown Biller ID	Biller id or service code is not registered.
405			Method not allowed No response body
429			User has sent too many requests in a given amount of time. No response body
200	054	Internal System Unavailable	Response of business backend
200	210	Time out	Response of business backend
200	211	Invalid data	Response of business backend
200	341	Service Provider not ready	Response of business backend
200	888	Other Errors	Response of business backend

POST {MERCHANT_VERIFY_URL}

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

PROD:
{MERCHANT_VERIFY_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}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT RSA256	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Request transmit date and time 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
billerId	String	15	Y	TaxId and Suffix of the Payee	`123456789012345`
amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`1500.75`
transDate	String	10	Y	Transaction date Format yyyy-MM-dd	`2018-12-31`
transTime	String	8	Y	Transaction time Format HH:mm:ss	`15:21:35`
reference1	String	30	Y	First Reference number of the transaction from Partner	`123456789`
reference2	String	30	N	Second Reference number of the transaction from Partner	`1124579998`
reference3	String	30	N	Second Reference number of the transaction from Partner	`22555347`

Request Body Example

{
    "billerId": "123456789012345",
    "amount": "1500.75",
    "transDate": "2018-03-15",
    "transTime": "15:21:50",
    "reference1": "123456789",
    "reference2": "1124579998",
    "reference3": "22555347"
}

Response Body

Parameter	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. Invalid special character set: ' (single quote) = (equals) " (double quote) < (less than) > (greater than)	`ITTest`

Response Body Example (Success)

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

Response Body Example (Failure)

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

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
200	052	Unknown Biller ID	Invalid Biller ID
200	054	System Unavailable	Response of business backend
200	209	Transaction not found	Transaction not found
200	210	Time out	Response of business backend
200	211	Invalid data	No Signature in Response Header Response of business backend Invalid Regular Expression Invalid Basic Authentication Token
200	215	Invalid token	Invalid JWT Token
200	341	Service Provider not ready	Response of business backend
200	888	Other Errors	Response of business backend
401		Unauthorized	Authorization failure

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}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT RSA256	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Request transmit date and time 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	15	Y
data .billerId	String	15	Y	TaxId and Suffix of the Payee	`123456789012345`
data .fromBank	String	3	Y	From bank code. Right-aligned and left-padded with zeros.	`002`
data .amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`1500.75`
data .approvalCode	String	6	N		`123456`
data .retryFlag	String	1	Y	Notification retry flag: Y: for retry/resend message D: for original message	`N`
data .transDate	String	10	Y	Transaction date Format yyyy-MM-dd	`2018-12-31`
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 .fromName	String	50	N	Payer name Eng/Thai (UTF-8)	`ITTest`
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	`1124579998`
data .reference3	String	30	N	Second Reference number of the transaction from Partner	`22555347`
data .bankRef	String	25	N	BBL reference	`2022101914273423001321408`
type	String			Application type Fixed Value: ThaiQR	`ThaiQR`

Request Body Example

{
    "data": {
        "billerId": "123456789012345",
        "fromBank": "002",
        "amount": "1500.75",
        "approvalCode": "123456",
        "retryFlag": "N",
        "transDate": "2017-11-06",
        "transTime": "17:57:50",
        "termType": "10",
        "fromName": "ITTest",
        "reference1": "123456789",
        "reference2": "20171106151550",
        "reference3": "5555555",
        "bankRef": "2022101914273423001321408"
    },
    "type": "ThaiQR"
}

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": "Service Provider not ready",
    "responseCode": "341"
}

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
200	052	Unknown Biller ID	Invalid Biller ID
200	054	System Unavailable	Response of business backend
200	209	Transaction not found	Transaction not found
200	210	Time out	Response of business backend
200	211	Invalid data	No Signature in Response Header Response of business backend Invalid Regular Expression Invalid Basic Authentication Token
200	215	Invalid token	Invalid JWT Token
200	341	Service Provider not ready	Response of business backend
200	888	Other Errors	Response of business backend
401		Unauthorized	Authorization failure

POST /biller/v1/pull-payment

Web Services: RESTful JSON

HTTP Method: POST

Character encoding: UTF-8

Content Type: application/json

Authorization: Bearer authentication (OAuth token Client Credential grant type)

Sequence Flow

After the Customer have completed a transaction, Merchant system is able to check the transaction status and its details by using the Pull Payment Transaction API function.
Merchant system authenticates with Bangkok Bank API Gateway by getting access token from OAuth Endpoint.
The Merchant system submits transaction details with access token and secured JWT claims via Pull Payment Transaction API endpoint to Bangkok Bank API Gateway.
The Bangkok Bank API Gateway then responds with transaction details to Merchant system.

Request URL

Sandbox:
https://api-sandbox.bangkokbank.com/biller/v1/pull-payment
PROD:
https://api.bangkokbank.com/biller/v1/pull-payment

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Bearer {accessToken}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Format yyyy-MM-dd’T’HH:mm:ss.SSS+\|-hh:mm	`2017-03-15T15:23:11.855+07:00`

Request Body

Parameter	Type	Size	Mandatory	Description	Example/Values
billerId	String	15	Y	TaxId and Suffix of the Payee	`010555604520701`
transRef	String	25	Y	Unique transaction reference number retrieved from payment slip for verifying payment transaction.	`2022011211544723000693608`
destBank	String	3	Y	Payer Bank Code retrieved from payment slip	`002`
reference1	String	20	Y	First Reference number of the transaction from Merchant Text A-Z capital letters	`002123456789001`
reference2	String	20	N	Second Reference number of the transaction from Merchant Text A-Z capital letters	`70012345000000123456`
reference3	String	20	N	Third Reference number of the transaction from Merchant Text A-Z capital letters	`5301234231112342`
amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`150.00`

Request Body Example

{
    "billerId": "013456789012301",
    "transRef": "2022011211544723000693608",
    "destBank": "002",
    "reference1": "002123456789001",
    "reference2": "70012345000000123456",
    "reference3": "5301234231112342",
    "amount": "150.00"
}

Request Example

curl --location --globoff 'https://{{api-host}}/biller/v1/pull-payment' \
--header 'Authorization: Bearer {{access-token}}' \
--header 'Signature: {{request-signature}}' \
--header 'Request-Ref: TXN20231120-0000023' \
--header 'Transmit-Date-Time: 2017-03-15T15:23:11.001+07:00' \
--header 'Content-Type: application/json' \
--data '{
    "billerId": "013456789012301",
    "transRef": "2022011211544723000693608",
    "destBank": "002",
    "reference1": "002123456789001",
    "reference2": "70012345000000123456",
    "reference3": "5301234231112342",
    "amount": "150.00"
}'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	3	Y	Response Code	`000`
responseMesg	String	50	Y	Response Message	`success`
data	Object
data .transRef	String	25	Y	Unique transaction reference number retrieved from payment slip for verifying payment transaction. Value must be exactly the same as the value in HTTP Request Body above.	`2022011211544723000693608`
data .sendingBank	String	3	Y	Payer Bank code retrieved from payment slip	`002`
data .receivingBank	String	3	Y	Merchant Bank code	`004`
data .transDate	String	10	N	Transaction date Format yyyy-MM-dd	`2023-09-20`
data .transTime	String	8	N	Transaction time Format HH:mm:ss	`11:54:43`
data .amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99 Value must be exactly the same as the value in HTTP Request Body above.	`150.00`
data .countryCode	String	2	N		`TH`
data .reference1	String	20	Y	First Reference number of the transaction from Merchant Text A-Z capital letters	`002123456789001`
data .reference2	String	20	N	Second Reference number of the transaction from Merchant Text A-Z capital letters	`70012345000000123456`
data .reference3	String	20	N	Third Reference number of the transaction from Merchant Text A-Z capital letters	`5301234231112342`
data .sender	Object
data .sender .displayName	String	50	N	Name of Sender	`สมชาย นามสมมติ`
data .sender .name	String	50	N	Name of Sender	`Somchai Namsommuth`
data .sender .type	String	12	N	In case paid by e-Wallet only	`EWALLETID`
data .sender .value	String	128	N	In case paid by e-Wallet only	`002556006918201`
data .sender .account	Object
data .sender .account .type	String	12	Y	In case paid by account only	`BANKAC`
data .sender .account .value	String	40	Y	In case paid by account only	`2750001253`
data .sender .receiver	Object
data .sender .receiver .displayName	String	50	N	Name of Receiver	`SUNDAY INS - QRUATOFFLINE`
data .sender .proxy	Object
data .sender .proxy .type	String	12	Y	Account type of receiver	`BILLERID`
data .sender .proxy .value	String	40	Y	Account value of receiver	`013456789012301`

Response Body Example (Success)

{
    "responseCode": "000",
    "responseMesg": "Success",
    "data": {
        "transRef": "2022011211544723000693608",
        "sendingBank": "002",
        "receivingBank": "004",
        "transDate": "2023-09-20",
        "transTime": "11:54:43",
        "amount": "150.00",
        "countryCode": "TH",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342",
        "sender": {
            "displayName": "สมชาย นามสมมติ",
            "name": "Somchai Namsommuth",
            "account": {
                "type": "BANKAC",
                "value": "2750001253"
            }
        },
        "receiver": {
            "displayName": "SUNDAY INS - QRUATOFFLINE",
            "proxy": {
                "type": "BILLERID",
                "value": "013456789012301"
            }
        }
    }
}

Response Body Example (Failure)

{
    "responseCode": "209",
    "responseMesg": "Transaction reference does not exists"   
}

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
400	211	Invalid format Signature	Header in response does not have signature.
400	211	Invalid data	Invalid JSON Invalid request input Invalid fields validation
401			Invalid access token Invalid signature No response body
403	052	Unknown Biller ID	Biller id or service code is not registered.
405			Method not allowed No response body
429			User has sent too many requests in a given amount of time. No response body
200	001	Invalid parameter input	Response of business backend Destination bank does not support or invalid destination bank.
200	209	Transaction reference does not exist	Response of business backend System cannot find the specified transaction reference.
200	213	Transaction reference does not exist	Response of business backend When the payment has already been refunded, it is no longer possible to inquire about the payment information.
200	211	Invalid data	The biller id, ref1, ref2, ref3 & amount differs from the request.
200	888	Other Errors	Response of business backend In case of any unexpected errors, the system will return this code.

POST /biller/v1/qr-inquiry

Web Services: RESTful JSON

HTTP Method: POST

Character encoding: UTF-8

Content Type: application/json

Authorization: Bearer authentication (OAuth token Client Credential grant type)

Note:

Used to inquire transaction made by QR code generated by merchant.

Request URL

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

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Bearer {accessToken}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT RSA256	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Request transmit date and time 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
billerId	String	15	Y	TaxId and Suffix of the Payee	`123456789012345`
amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`1500.75`
transDate	String	10	Y	Transaction date Format yyyy-MM-dd	`2018-12-31`
reference1	String	30	Y	First Reference number of the transaction from Partner	`123456789`
reference2	String	30	N	Second Reference number of the transaction from Partner	`1124579998`
reference3	String	30	N	Second Reference number of the transaction from Partner	`22555347`

Request Body Example

{
    "billerId": "123456789012345",
    "amount": "1500.25",
    "transDate": "2018-03-15",
    "reference1": "123456789",
    "reference2": "1124579998",
    "reference3": "1124579998"
}

Request Example

curl --request POST 'https://{{api-host}}/biller/v1/qr-inquiry' \
--header 'Authorization: Bearer {{access-token}}' \
--header 'Signature: {{request-signature}}' \
--header 'Transmit-Date-Time: 2017-03-15T15:23:11.001+07:00' \
--header 'Request-Ref: TXN20171120-0000023' \
--header 'Content-Type: application/json' \
--data-raw '{
    "billerId": "123456789012345",
    "amount": "1500.25",
    "transDate": "2018-03-15",
    "reference1": "123456789",
    "reference2": "1124579998",
    "reference3": "1124579998"
}'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	3	Y	Response Code	`000`
responseMesg	String	50	Y	Response Message	`success`
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 Maximum number is 9999999999999.99	`1500.75`
data .reference1	String	30	Y	First Reference number of the transaction from Partner	`120213405`
data .reference2	String	30	N	Second Reference number of the transaction from Partner	`120213405`
data .reference3	String	30	N	Second Reference number of the transaction from Partner	`120213405`
data .fromBank	String	3	Y	From bank code. Right-aligned and left-padded with zeros.	`002`
data .fromName	String	50	N	Payer name Eng/Thai (UTF-8)	`ITTest`
data .bankRef	String	25	N	BBL reference
data .approvalCode	String	6	N		`123456`

Response Body Example (Success)

{
    "responseCode": "000",
    "responseMesg": "Success",
    "data": {
        "billerId": "123456789012345",
        "transDate": "2017-11-16",
        "transTime": "17:57:50",
        "termType": "10",
        "amount": "1500.75",
        "reference1": "120213405",
        "reference2": "120213405",
        "reference3": "120213405",
        "fromBank": "001",
        "fromName": "ITTest",
        "approvalCode": "123456"
    }
}

Response Body Example (Failure)

{
    "responseMesg": "Service Provider not ready",
    "responseCode": "341"
}

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
200	054	System Unavailable	Response of business backend
200	209	Transaction not found	Transaction not found
200	210	Time out	Response of business backend
200	211	Invalid data	Invalid JSON Response of business backend No Signature in Response Header
200	215	Invalid token	Invalid JWT Token
200	341	Service not ready	Response of business backend
200	888	Other Errors	Response of business backend
401		Unauthorized	Authorization failure
403	052	Unknown Biller ID	Biller ID or Service Code is not registered

POST /biller/v1/payment-inquiry

Web Services: RESTful JSON

HTTP Method: POST

Character encoding: UTF-8

Content Type: application/json

Authorization: Bearer authentication (OAuth token Client Credential grant type)

Note:

Used to inquire transaction made by QR code generated through Thai QR Code Generation API.

Sequence Flow

In case that Merchant system does not receive any payment notification for completed transactions, merchant systems can check the transaction status by using the Thai QR Payment Inquiry API function.
Merchant system authenticates with Bangkok Bank API Gateway by getting access token from OAuth Endpoint.
The Merchant system then submits transaction details along with the access token and secure JWT claims to the Bangkok Bank API Gateway via the Thai QR Payment Inquiry API endpoint.
Bangkok Bank API Gateway then responds with the transaction status, the payment status.

Request URL

Sandbox:
https://api-sandbox.bangkokbank.com/biller/v1/payment-inquiry
PROD:
https://api.bangkokbank.com/biller/v1/payment-inquiry

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Access token of OAuth token Client Credential type Bearer {accessToken}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT RSA256	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Request transmit date and time 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
inquiryDate	String	10	Y	Inquiry date Format yyyy-MM-dd	`2018-12-31`
inquiryTime	String	8	Y	Inquiry time Format HH:mm:ss	`17:57:50`
amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`500.00`
qrCodeId	String	20	Y	Unique identifier of QR code, used for inquiry	`10000000000000000000`
qrPromptpayInfo	Object
qrPromptpayInfo .billerId	String	15	Y	TaxId and Suffix of the Payee	`010555604520701`
qrPromptpayInfo .reference1	String	20	Y	First Reference number of the transaction from Merchant Text A-Z capital letters	`002123456789001`
qrPromptpayInfo .reference2	String	20	N	Second Reference number of the transaction from Merchant Text A-Z capital letters	`70012345000000123456`
qrPromptpayInfo .reference3	String	20	N	Third Reference number of the transaction from Merchant Text A-Z capital letters	`5301234231112342`

Request Body Example

{
    "inquiryDate": "2018-12-31",
    "inquiryTime": "17:57:50",
    "amount": "500.00",
    "qrCodeId": "10000000000000000000",
    "qrPromptpayInfo": {
        "billerId": "010555604520701",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}

Request Example

curl --location --globoff 'https://{{api-host}}/biller/v1/payment-inquiry' \
--header 'Authorization: Bearer {{access-token}}' \
--header 'Signature: {{request-signature}}' \
--header 'Request-Ref: TXN20231120-0000023' \
--header 'Transmit-Date-Time: 2017-03-15T15:23:11.001+07:00' \
--header 'Content-Type: application/json' \
--data '{
    "inquiryDate": "2018-12-31",
    "inquiryTime": "17:57:50",
    "amount": "500.00",
    "qrCodeId": "10000000000000000000",
    "qrPromptpayInfo": {
        "billerId": "010555604520701",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	3	Y	Response Code	`000`
responseMesg	String	50	Y	Response Message	`success`
data	Object
data .statusCode	String	2	Y	Status Code of payment: 00: Approved UK: Unknown (Please retry inquiry) 01: Voided 02: Voidable Other: Failed	`00`
data .statusMesg	String	100	Y	Status Message of payment: 00: Approved UK: Unknown (Please retry inquiry) 01: Voided 02: Voidable Other: Failed	`Approved`
data .cardNetworkCode	String	2	N	Return if Status Code is 00 Card network code for transaction's payment channel: 01: PromptPay	`01`
data .transDate	String	10	N	Return if Status Code is 00 Transaction date Format yyyy-MM-dd	`2018-12-31`
data .transTime	String	8	N	Return if Status Code is 00 Transaction time Format HH:mm:ss	`17:57:50`
data .approvalCode	String	6	N	Return if Status Code is 00 BBL reference	`650258`
data .transactionId	String	12	N	Return if Status Code is 00 Payment Transaction ID	`100000000001`
data .qrPromptpayInfo	Object
data .qrPromptpayInfo .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 .qrPromptpayInfo .fromBank	String	3	Y	From bank code	`SCB`
data .qrPromptpayInfo .fromName	String	50	N	Payer name Eng/Thai (UTF-8)	`Joe`
data .qrPromptpayInfo .bankRef	String	50	N	BBL reference	`242848204`

Response Body Example (Success)

{
    "responseCode": "000",
    "responseMesg": "Success",
    "data": {
        "statusCode": "00",
        "statusMesg": "Approved",
        "cardNetworkCode": "01",
        "transDate": "2018-12-31",
        "transTime": "17:51:35",
        "approvalCode": "650258",
        "transactionId": "100000000001",
        "qrPromptpayInfo": {
            "termType": "80",
            "fromBank": "SCB",
            "fromName": "Joe",
            "bankRef": "242848204"
        }
    }
}

Response Body Example (Failure)

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

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
400	211	Invalid format Signature	Header in response does not have signature.
400	211	Invalid data	Invalid JSON Invalid request input Invalid fields validation
401			Invalid access token Invalid signature No response body
403	052	Unknown Biller ID	Biller id or service code is not registered.
405			Method not allowed No response body
429			User has sent too many requests in a given amount of time. No response body
200	054	Internal System Unavailable	Response of business backend
200	209	Transaction not found	Response of business backend
200	210	Time out	Response of business backend
200	211	Invalid data	Response of business backend
200	341	Service Provider not ready	Response of business backend
200	888	Other Errors	Response of business backend

POST /biller/v1/refund/verification

Web Services: RESTful JSON

HTTP Method: POST

Character encoding: UTF-8

Content Type: application/json

Authorization: Bearer authentication (OAuth token Client Credential grant type)

Sequence Flow

In case that customer request to cancel the completed payment transaction, merchant system can request to cancel the payment transaction by using the refund verification function.
Merchant system authenticates with Bangkok Bank API Gateway by getting access token from OAuth Endpoint.
Merchant system submits transaction details with access token and secured JWT claims via Thai QR Refund Verification API endpoint to Bangkok Bank API Gateway.
Bangkok Bank API Gateway then response whether the cancellation can be made or not.

Request URL

Sandbox:
https://api-sandbox.bangkokbank.com/biller/v1/refund/verification
PROD:
https://api.bangkokbank.com/biller/v1/refund/verification

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Access token of OAuth token Client Credential type Bearer {accessToken}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT RSA256	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Request transmit date and time 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
transDate	String	10	Y	Transaction date Format yyyy-MM-dd	`2018-12-31`
transTime	String	8	Y	Transaction time Format HH:mm:ss	`15:21:35`
amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`500.00`
approvalCode	String	6	Y	Approval Code	`650258`
cardNetworkCode	String	2	Y	Card network code for transaction's payment channel: 01: PromptPay	`01`
qrPromptpayInfo	Object
qrPromptpayInfo .billerId	String	15	Y	TaxId and Suffix of the Payee	`010555604520701`
qrPromptpayInfo .reference1	String	20	Y	First Reference number of the transaction from Merchant Text A-Z capital letters	`002123456789001`
qrPromptpayInfo .reference2	String	20	N	Second Reference number of the transaction from Merchant Text A-Z capital letters	`70012345000000123456`
qrPromptpayInfo .reference3	String	20	N	Third Reference number of the transaction from Merchant Text A-Z capital letters	`5301234231112342`

Request Body Example

{
    "transDate": "2018-12-31",
    "transTime": "15:21:35",
    "amount": "500.00",
    "approvalCode": "650258",
    "cardNetworkCode": "01",
    "qrPromptpayInfo": { 
        "billerId": "010555604520711",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}

Request Example

curl --location --globoff 'https://{{api-host}}/biller/v1/refund/verification' \
--header 'Authorization: Bearer {{access-token}}' \
--header 'Signature: {{request-signature}}' \
--header 'Request-Ref: TXN20231120-0000023' \
--header 'Transmit-Date-Time: 2017-03-15T15:23:11.001+07:00' \
--header 'Content-Type: application/json' \
--data '{
    "transDate": "2018-12-31",
    "transTime": "15:21:35",
    "amount": "500.00",
    "approvalCode": "650258",
    "cardNetworkCode": "01",
    "qrPromptpayInfo": {
        "billerId": "010555604520711",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	3	Y	Response Code	`000`
responseMesg	String	50	Y	Response Message	`success`
data	Object
data .transactionId	String	12	Y	Payment Transaction ID	`65478923`
data .fromName	String	50	N	Buyer Name	`ABC XYZ`

Response Body Example (Success)

{
    "responseCode": "000",
    "responseMesg": "Success",
    "data": {
        "transactionId": "65478923",
        "fromName": "ABC XYZ"
    }
}

Response Body Example (Failure)

{
    "responseMesg": "Transaction already void",
    "responseCode": "213"
}

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
400	211	Invalid format Signature	Header in response does not have signature.
400	211	Invalid data	Invalid JSON Invalid request input Invalid fields validation
401			Invalid access token Invalid signature No response body
403	052	Unknown Biller ID	Biller id or service code is not registered.
405			Method not allowed No response body
429			User has sent too many requests in a given amount of time. No response body
200	054	Internal System Unavailable	Response of business backend
200	209	Transaction not found	Response of business backend
200	210	Time out	Response of business backend
200	211	Invalid data	Response of business backend
200	213	Transaction already void	Response of business backend
200	214	Trans too old to void advice	Response of business backend Voiding is not possible anymore
200	215	Trans too old to pre-void	Response of business backend Transaction can't be pre voided if the processing date differs from the payment date. Pre voiding is only possible for transactions processed on the same day as the payment.
200	216	Voiding not allowed on this Transaction	Response of business backend
200	217	This transaction cannot be voided	Response of business backend
200	218	Voiding decline by host	Response of business backend
200	341	Service Provider not ready	Response of business backend
200	888	Other Errors	Response of business backend

POST /biller/v1/refund/advice

Web Services: RESTful JSON

HTTP Method: POST

Character encoding: UTF-8

Content Type: application/json

Authorization: Bearer authentication (OAuth token Client Credential grant type)

Sequence Flow

After successful verification, to confirm cancel completed payment transaction, merchant system can proceed this action by using the refund advice function.
Merchant system authenticates with Bangkok Bank API Gateway by getting access token from OAuth Endpoint.
Merchant system submits transaction details with access token and secured JWT claims via Thai QR Refund Advice API endpoint to Bangkok Bank API Gateway.
Bangkok Bank API Gateway then response the status.

Request URL

Sandbox:
https://api-sandbox.bangkokbank.com/biller/v1/refund/advice
PROD:
https://api.bangkokbank.com/biller/v1/refund/advice

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Access token of OAuth token Client Credential type Bearer {accessToken}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT RSA256	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Request transmit date and time 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
transDate	String	10	Y	Transaction date Format yyyy-MM-dd	`2018-12-31`
transTime	String	8	Y	Transaction time Format HH:mm:ss	`15:21:35`
amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`500.00`
approvalCode	String	6	Y	Approval Code	`650258`
cardNetworkCode	String	2	Y	Card network code for transaction's payment channel: 01: PromptPay	`01`
qrPromptpayInfo	Object
qrPromptpayInfo .billerId	String	15	Y	TaxId and Suffix of the Payee	`010555604520701`
qrPromptpayInfo .reference1	String	20	Y	First Reference number of the transaction from Merchant Text A-Z capital letters	`002123456789001`
qrPromptpayInfo .reference2	String	20	N	Second Reference number of the transaction from Merchant Text A-Z capital letters	`70012345000000123456`
qrPromptpayInfo .reference3	String	20	N	Third Reference number of the transaction from Merchant Text A-Z capital letters	`5301234231112342`

Request Body Example

{
    "transDate": "2018-12-31",
    "transTime": "15:21:35",
    "amount": "500.00",
    "approvalCode": "650258",
    "cardNetworkCode": "01",
    "qrPromptpayInfo": { 
        "billerId": "010555604520711",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}

Request Example

curl --location --globoff 'https://{{api-host}}/biller/v1/refund/advice' \
--header 'Authorization: Bearer {{access-token}}' \
--header 'Signature: {{request-signature}}' \
--header 'Request-Ref: TXN20231120-0000023' \
--header 'Transmit-Date-Time: 2017-03-15T15:23:11.001+07:00' \
--header 'Content-Type: application/json' \
--data '{
    "transDate": "2018-12-31",
    "transTime": "15:21:35",
    "amount": "500.00",
    "approvalCode": "650258",
    "cardNetworkCode": "01",
    "qrPromptpayInfo": { 
        "billerId": "010555604520711",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	3	Y	Response Code	`000`
responseMesg	String	50	Y	Response Message	`success`
data	Object
data .transactionId	String	12	Y	Payment Transaction ID	`65478923`

Response Body Example (Success)

{
    "responseCode": "000",
    "responseMesg": "Success",
    "data": {
        "transactionId": "65478923"
    }
}

Response Body Example (Failure)

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

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
400	211	Invalid format Signature	Header in response does not have signature.
400	211	Invalid data	Invalid JSON Invalid request input Invalid fields validation
401			Invalid access token Invalid signature No response body
403	052	Unknown Biller ID	Biller id or service code is not registered.
405			Method not allowed No response body
429			User has sent too many requests in a given amount of time. No response body
200	054	Internal System Unavailable	Response of business backend
200	209	Transaction not found	Response of business backend
200	210	Time out	Response of business backend
200	211	Invalid data	Response of business backend
200	213	Transaction already void	Response of business backend
200	214	Trans too old to void advice	Response of business backend Voiding is not possible anymore
200	215	Trans too old to pre-void	Response of business backend Transaction can't be pre voided if the processing date differs from the payment date. Pre voiding is only possible for transactions processed on the same day as the payment.
200	216	Voiding not allowed on this Transaction	Response of business backend
200	217	This transaction cannot be voided	Response of business backend
200	218	Voiding decline by host	Response of business backend
200	341	Service Provider not ready	Response of business backend
200	888	Other Errors	Response of business backend

POST /biller/v1/refund/reversal

Web Services: RESTful JSON

HTTP Method: POST

Character encoding: UTF-8

Content Type: application/json

Authorization: Bearer authentication (OAuth token Client Credential grant type)

Sequence Flow

In case of timeout, merchant can cancel refund request by using the refund reversal function.
Merchant system authenticates with Bangkok Bank API Gateway by getting access token from OAuth Endpoint.
Merchant system submits transaction details with access token and secured JWT claims via Thai QR Refund Reversal API endpoint to Bangkok Bank API Gateway.
Bangkok Bank API Gateway then response the status.

Request URL

Sandbox:
https://api-sandbox.bangkokbank.com/biller/v1/refund/reversal
PROD:
https://api.bangkokbank.com/biller/v1/refund/reversal

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Access token of OAuth token Client Credential type Bearer {accessToken}	`Bearer 3CMwLhLwOZL3mKOI6iJoKNs3Q4NA`
Signature	String		Y	Digital Signature sign with JWT RSA256	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJqadEIuNEPkxgfD8fzh2TlfOKVXwNGVr_p9TTCGkJ672MbkSoJZqcQVi-Pm-IaVX7hE8…`
Request-Ref	String	50	Y	Transaction tracking no. (Unique)	`TXN20171120-0000023`
Transmit-Date-Time	String	29	Y	Request transmit date and time 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
transDate	String	10	Y	Transaction date Format yyyy-MM-dd	`2018-12-31`
transTime	String	8	Y	Transaction time Format HH:mm:ss	`15:21:35`
amount	String	16	Y	Payment amount = 13 digits + . + 2 decimals Ex. xxxx.xx Maximum number is 9999999999999.99	`500.00`
approvalCode	String	6	Y	Approval Code	`650258`
cardNetworkCode	String	2	Y	Card network code for transaction's payment channel: 01: PromptPay	`01`
qrPromptpayInfo	Object
qrPromptpayInfo .billerId	String	15	Y	TaxId and Suffix of the Payee	`010555604520701`
qrPromptpayInfo .reference1	String	20	Y	First Reference number of the transaction from Merchant Text A-Z capital letters	`002123456789001`
qrPromptpayInfo .reference2	String	20	N	Second Reference number of the transaction from Merchant Text A-Z capital letters	`70012345000000123456`
qrPromptpayInfo .reference3	String	20	N	Third Reference number of the transaction from Merchant Text A-Z capital letters	`5301234231112342`

Request Body Example

{
    "transDate": "2018-12-31",
    "transTime": "15:21:35",
    "amount": "500.00",
    "approvalCode": "650258",
    "cardNetworkCode": "01",
    "qrPromptpayInfo": { 
        "billerId": "010555604520711",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}

Request Example

curl --location --globoff 'https://{{api-host}}/biller/v1/refund/reversal' \
--header 'Authorization: Bearer {{access-token}}' \
--header 'Signature: {{request-signature}}' \
--header 'Request-Ref: TXN20231120-0000023' \
--header 'Transmit-Date-Time: 2017-03-15T15:23:11.001+07:00' \
--header 'Content-Type: application/json' \
--data '{
    "transDate": "2018-12-31",
    "transTime": "15:21:35",
    "amount": "500.00",
    "approvalCode": "650258",
    "cardNetworkCode": "01",
    "qrPromptpayInfo": { 
        "billerId": "010555604520711",
        "reference1": "002123456789001",
        "reference2": "70012345000000123456",
        "reference3": "5301234231112342"
    }
}'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	3	Y	Response Code	`000`
responseMesg	String	50	Y	Response Message	`success`
data	Object
data .transactionId	String	12	Y	Payment Transaction ID	`65478923`

Response Body Example (Success)

{
    "responseCode": "000",
    "responseMesg": "Success",
    "data": {
        "transactionId": "65478923"
    }
}

Response Body Example (Failure)

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

Response Code

HTTP Status	Response Code	Response Message	Remark
200	000	Success	Success
400	211	Invalid format Signature	Header in response does not have signature.
400	211	Invalid data	Invalid JSON Invalid request input Invalid fields validation
401			Invalid access token Invalid signature No response body
403	052	Unknown Biller ID	Biller id or service code is not registered.
405			Method not allowed No response body
429			User has sent too many requests in a given amount of time. No response body
200	054	Internal System Unavailable	Response of business backend
200	209	Transaction not found	Response of business backend
200	210	Time out	Response of business backend
200	211	Invalid data	Response of business backend
200	213	Transaction already void	Response of business backend
200	214	Trans too old to void advice	Response of business backend Voiding is not possible anymore
200	215	Trans too old to pre-void	Response of business backend Transaction can't be pre voided if the processing date differs from the payment date. Pre voiding is only possible for transactions processed on the same day as the payment.
200	216	Voiding not allowed on this Transaction	Response of business backend
200	217	This transaction cannot be voided	Response of business backend
200	218	Voiding decline by host	Response of business backend
200	341	Service Provider not ready	Response of business backend
200	888	Other Errors	Response of business backend

Response HTTP Status

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