Integration service to generate payments deep-link between merchant & BBL's mobile app.
Bill Payment App to App
Digital Signature Token Structure
The signature token follows the standard JSON Web Token format RFC 7519 contains the
following claims (elements)
Token HEADER
Claim | Description | Example |
---|---|---|
typ | Type | JWT |
alg | Algorithm | RS256 |
Body Claim | API Request Payload / API Response Payload |
API JSON Request Payload/API JSON Response Payload |
"exp" (Expiration Time) Claim |
Now + 1 Day (timestamp) | 1655995873 |
"Iat" (Issued At) Claim |
Time to create token (timestamp) |
1655967073 |
jti (JWT ID) Claim |
UUID | ba7544f4-a7c5-4362-8009-51f1ab25 e132 |
Verify Token Signature
RSASHA256(base64UrlEncode(header) + "." +base64UrlEncode(payload),Public key,Private key)
Guide to generating certificate for JWT Signature:
- Generating a Private Key (Used for signing digital signatures.) :
openssl genrsa -aes256 -out private_key.pem 2048
- Generating a Public Key (Used for validation digital signatures.):
openssl rsa -pubout -in private_key.pem -out public_key.pem
For production, it is not recommended to use the self-sign certificate.
oAuth Client Credentials
POST /oauth/accesstoken
Header
Parameter | Type | Size | Description | Example/Values |
---|---|---|---|---|
Authorization | string | 100 | Basic authentication Token encode with Base64 String = [client_id] : [client_secret] Basic [Token] | Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ |
Header request example
curl --request POST ' https://api-sandbox.bangkokbank.com/oauth/accesstoken' \
--header 'Authorization: Basic b2hSQllvMExBVkE5RVJ2MERZeGJNb3FnRWpCT3B5WjU6WUNCam50RWlBazN2Y2NGdw==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=READ CREATE' \
--data-urlencode 'grant_type=client_credentials'
Form parameter
Parameter | Type | Size | Description | Example/Values |
---|---|---|---|---|
grant_type | string | 20 | oAuth grant type | “client_credentials” |
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 | N | Scope token defined by BBL depending on sub-service | Null, READ |
{
"accessToken":"VAGw4iJj5peD2fXlVsI2GhS1Hblp",
"expiresIn":"86399",
"scope":""
}
Payment Initiation
Web Services: RESTful JSON
HTTP Method: POST
Character encoding: UTF-8
Content-Type: application/json
Authorization: Bearer authentication(oAuth token Client Credential grant type)
https://api-sandbox.bangkokbank.com/apptoapp/v1/paymentinitiation/payment-requests
POST /apptoapp/v1/paymentinitiation/payment-requests
Request Header
No. | Parameter | Type | Size | Description | Example/Values |
---|---|---|---|---|---|
1 | Authorization | string | 100 | Bearer [accessToken] | Bearer ylSkZIjbdWybfsUQe9B qP0LH5Z |
2 | Signature | string | - | Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure |
Request Body
No. | Parameter | Type | Size | Mandatory | Description | Example/Values |
---|---|---|---|---|---|---|
1 |
serviceCode |
string |
12 |
Y |
Service code of the Payee |
BBLTest |
2 |
billerId |
string |
15 |
Y |
TaxId and Suffix of the Payee |
123456789012345 |
3 |
reference1 |
string |
20 |
Y |
First Reference number of the transaction from Partner |
123456789 |
4 |
reference2 |
string |
20 |
N |
Second Reference number of the transaction from Partner |
78897 |
5 |
totalAmount |
decimal |
11 |
Y |
Total amount (2 decimal digits), support Thai currency only, Max is 999999999.99 |
114.00
|
6 |
shopImageFile |
base64 |
|
N |
Shop Image in base64 format, photo size is not more than 30 KB |
|
7 |
shopName |
string |
75 |
Y |
Shop name |
ABC Shop |
8 |
osPlatform |
string |
10 |
Y |
Mobile OS platform (Capital Letter and Sensitive Case) |
Android: ANDROIDiOS: IOS |
9 |
currencyCode |
string |
3 |
Y |
Currency Code |
THB |
10 |
shippingFee
|
decimal |
8 |
N |
Order shipping fee (2 decimal digits), Max is 999999.99 |
30.00 |
11 |
buyerName |
string |
75 |
N |
Name of Customer |
Customer |
12 |
promotionCode |
string |
255 |
N |
Promotion Code |
BBLSAV10 |
13 |
partnerAppUrl |
string |
512 |
N |
Android: Always send this value “APP2APP” iOS: Format BundleID://Path_Destination |
Android: APP2APPiOS:com.bangkokbank.
|
14 |
transType |
string |
20 |
Y |
Transaction type |
APP2APP |
15 |
additionalInfo |
Array <Name Value Pair> |
|
N |
Additional Info Detail Not allowed emoji and these characters $?!{}#%=|~<>;•
|
|
Note: Mandatory =N, means the field is not required to send or it can be null value
additionalInfo Array Object
No. | Parameter | Type | Size |
---|---|---|---|
1 | name | string | 100 |
2 | value | string | - |
Example request
{
"transType":"APP2APP",
"serviceCode":"BBLSANDBOX",
"billerId":"123456789012345",
"reference1":"123456789",
"reference2":"78897",
"totalAmount":"114.00",
"shopName":"shopName Sandbox",
"osPlatform":"ANDROID",
"currencyCode":"THB",
"shopImage":"Sandbox",
"buyerName":"Sandbox",
"shippingFee":0,
"partnerAppUrl":"com.bangkokbank.mobilepartnersandbox://payment",
"promotionCode":"Apigee",
"shopImage":"https://www.image.com/mockup",
"shopImageFile": "data:image/png;base64,iVBORw0KGgoAAAANNCSVQICAjb4U..."
"additionalInfo": [
{
"Name": "TESTNAME1",
"Value": "TESTVALUE"
},
{
"Name": "TESTNAME2",
"Value": "TESTVALUE"
}
]
}
Response Header
No. | Parameter | Type | Size | Description | Example/Values |
---|---|---|---|---|---|
1 | Signature | string | - | Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure |
Response Body
No. | Parameter | Type | Size | Mandatory | Description | Example/Values |
---|---|---|---|---|---|---|
1 | responseCode | string | 4 | Y | Response Code | 0000 |
2 | responseMesg | string | 100 | Y | Response Message | success |
3 | paymentReques tId | string | 50 | N | Payment Request reference ID generated by BBL | 234ABB58CC000 |
4 | bankAppUrl | string | 512 | N | URL for partner application use to switch to the mobile banking application | {Bank.App.URI.Sche me}://mbank.paym ent? paymentRequestId ={ paymentRequestId} |
5 | expiryDate | datetime | N | The transaction will be expired within 24 hours | 2017-03- 15T15:23:11.001+0 7:00 | |
6 | additionalInfo | Array <NameValuePair> | N | Additional Information | ||
7 | apptoappToken | String | 2048 | N |
Example response
{
"app2appToken":"eyJbGci0iJSUzI1NiIsImtpZCI6IkY5MUJ",
"paymentRequestId":"8E17E5D0-4B67-4BFB-AC48-4C57DF8369EF",
"bankAppUrl":"bualuangmbanking://mbanking.payment?paymentRequestId={0}",
"callback":{
"osPlatform":"ANDROID",
"partnerAppUrl":"com.bangkokbank.mobilepartnersandbox://payment"
}
}
Get Payment Result
Web Services: RESTful JSON
HTTP Method: GET
Character encoding: UTF-8
Content Type: application/json
Authorization: Bearer authentication(oAuth token Client Credential grant type)
https://api-sandbox.bangkokbank.com/apptoapp/v1/paymentinitiation/payment-requests /@paymentRequestId@
GET /apptoapp/v1/ paymentinitiation/paymentrequests/
URL Path and Query Parameter
No. | Parameter | Type | Size | Description | Example/Values |
---|---|---|---|---|---|
1 | paymentRequestId | string | 50 | Payment request reference ID generated by BBL | 4D13BE6A-DAAF-4E2F-A7A9-2558160C8422 |
Request Header
No. | Parameter | Type | Size | Description | Example/Values |
---|---|---|---|---|---|
1 | Authorization | string | 100 | Bearer [accessToken] | Bearer 6LJQPMEMnrSGgEr7aAWszZaTAnZL |
Response Body
No. | Parameter | Type | Size | Mandatory | Description | Example/Values |
---|---|---|---|---|---|---|
1 | responseCode | string | 4 | Y | Response Code | 1003 |
2 | responseMesg | string | 100 | Y | Response Message | invalid format |
3 | partnerInfo | object | N | Payment Info Detail | partnerInfo:{} | |
4 | paymentInfo | object | N | Payment Info Detail | paymentInfo:{} | |
5 | additionalInfo | object | N | Additional Info Detail | additionalInfo: {} | |
6 | callback | object | N | Callback Detail | callback:{} |
Mapping Response Body
No. | Parameter | Type |
---|---|---|
1 | partnerInfo | Object |
2 | paymentInfo | Object |
3 | additianalInfo | Object |
4 | callBackInfo | Object |
partnerInfo Object
No. | Parameter | Type |
---|---|---|
1 | partnerName | String |
2 | partnerId | String |
3 | serviceCode | String |
4 | taxIdSuffix | String |
PaymentInfo Object
No. |
Parameter |
Type |
1 |
paymentRequestId |
string |
2 |
paymentReferenceId |
string |
3 |
paymentStatus |
string |
4 |
transType |
string |
5 |
createdDateTime |
date |
6 |
paymentDateTime |
date |
7 |
expiryDate |
date |
8 |
slipImage |
string |
9 |
paymentAccount |
string |
10 |
shopName |
string |
11 |
currencyExponent |
decimal |
12 |
reference1 |
string |
13 |
reference2 |
string |
14 |
totalAmount |
decimal |
15 |
currencyCode |
string |
16 |
shopImage |
string |
17 |
shopImageFile |
string |
18 |
additionalInfo |
object |
19 |
callback |
object |
additionalInfo Array Object
No. | Parameter | Type |
---|---|---|
1 | name | string |
2 | value | string |
callBackInfo Array Object
No. | Parameter | Type |
---|---|---|
1 | osPlatform | string |
2 | partnerAppUrl | string |
Example Code
curl --request GET 'https://api-sandbox.bangkokbank.com/apptoapp/v1/paymentinitiation/payment-requests/4D13BE6A-DAAF-4E2F-A7A9-2558160C8422' \
--header 'Authorization: Bearer 6LJQPMEMnrSGgEr7aAWszZaTAnZL'
App to App Notification API
API Initiator: Bank system
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: https://[MERCHANT_CALLBACK_URL]
POST App To App Notification (BBL > Merchant)
Request Header
No. | Parameter | Type | Size | Description | Example/Values |
---|---|---|---|---|---|
1 | Authorization | string | 100 | Basic authentication Token encode with Base64 String = [client_id] : [client_secret] Basic [Token] | Basic c3FIOG9vSGV4VHoAyg5 T1JvNnJoZ3ExaVNyQWw 6WjRsanRKZG5lQk9qUE 1BVQ |
2 | Signature | string | - | Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure |
Request Body
No. | Parameter | Type | Size | Mandatory | Description | Example/Values |
---|---|---|---|---|---|---|
1 | paymentRe questId | string | 50 | Y | Payment request reference ID generated by BBL | 234ABB58CC00 |
2 | serviceCod e | string | 12 | N | Payment request reference ID generated by BBL | BBLTEST |
3 | billerId | string | 15 | Y | TaxId and Suffix of the Payee | 123456789012300 |
4 | reference1 | string | 30 | N | First Reference number of the transaction from Partner | 1124579998 |
5 | reference2 | string | 30 | N | Second Reference number of the transaction from Partner | 2255534 |
6 | totalAmou nt | decimal | 11 | N | Total amount (2 decimal digits), support Thai currency only | 250.00 (max is 999999999.99) |
7 | currencyCo de | string | 3 | N | Currency code | THB |
8 | paymentSt atus | string | 10 | Y | A customer payment transaction status | success |
9 | paymentAc count | string | 15 | N | A payment account in mask format *has value when status = ‘success’ | xxx-x-x0055-x |
10 | paymentDa teTime | string | N | Data and Time of the successful payment transaction | 2017-03-15T15:23:11.00 1+07:00 | |
11 | paymentRe ferenceID | string | 6 | N | Reference ID of the successful payment transaction from BBL | 123456 |
12 | slipImage | Base64 | N | BBL slip in base64 format of the successful payment transaction |
Example Request
{
"type":"ApptoApp",
"data":{
"paymentRequestId":"48C4BE86-D7F2-4B2B-B507-81C8688820AA",
"serviceCode":"BBL01",
"billerId":"123456789012345",
"paymentAccount":null,
"reference1":"123456789",
"reference2":"89406974",
"reference3":"123456789",
"totalAmount":114.00,
"currencyCode":"THB",
"paymentStatus":"rejected",
"paymentReferenceID":"234ABB58CC000",
"paymentDateTime":"3/31/2022 9:27:22 AM",
"paymentReferenceID":null,
"slipImage":null
}
}
Response Header
No. | Parameter | Type | Size | Description | Example/Values |
---|---|---|---|---|---|
1 | Signature | string | - | Digital Signature sign with JWT RSA256 detail in Digital Signature Token Structure |
Response Body
No. | Parameter | Type | Size | Mandatory | Description | Example/Values |
---|---|---|---|---|---|---|
1 | responseCode | string | 4 | Y | Response Code | 000 |
2 | responseMesg | string | 100 | Y | Response Message | success |
Example Response
{
"responseCode":"0000",
"responseMesg":"Success"
}
Response Code
Response Code
HTTP Status Code | Response Code | Response Message |
---|---|---|
400 | 1001 | Required field not found (specific field name in error message) responseCode: 1001 responseMesg : 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 | 9999 | Others |
HTTP Error Response Codes
Status Code | 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 |
Mobile App Deeplink Construct
Android
PartnerApp to mBankingApp
bualuangmbanking://mbanking.payment?paymentRequestId={paymentRequestId}
Remark: Please use “startActivityForResult” for calling mBanking
mBankingApp to PartnerApp
mBanking will call to Partner by following script
Intent resultIntent = new Intent();
resultIntent.putExtra("payment_status", "success");
setResult(Activity.RESULT_OK, resultIntent);
finish();
Parameters: payment_status=[ success | failure ]
Note: Android app should call mBanking app using default launch mode, which is done by without specifying any intent to use different launch mode. (i.e. they should not use any of FLAG_ACTIVITY_NEW_TASK, FLAG_ACTIVITY_SINGLE_TOP, FLAG_ACTIVITY_CLEAR_TOP intent.)
iOS
PartnerApp to mBankingApp
Please append “Callback URL” when switching from PartnerApp to mBanking App:
Bualuangmbanking://mbanking.payment?paymentRequestId={paymentRequestId} &callback_url={BundleID}
mBankingApp to PartnerApp
{partnerAppUrl}?payment_status={ success | failure }
Note: partnerAppUrl is sent at “Payment Initiation” API (Field#13. partnerAppUrl)
Example: com.bangkokbank.mobilepartnersandbox://payment?payment_status=success