บริการชำระค่าสินค้าและบริการ แบบ App to App

บริการรับชำระค่าสินค้าและบริการ ที่มีการเชื่อมต่อระหว่าง Company App กับ Bangkok Bank Mobile App (Deep Link) ในรูปแบบ API

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: ANDROID iOS: 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: APP2APP iOS: com.bangkokbank.mobilepartnersandbox://payment
14	transType	string	20	Y	Transaction type	APP2APP
15	additionalInfo	Array <Name Value Pair>		N	Additional Info Detail Not allowed emoji and these characters $?!{}#%=\|~<>;•

No.

Parameter

Type

Size

Mandatory

Description

Example/Values

serviceCode

string

Service code of the Payee

BBLTest

billerId

string

TaxId and Suffix of the Payee

123456789012345

reference1

string

First Reference number of the transaction from

Partner

123456789

reference2

string

Second Reference number

of the transaction from

Partner

78897

totalAmount

decimal

Total amount (2 decimal digits), support Thai

currency only, Max is 999999999.99

114.00

shopImageFile

base64

Shop Image in base64 format, photo size is not more than 30 KB

shopName

string

Shop name

ABC Shop

osPlatform

string

Mobile OS platform

(Capital Letter and Sensitive Case)

Android:

ANDROID

iOS:

IOS

currencyCode

string

Currency Code

THB

shippingFee

decimal

Order shipping fee (2 decimal digits), Max is 999999.99

30.00

buyerName

string

Name of Customer

Customer

promotionCode

string

255

Promotion Code

BBLSAV10

partnerAppUrl

string

512

Android:

Always send this value

“APP2APP”

iOS:

Format

BundleID://Path_Destination

Android:

APP2APP

iOS:

com.bangkokbank.mobilepartnersandbox://payment

transType

string

Transaction type

APP2APP

additionalInfo

Array

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 vlaue

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

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