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 JOSE approach to encrypt and sign the requests.

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

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.

JSON Request (Request fields required for the API)
Client Id - clientid is shared by BillDesk
Encrypt the request
Signing the encrypted request
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",
	}
}

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.A256GCM).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.

📘
Note

The above example illustrates signing and encryption with BillDesk generated key. A symmetric JOSE approach

BillDesk also supports whitelisting of merchant public key for encryption and signing. For more details, please reach out to BillDesk Relationship Manager.

🚧
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)

Attribute	Description
Content-Type	`string` Request Content-Type to take the values application/jose
Accept	`string` Accept Response Content-Type to take the values application/jose
BD-Traceid	`string` Traceid is used for idempotency and the request with the same Traceid within the day will be rejected. Traceid can be alphanumeric without any spaces or special characters and should be a maximum size of 35
BD-Timestamp	`string` epoch timestamp of the server

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

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

Environment	API Endpoint
Sandbox	https://uat1.billdesk.com/u2/
Production	https://api.billdesk.com/

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

Step 4.5 - BillDesk will send a response

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