Introduction

The BillDesk Flutter SDK allows the merchant to seamlessly integrate the BillDesk payment suite with their application. The BillDesk Flutter SDK takes away the complexity of handling and integrating payment stack in a Flutter project. The SDK opens the payment page in a webview and completes the mandate setup journey within the merchant app sans any external redirections

Salient Features

• Low code integration - Accept payments with a few easy steps and minimal code with this offering
• Customizable - Customize aspects such as merchant's company logo, payment methods as well as themes to give their end customers an integrated experience

BillDesk Solutions for Recurring Payments

BillDesk's Flutter SDK has 2 flows for Recurring Payments. Merchants can pick a journey most suitable to their end customers and build their integration.

Prerequisites

• Obtain your Merchant ID (MID) from BillDesk
• Merchant’s Server public IP address to be whitelisted at BillDesk
• Download the BillDesk Flutter SDK libraries
• It is mandatory that all the below points are implemented, as per industry standards, in the merchant's mobile app (where the BillDesk Flutter SDK will be implemented):
  • Root/jailbroken device detection
  • Frida, debugger, and objection detection
  • Code obfuscation
  • Runtime manipulation checks
• Response of the Create Order API or Create Mandate Tokens API ( Explained in section 3.1)

Integration Steps

Step 1: Receive the BillDesk Flutter Libraries

Please contact your BillDesk Relationship Manager for more details

Note: We currently support dart versions between ">=3.5.0<4.0.0" and flutter versions ">=3.24.0".

Step 2: Integrating the BillDesk libraries in merchant app

1. Navigate to the directory where merchant wants to create their merchant Flutter app.
2. Run the command : $ flutter create my_flutter_app to create a new Flutter app
3. Copy the “billDeskSDK” project and paste it into the root level of the directory (Sample image of this command pasted below)
4. Import sdk in dependency and configure the path pubspec.yaml your project (Sample image of this command pasted below)

5. Add the below configuration in the pubspec file to include all the libraries

dependencies:  
  flutter:  
    sdk: flutter  
  billDeskSDK:  
    path: ./billDeskSDK

6. Navigate to the merchant app and billDeskSDK directory. Run the command $ flutter pub get to fetch and install the defined dependencies

Step 3: Preparing the Configurations

3.1 Creating an Order/ Mandate token

Depending on the work flow - One time payment & Mandate workflow or Only Mandate Setup workflow, the API to be called varies. Please refer to the below table for more details:

A. One time Payment & Mandate workflow

An order needs to be created for every transaction initiated using the BillDesk Flutter SDK.

To create an order use the Create Order API with the mandate object. The response of this API provides the bdorderIdand authorization values which are required to invoke the BillDesk Flutter SDK (explained in Step 2):

{
	"mercid": "BDMERCID",
	"amount": "1500",
	"mandate": {
		"mercid": "BDMERCID",
		"end_date": "2028-11-18",
		"amount": "10.00",
		"mandate_tokenid": "NN048F17340196",
		"subscription_desc": "Subscription Pack 1",
		"createdon": "2023-11-18T17:01:09+05:30",
		"frequency": "year",
		"customer_refid": "CUST1700307069350",
		"amount_type": "max",
		"debit_day": "1",
		"subscription_refid": "SubRef1700307069350",
		"currency": "356",
		"recurrence_rule": "after",
		"start_date": "2023-11-18",
		"status": "initiated"
	},
	"ru": "https://www.merchanturl.com/response.jsp",
	"orderid": "BDSDK1700307069350",
	"mandate_required": "Y",
	"createdon": "2023-11-18T17:01:09+05:30",
	"order_date": "2023-11-17T17:01:09+05:30",
	"bdorderid": "OAQE2S18EWI1",
	"additional_info": {
		"additional_info1": "Details1",
		"additional_info2": "Details2"
	},
	"next_step": "redirect",
	"itemcode": "DIRECT",
	"currency": "356",
	"links": [
		{
			"method": "GET",
			"rel": "self",
			"href": "https://www.domainname.com/pgi/ve1_2/orders/BDSDK1700307069350"
		},
		{
			"headers": {
				"authorization": "OToken 6110e0d6570351bf50fb1e6e47ec254c5672b90d7b7a57c78a47b9bbb3d9e7f7dae821fcaf4bac8a1b4f2c9925d65fd268ba2002cdf31369699775e2a7d945824ce68726eeb54a216021187c221a8ca6f4426e6a83c08ddc8a.70675f7061726;aHR0cHM6Ly9hcGkuYmlsbGRlc2suY29t"
			},
			"valid_date": "2023-11-18T17:31:09+05:30",
			"method": "POST",
			"rel": "redirect",
			"href": "https://www.domainname.com/pgi/MerchantPayment/",
			"parameters": {
				"mercid": "BDMERCID",
				"bdorderid": "OAQE2S18EWI1",
				"rdata": "89fd934cf8ca5ad76b8efbcf1d56caf8546a28d5b7876ad0f4070d48fa9b6bc00d3d5c85cda042d681d4593a28dd4ecf19b97c4f15eddff452885653e3f08425d35868fc0b05dd1af21d6eec07364e13b9a3b8f4fd56bdc6983fa732a7ab5267c2708da2b41de3edbb05919787dd5f7c52d17b8e9522e0965164100632eda8575a59483f667255b1c4b0f63bb4ef61d.70675f706172616d5f656e6333"
			}
		}
	],
	"objectid": "order",
	"status": "ACTIVE"
}

B. Only Mandate Setup workflow

A mandate token needs to be created for every mandate setup initiated using the BillDesk Flutter SDK.

To create a mandate, use the Create Mandate Token API with the mandate object. The response of this API provides the mandate_tokenid & authorization values required to launch the BillDesk Flutter SDK (explained Step 2 onwards).

{
	"mercid": "BDMERCID",
	"end_date": "2028-11-19",
	"amount": "10.00",
	"ru": "https://www.merchanturl.com/response.jsp",
	"mandate_tokenid": "NN107717398002",
	"subscription_desc": "Subscription pack",
	"createdon": "2023-11-19T13:23:19+05:30",
	"frequency": "adho",
	"customer_refid": "CUST1700380399174",
	"amount_type": "max",
	"next_step": "redirect",
	"debit_day": "1",
	"subscription_refid": "SubRef1700380399174",
	"currency": "356",
	"recurrence_rule": "after",
	"links": [
		{
			"headers": null,
			"valid_date": null,
			"method": "POST",
			"rel": "self",
			"href": "https://merchantdomain.com/pgsi/v1_2/mandates/token/initiate",
			"parameters": null
		},
		{
			"headers": {
				"authorization": "OToken 842F1738CDE912F0B3C4F6A26FBAD140E370E03B0A9108FBD12B11E223F3096BB510334849E7B21BABF9D0492CE2EB573CBB5CAB232DABE6BD32557EE3BBB119F2FE2F057A81796F195FA874EEE2BB9333DA5FC00475E0B767.70675F70617261;aHR0cHM6Ly9hcGkuYmlsbGRlc2suY29t"
			},
			"valid_date": "2023-11-19T13:53:19+05:30",
			"method": "POST",
			"rel": "redirect",
			"href": "https://www.domainname.com/pgi/MerchantPayment/",
			"parameters": {
				"mercid": "BDMERCID",
				"mandate_tokenid": "NN107717398002",
				"rdata": "89fd934cf8ca5ad76b8efbcf1d56caf8546a28d5b7876ad0f4070d48fa9b6bc00d3d5c85cda042d681d4593a28dd4ecf19b97c4f15eddff452885653e3f08425d35868fc0b05dd1af21d6eec07364e13b9a3b8f4fd56bdc6983fa732a7ab5267c2708da2b41de3edbb05919787dd5f7c52d17b8e9522e0965164100632eda8575a59483f667255b1c4b0f63bb4ef61d.70675f706172616d5f656e6333"
			}
		}
	]
}

3.2: Building the sdkConfig

The sdkConfig acts as a wrapper that encapsulates the necessary configurations and settings required for initializing and configuring the BillDesk Flutter SDK. It serves as the main configuration object for the SDK integration.

sdkConfig(
  	sdkConfigJson: sdkConfigJson,
  	responseHandler: responseHandler,
  	isUATEnv: false
	)

3.3: Building the sdkConfigJson

The sdkConfigJson is a JSON object that represents the configurations that merchant will prepare specific to their integration

final sdkConfigJson = {
      "flowConfig": flowConfig,
      "flowType": "payments",
      "merchantLogo": merchantLogo,
      “themeConfig” = jsonDecode(“
	{
              sdkPrimaryColor: "#69068a",
              sdkAccentColor: "#cf5df5",
              sdkBackgroundColor: "#f2caff",
              sdkBannerColor: "#982cbb"
            }
        “) 
    }

3.4 Building the flowConfig

The flow config is an object which defines how certain aspects of the the SDK will render. It contains:

1. Values received from the Create Order API or Create Mandate Token API (Step 1).
2. Customizations that merchant would like to make on the BillDesk Flutter SDK.

Elements in the flow_config object:

The flow_config object differs for Payments & Mandate Setup workflow or the Mandate Setup workflow. Please refer to the below sections for flow configs for each workflow

A. Payment & Mandate setup workflow

var flow_config = {
	merchantId: "BDMERCID",
	bdOrderId: "TSFFDHWE",
	authToken: "OToken FDD5C104249A4CDAE734623",
	returnUrl: "http://www.demo.com/api/pgresponse",
	retryCount: 3,
	prefs: {
		"payment_categories": ["card", "nb"],
		"allowed_bins": ["459150", "525211"]
	}
}

B. Only Mandate Setup workflow

var flow_config = {
	merchantId: "BDMERCID",
	bdOrderId: "TSFFDHWE",
	authToken: "OToken FDD5C104249A4CDAE734623",
	returnUrl: "http://www.demo.com/api/pgresponse",
	retryCount: 3
}

Step 4: Include the function to launch the SDK

The scripts and configuration objects created in the steps above need to be passed to the function: SdkWebView.openSdkWebView(sdkConfig, context); to launch the BillDesk Flutter SDK.

Step 5: Capture the transaction response

This Step explains the workflow involved the capturing the transaction response once the customer has completed a transaction on the BillDesk Flutter SDK

5.1 : Initialize the SDK Response Handler

The first step in processing the transaction response received from the SDK is to initialize the ResponseHandler. The ResponseHandler is an essential component that handles the responses and errors generated by the SDK during transaction processing.

Sample code for the ResponseHandler:

ResponseHandler responseHandler = SdkResponseHandler(flowType: FlowType.payments);

5.2 : Implement Response Handling Functions

Next, merchant needs to implement two functions within the ResponseHandler class: 1. onTransactionResponse and 2.onError. These functions will be called by the SDK to provide the results of a transaction or report any errors encountered during the process.

TxnInfo Class:
The TxnInfo class represents transaction information and is used to encapsulate the details of a transaction response.

Txn(txnInfoMap='{
  isCancelledByUser: false, 
  orderId: BDSDK1689592751433, 
  merchantId: BDMERCID 
}')

Txn(txnInfoMap='{
  isCancelledByUser: false, 
  customerRrefid:cust9199028201, 
  merchantId: BDMERCID 
}')

Next Steps

Once the Mandate setup is successful, the below 4 APIs are available to Query the status of a Mandate /Refund or Create a Refund.