1. Overview

1.1 Authentication

BNC follows the SNAP standard : ASYMMETRIC WITH ACCESS TOKEN (SHA256WITHRSA)

1.2 Digital Signature Generation

The below are steps of digital signature generation:

Compose the string to sign:
1. Apply token: <X-CLIENT-KEY> + “|” + <X-TIMESTAMP>
2. Transactional:SHA256withRSA(clientSecret，stringtosign)with formula stringtosign= HTTPMethod+ “:” + EndPointURL> + “:” + LowerCase(HexEncode(SHA-256(Minify(<requestBody>)))) + “:” + <X-TIMESTAMP>
The signature string is generated from string to sign above with applying SHA-256 using private key, and then encode the result to base64.
Put the signature string into HTTP header “X-SIGNATURE”.

1.3 Digital Signature Validation

The below are steps of digital signature validation:

Take the signature from HTTP header “X-SIGNATURE”.
Decrypt the signature using public key which is pair with private key that used to generate the signature.
Verify the correctness of the signature based on SHA-256 signing against the string to sign.

If the verification is correct, then consume the message.

2. API Specification

HTTP Method	POST
Endpoint	`/open/bi/1.0.0/get/token`
SNAP Service Code	`73`

3. Request

3.1. Request Header

	Parameter Name	Type	Length	Required	Description	Sample
1	X-SIGNATURE	String	2048	M	Asymmetric Signature SHA256withRSA (Private_Key, stringToSign). stringToSign = client_ID + “\|” + X-TIMESTAMP
2	X-TIMESTAMP	String	25	M	Timestamp request. Formatted as `yyyy-MM-ddTHH:mm:ssS`	2022-09-28T13:00:00+07:00
3	X-CLIENT-KEY	String	32	M	Merchant ID. Provided by BNC	000580000134

Parameter Name

Type

Length

Required

Description

Sample

X-SIGNATURE

String

2048

Asymmetric Signature SHA256withRSA

(Private_Key, stringToSign).

stringToSign = client_ID + “|” + X-TIMESTAMP

X-TIMESTAMP

String

Timestamp request. Formatted as yyyy-MM-ddTHH:mm:ssS

2022-09-28T13:00:00+07:00

X-CLIENT-KEY

String

Merchant ID. Provided by BNC

000580000134

3.2 Request Body

Name	Type	M/O	Length	Description
grant_type	String	M	30	“client_credentials” : The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control (OAuth 2.0: RFC 6749 & 6750)
additionalInfo	String	O	Object

3.2.1 Sample Request Body

{
   "grantType":"client_credentials",
   "additionalInfo":{
   }
}

4. Response

4.1 Response Body

Name	Type	M/O	Length	Description
accessToken	String	M	256	accessToken
expiresIn	String	M	32	Merchant ID. Provided by BNC.
responseCode	String	O	32	Sub Merchant ID of the Merchant. This property depends on merchant. Provided by BNC.
responseMessage	String	M	6	Merchant allow to provide type of the platform they use such as APP, WEB, MOBILE.
tokenType	String	M	2048	URL redirect to merchant apps

4.1.1 Sample Response Body

Success:

{
    "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJCWUIiLCJzdWIiOiIwMDA1MTAwMDAyMzMiLCJpYXQiOjE3MDE4NDgyMzMsImV4cCI6MTcwMjQ1MzAzM30.3UNMyNge7iANifz_fzU7qR15nM98QTiIRLD_mQw-_30",
    "expiresIn": "900",
    "responseCode": "2007300",
    "responseMessage": "Successful",
    "tokenType": "Bearer"
}

Fail:

{
    "responseCode": "4010000",
    "responseMessage": "Unauthorized Client"
}

{
    "responseCode": "4010000",
    "responseMessage": "Unauthorized Signature"
}

	Error Code	Error Message	Description
1	4010000	Unauthorized Client
2	4010000	Unauthorized Signature	Incorrect signature

6. Reference

	Field Code	Field Name	Description
1	M	Mandatory	Mandatory
2	ME	Mandatory Equal	Mandatory Equal – value in the request and the response must be the same.
3	C	Conditional	Conditional
4	CE	Conditional Equal	Conditional Equal – value in the request and the response must be the same.
5	O	Optional	Optional