Bill Payment App to App

Bill Payment Service that a simple button to enable deep-linking between your app and Bangkok Bank Mobile App

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

App2App Payment Initiation

Using App2App payment initiation API, Merchants can request to create payment deep links for their order transaction in order to allow their customers to pay via Bangkok Bank mobile application.

App2App Notification

Using App2App Notification 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 completed through the deep-link.

App2App Get Payment Request

Using this API, Merchants can request to inquire payment status for particular payment request ID.

POST /apptoapp/v1/paymentinitiation/payment-requests

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

Sandbox:
https://api-sandbox.bangkokbank.com/apptoapp/v1/paymentinitiation/payment-requests
PROD:
https://api.bangkokbank.com/apptoapp/v1/paymentinitiation/payment-requests

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 Body

Parameter	Type	Size	Mandatory	Description	Example/Values
serviceCode	String	12	Y	Service code of the Payee	`BBLTest`
billerId	String	15	Y	TaxId and Suffix of the Payee	`123456789012345`
reference1	String	20	Y	First Reference number of the transaction from Partner	`1124579998`
reference2	String	20	N	Second Reference number of the transaction from Partner	`22555347`
totalAmount	Decimal	11	Y	Total amount (2 decimal digits), support Thai currency only Max is 999999999.99	`114.00`
shopImageFile	String		N	Shop Image in base64 format, photo size is not more than 30 KB
shopName	String	75	Y	Shop name	`ABC Shop`
osPlatform	String	10	Y	Mobile OS platform (Capital Letter and Sensitive Case)	Android: `ANDROID` iOS: `IOS`
currencyCode	String	3	Y	Currency Code	`THB`
shippingFee	Decimal	8	N	Order shipping fee (2 decimal digits) Max is 999999.99	`30.00`
buyerName	String	75	N	Name of Customer	`Customer`
promotionCode	String	255	N	Promotion Code	`BBLSAV10`
partnerAppUrl	String	512	N	Android: Always send this value "APP2APP" iOS: Format BundleID://Path_Destination WebSite: Must start with https	Android: `APP2APP` iOS: `com.bangkokbank.mobilepartnersandbox://payment` WebSite: `https://payment.BBLTest/result`
transType	String	20	Y	Transaction type: If Client is Mobile Application(Android,iOS) then always send this value "APP2APP" If Client is WebSite then always send this value "WEB2APP"	Android: `APP2APP` iOS: `APP2APP` WebSite: `WEB2APP`
additionalInfo	Object		N
additionalInfo[] .name	String	32	Y	Key Not allowed emoji and these characters $?!{}#%=\|~<>;•	`Exchange Rate`
additionalInfo[] .value	String	255	Y	Value Not allowed emoji and these characters $?!{}#%=\|~<>;•	`32.123THB`

Request Body Example

{
    "transType": "APP2APP",
    "serviceCode": "BBLTest",
    "billerId": "123456789012345",
    "reference1": "123456789",
    "reference2": "78897",
    "totalAmount": 114.00,
    "shopName": "ABC Shop",
    "osPlatform": "ANDROID",
    "currencyCode": "THB",
    "buyerName": "Customer",
    "shippingFee": 30.00,
    "partnerAppUrl": "APP2APP",
    "promotionCode": "BBLSAV10",
    "shopImageFile": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAMAAADDpiTIAAAAA3NCSVQICAjb4U/gAAAACXBIWXMAAJOjAACTowHRsvDGAAAAGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48GgAAAvFQTFRF////AAAAAAAAAAA==",
    "additionalInfo": [
        {
            "name": "Exchange Rate",
            "value": "32.123THB"
        }
    ]
}

Request Example

curl --request POST 'https://{{api-host}}/apptoapp/v1/paymentinitiation/payment-requests' \
--header 'Authorization: Bearer {{access-token}}' \
--header 'Signature: {{request-signature}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "serviceCode":"BBLTest",
    "billerId":"123456789012345",
    "reference1":"1124579998",
    "reference2":"78897",
    "totalAmount":114.00,
    "shopImageFile": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAMAAADDpiTIAAAAA3NCSVQICAjb4U/gAAAACXBIWXMAAJOjAACTowHRsvDGAAAAGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48GgAAAvFQTFRF////ErkJxxx==",
    "shopName":"ABC Shop",
    "osPlatform":"ANDROID",
    "currencyCode":"THB",
    "shippingFee":30.00,
    "buyerName":"Customer",
    "promotionCode":"BBLSAV10",
    "partnerAppUrl":"APP2APP",
    "transType":"APP2APP"
}'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	3	Y	Response Code	`000`
responseMesg	String	50	Y	Response Message	`success`
paymentRequestId	String	50	N	Payment request reference ID generated by BBL	`8E17E5D0-4B67-4BFB-AC48-4C57DF8369E`
bankAppUrl	String	512	N	URL for partner application use to switch to the mobile banking application	`bualuangmbanking://mbanking.payment?paymentRequestId={0}&app2appToken={1}`
expiryDate	Datetime	512	N	The transaction will be expired within 24 hours	`2017-03-15T15:23:11.001+07:00`
additionalInfo	Object[]		N
additionalInfo[] .name	String	32	Y	Key Not allowed emoji and these characters $?!{}#%=\|~<>;•	`Exchange Rate`
additionalInfo[] .value	String	255	Y	Value Not allowed emoji and these characters $?!{}#%=\|~<>;•	`32.123THB`
apptoappToken	String	2048	N		`eyJbGci0iJSUzI1NiIsImtpZCI6IkY5MUJ`

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

Request Body

Parameter	Type	Size	Mandatory	Description	Example/Values
data	Object
data .paymentRequestId	String	50	Y	Payment request reference ID generated by BBL	`8E17E5D0-4B67-4BFB-AC48-4C57DF8369E`
data .serviceCode	String	12	Y	Service code of the Payee	`BBLTest`
data .billerId	String	15	Y	TaxId and Suffix of the Payee	`123456789012345`
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 .totalAmount	Decimal	11	N	Total amount (2 decimal digits), support Thai currency only Max is 999999999.99	`114.00`
data .currencyCode	String	3	N	Currency Code	`THB`
data .paymentStatus	String	10	Y	A customer payment transaction status	`rejected`
data .paymentDateTime	String		N	Data and Time of the successful payment transaction	`2023-03-31T15:23:11.001+07:00`
data .paymentReferenceID	String	6	N	Reference ID of the successful payment transaction from BBL	`234ABB58CC000`
data .slipImage	String		N	BBL slip in base64 format of the successful payment transaction
type	String			Application type Fixed Value: AppToApp	`AppToApp`

Request Body Example

{
    "data": {
        "paymentRequestId": "8E17E5D0-4B67-4BFB-AC48-4C57DF8369E",
        "serviceCode": "BBLTest",
        "billerId": "123456789012345",
        "reference1": "123456789",
        "reference2": "78897",
        "totalAmount": 114.00,
        "currencyCode": "THB",
        "paymentStatus": "rejected",
        "paymentDateTime": "2023-03-31T15:23:11.001+07:00",
        "paymentReferenceID": "234ABB58CC000",
        "slipImage": null
    },
    "type": "AppToApp"
}

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

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

GET /apptoapp/v1/paymentinitiation/payment-requests/{paymentRequestId}

Web Services: RESTful JSON

HTTP Method: GET

Character encoding: UTF-8

Content Type: application/json

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

Request URLs

Sandbox:
https://api-sandbox.bangkokbank.com/apptoapp/v1/paymentinitiation/payment-requests/{paymentRequestId}
PROD:
https://api.bangkokbank.com/apptoapp/v1/paymentinitiation/payment-requests/{paymentRequestId}

Request URL Path and Query Parameter

Parameter	Type	Size	Mandatory	Description	Example/Values
paymentRequestId	String	50	Y	Payment request reference ID generated by BBL	`4D13BE6A-DAAF-4E2F-A7A9-2558160C8422`

Request Headers

Parameter	Type	Size	Mandatory	Description	Example/Values
Authorization	String	100	Y	Bearer {accessToken}	`Bearer 6LJQPMEMnrSGgEr7aAWszZaTAnZL`

Request Example

curl --request GET 'https://api-sandbox.bangkokbank.com/apptoapp/v1/paymentinitiation/payment-requests/4D13BE6A-DAAF-4E2F-A7A9-2558160C8422' \
--header 'Authorization: Bearer 6LJQPMEMnrSGgEr7aAWszZaTAnZL'

Response Body

Parameter	Type	Size	Mandatory	Description	Example/Values
responseCode	String	4	Y	Response Code	`10003`
responseMesg	String	100	Y	Response Message	`invalid format`
data	Object
data .partnerInfo	Object		N	Partner Info Detail
data .partnerInfo .partnerName	String				`app2apppayment`
data .partnerInfo .partnerId	String				`BBLTest`
data .partnerInfo .serviceCode	String			Service code of the Payee	`BBLTest`
data .partnerInfo .taxIdSuffix	String			TaxId and Suffix of the Payee	`123456789012345`
data .paymentInfo	Object		N	Payment Info Detail
data .paymentInfo .paymentRequestId	String			Payment request reference ID generated by BBL in the “Payment Initiation” API	`8E17E5D0-4B67-4BFB-AC48-4C57DF8369E`
data .paymentInfo .paymentReferenceId	String			Reference ID of the successful payment transaction from BBL	`234ABB58CC000`
data .paymentInfo .paymentStatus	String			A customer payment transaction status	`rejected`
data .paymentInfo .transType	String			Transaction type: If Client is Mobile Application(Android,iOS) then always send this value "APP2APP" If Client is WebSite then always send this value "WEB2APP"	Android: `APP2APP` iOS: `APP2APP` WebSite: `WEB2APP`
paymentInfo .createdDateTime	Datetime			Data and Time of the payment creation	`2022-05-05T18:05:30.68`
data .paymentInfo .paymentDateTime	Datetime			Data and Time of the successful payment transaction	`2023-03-31T15:23:11.001+07:00`
data .paymentInfo .expiryDate	Datetime			The transaction will be expired within 24 hours	`2022-05-05T18:05:30.68`
data .paymentInfo .slipImage	String			BBL slip in base64 format of the successful payment transaction
data .paymentInfo .shopName	String			Shop name	`ABC Shop`
data .paymentInfo .currencyExponent	Decimal			Decimal	`0`
data .paymentInfo .reference1	String			First Reference number of the transaction from Partner	`1124579998`
paymentInfo .reference2	String			Second Reference number of the transaction from Partner	`22555347`
data .paymentInfo .totalAmount	Decimal			Total amount (2 decimal digits), support Thai currency only Max is 999999999.99	`114.00`
data .paymentInfo .currencyCode	String			Currency Code	`THB`
data .paymentInfo .shopImage	String
data .paymentInfo .shopImageFile	String			Shop Image in base64 format
data .additionalInfo	Object[]
data .additionalInfo[] .name	String			Key Not allowed emoji and these characters $?!{}#%=\|~<>;•	`Exchange Rate`
data .additionalInfo[] .value	String			Value Not allowed emoji and these characters $?!{}#%=\|~<>;•	`32.123THB`
data .callback	Object
data .callback .osPlatform	String			Mobile OS platform (Capital Letter and Sensitive Case)	Android: `ANDROID` iOS: `IOS`
data .additionalInfo[] .partnerAppUrl	String			Android: Always send this value "APP2APP" iOS: Format BundleID://Path_Destination WebSite: Must start with https	Android: `APP2APP` iOS: `com.bangkokbank.mobilepartnersandbox://payment` WebSite: `https://payment.BBLTest/result`

Response Body Example (Success)

{
    "responseCode": "000",
    "responseMesg": "Success",
    "data": {
        "partnerInfo": {
            "partnerName": "app2apppayment",
            "partnerId": "BBLTest",
            "serviceCode": " BBLTest",
            "taxIdSuffix": "123456789012345"
        },
        "paymentInfo": {
            "paymentRequestId": "8E17E5D0-4B67-4BFB-AC48-4C57DF8369E",
            "paymentReferenceId": "234ABB58CC000",
            "paymentStatus": "rejected",
            "transType": "APP2APP",
            "createdDateTime": "2022-05-05T18:05:30.68",
            "paymentDateTime": null,
            "expiryDate": "2022-05-05T18:05:30.68",
            "slipImage": null,
            "paymentAccount": null,
            "shopName": "ABC Shop",
            "currencyExponent": 0,
            "reference1": "123456789",
            "reference2": "78897",
            "totalAmount": 114.00,
            "currencyCode": "THB",
            "shopImage": "https://www.image.com/mockup/123456",
            "shopImageFile": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAMAAADDpiTIAAAAA3NCSVQICAjb4U/gAAAACXBIWXMAAJOjAACTowHRsvDGAAAAGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48GgAAAvFQTFRF////U5ErkJxxx=="
        },
        "additionalInfo": [
            {
                "name": "Exchange Rate",
                "value": "32.123THB"
            }
        ],
        "callback": {
            "osPlatform": "ANDROID",
            "partnerAppUrl": "com.bangkokbank.mobilepartnersandbox://payment"
        }
    }
}

Response Code

HTTP Status Code	Response Code	Response Message
200	0000	Success
200	0215	Invalid Token
400	1001	Required field not found (specific field name in error message)
400	1002	Field exceed maximum length (specific field name in error message)
400	1003	Invalid format (specific field name in error message)
400	1005	Payment request id not found
400	1006	Shop image to large
500	500	Others

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