1. Introduction

To start your integration with BillDesk, there are certain mandatory steps need to be followed to secure the transfer of payload over internet. As a result, all such requests need to be encrypted & signed. At BillDesk, we follow Symmetric JOSE approach to encrypt and sign the requests.

Symmetric JOSE is a framework intended to provide a method to securely transfer claims (such as authorization information) between BillDesk and merchants. The JOSE framework provides a collection of specifications to serve this purpose.

2. Salient Features

• Integrity: Verifying that data has not been tampered when transferred over internet.
• Authenticity: Verifying the origin of the data.
• Confidentiality: Keeping data secret from unauthorized parties and processes.

3. Integration Steps - Symmetric JOSE

To initiate a request to BillDesk, you need to follow certain steps that are mandatory to secure & maintain integrity of the it when transferred over internet.

1. JSON Request (Request fields required for the API).
2. Client Id - clientid is shared by BillDesk.
3. Encrypt the request.
4. Signing the encrypted request.
5. Reverse process needs to be followed to decrypt Billdesk responses:
   • Verify Signature.
   • Decrypt the verified response.
   • Process the JSON response as per your requirements.

To generate a request payload to BillDesk, there are essentially 4 steps involved which are as follows:

Step 1 - Create the JSON Request

Create the JSON request with required attributes/fields. An example for Create Order is provided below

{
	"mercid": "BDMERCID",
	"orderid": "order45608988",
	"amount": "300.00",
	"order_date": "2023-07-16T10:59:15+05:30",
	"currency": "356",
	"ru": "https://www.merchant.com/",
	"additional_info": {
		"additional_info1": "Details1",
		"additional_info2": "Details2",
		"additional_info7": "mgl"
	},
	"itemcode": "DIRECT",
	"device": {
		"init_channel": "internet",
		"ip": "<customer’s ip>",
		"user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;)Gecko/20100101Firefox/51.0",
		"accept_header": "text/html",
		"fingerprintid": "61b12c18b5be34a23ca64bb19",
		"browser_tz": "-330",
		"browser_color_depth": "32",
		"browser_java_enabled": "false",
		"browser_screen_height": "601",
		"browser_screen_width": "657",
		"browser_language": "en-US",
		"browser_javascript_enabled": "true"
	}
}

Step 2 - Encrypt the JSON Request

To create the encrypted request you need to pass JSON request along with encryption key, refer below sample code.

// encryptionKey - Encryption key provided by BillDesk
SecretKey key = new SecretKeySpec(encryptionKey.getBytes(), "AES");
// keyId - Is the BillDesk provided encryption key id
// clientid - clientId provided by BillDesk for the integration
JWEHeader jweHeader = new JWEHeader.Builder(JWEAlgorithm.DIR, EncryptionMethod.A128GCM).keyID(keyId).customParam("clientid", clientid).build();
Payload payload = new Payload(responseString);
JWEObject jweObject = new JWEObject(jweHeader, payload);
jweObject.encrypt(new DirectEncrypter(key));
String jweEncryptedData = jweObject.serialize();
return jweEncryptedData;

Step 3 - Sign the Encrypted Request

To create the signed request you need to pass encrypted request from Step 2 along with signing key, refer the below sample code.

// signingKey - Signing key provided by BillDesk
JWSSigner jwsSigner = new MACSigner(signingKey);
HashMap<String, Object> customParams = new HashMap();
// keyId - Is the BillDesk provided signing key id
// clientid - clientId provided by BillDesk for the integration
customParams.put("clientid", clientid);
JWSHeader jwsHeader = (new JWSHeader.Builder(jwsAlgorithm)).keyID(keyId).customParams(customParams).build();
JWSObject jwsObject = new JWSObject(jwsHeader, new Payload(requestString));
Provider bc = BouncyCastleProviderSingleton.getInstance();
jwsSigner.getJCAContext().setProvider(bc);
jwsObject.sign(jwsSigner);
return jwsObject.serialize();

The above step will give you a signed encrypted request that needs to be sent BillDesk in the API request body.

🚧

Prepare Final Request to BillDesk

A step by step guide to create final request to BillDesk when calling any API. Please follow the below instructions

Step 4 - How to initiate the API Request to BillDesk

Follow below steps to send request to BillDesk APIs.

Step 4.1 - Set the header as below

The header consists of below attributes that are required by BillDesk. Here BD-Traceid and BD-Timestamp are required to track a request at BillDesk end (to check success/failure logs):

Step 4.2 - Keep the payload as mentioned in Step #3

Step 4.3 - Select the API endpoint as mentioned below in the table

Step 4.4 - Send the request to the selected API endpoint from your server (application server)

Step 4.5 - BillDesk will send a response

1. Receive the response at your end.
2. Verify using BillDesk provided signing key.
3. Decrypt using BillDesk provided encryption key.
4. Process at your end to manage the internal workflows.

4. Integration Steps - Asymmetric JOSE

To initiate a request to BillDesk, you need to follow certain steps that are mandatory to secure & maintain integrity of the it when transferred over internet.

1. JSON Request (Request fields required for the API).
2. Client Id - clientid is shared by BillDesk.
3. Encrypt the request (using BillDesk provided Public Encryption Key).
4. Signing the encrypted request (using Merchant provided Private Signing Key).
5. Reverse process needs to be followed to decrypt Billdesk responses:
   • Verify Signature (using BillDesk provided Public Signing Key).
   • Decrypt the verified response (using Merchant provided Private Encryption Key).
   • Process the JSON response as per your requirements.

To generate a request payload to BillDesk, there are essentially 4 steps involved which are as follows:

Step 1 - Create the JSON Request

Create the JSON request with required attributes/fields. An example for Create Order is provided below

{
	"mercid": "BDMERCID",
	"orderid": "order45608988",
	"amount": "300.00",
	"order_date": "2023-07-16T10:59:15+05:30",
	"currency": "356",
	"ru": "https://www.merchant.com/",
	"additional_info": {
		"additional_info1": "Details1",
		"additional_info2": "Details2",
		"additional_info7": "mgl"
	},
	"itemcode": "DIRECT",
	"device": {
		"init_channel": "internet",
		"ip": "<customer’s ip>",
		"user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;)Gecko/20100101Firefox/51.0",
		"accept_header": "text/html",
		"fingerprintid": "61b12c18b5be34a23ca64bb19",
		"browser_tz": "-330",
		"browser_color_depth": "32",
		"browser_java_enabled": "false",
		"browser_screen_height": "601",
		"browser_screen_width": "657",
		"browser_language": "en-US",
		"browser_javascript_enabled": "true"
	}
}

Step 2 - Encrypt the JSON Request

To create the encrypted request you need to pass JSON request along with Public encryption key, refer below sample code.

// encryptionKey - Public Encryption key provided by BillDesk
SecretKey key = new SecretKeySpec(encryptionKey.getBytes(), "RSA");
// keyId - Is theBillDesk provided Public Encryption key id
// clientid - clientId provided by BillDesk for the integration
JWEHeader jweHeader = new JWEHeader.Builder(JWEAlgorithm.DIR, EncryptionMethod.A128GCM).keyID(keyId).customParam("clientid", clientid).build();
Payload payload = new Payload(responseString);
JWEObject jweObject = new JWEObject(jweHeader, payload);
jweObject.encrypt(new DirectEncrypter(key));
String jweEncryptedData = jweObject.serialize();
return jweEncryptedData;

Step 3 - Sign the Encrypted Request

To create the signed request you need to pass encrypted request from Step 2 along with Private Signing key that you have generated, refer the below sample code.

// signingKey - Private Signing key created/generated by Merchant
JWSSigner jwsSigner = new MACSigner(signingKey);
HashMap<String, Object> customParams = new HashMap();
// keyId - Is the Merchant provided signing key id
// clientid - clientId provided by BillDesk for the integration
customParams.put("clientid", clientid);
JWSHeader jwsHeader = (new JWSHeader.Builder(jwsAlgorithm)).keyID(keyId).customParams(customParams).build();
JWSObject jwsObject = new JWSObject(jwsHeader, new Payload(requestString));
Provider bc = BouncyCastleProviderSingleton.getInstance();
jwsSigner.getJCAContext().setProvider(bc);
jwsObject.sign(jwsSigner);
return jwsObject.serialize();

The above step will give you a signed encrypted request that needs to be sent BillDesk in the API request body.

🚧

Prepare Final Request to BillDesk

A step by step guide to create final request to BillDesk when calling any API. Please follow the below instructions

Step 4 - How to initiate the API Request to BillDesk

Follow below steps to send request to BillDesk APIs.

Step 4.1 - Set the header as below

The header consists of below attributes that are required by BillDesk. Here BD-Traceid and BD-Timestamp are required to track a request at BillDesk end (to check success/failure logs):

Step 4.2 - Keep the payload as mentioned in Step #3

Step 4.3 - Select the API endpoint as mentioned below in the table

Step 4.4 - Send the request to the selected API endpoint from your server (application server)

Step 4.5 - BillDesk will send a response

1. Receive the response at your end.
2. Verify using BillDesk provided Public Signing key.
3. Decrypt using Merchant provided Private encryption key.
4. Process at your end to manage the internal workflows.