Introduction

The BillDesk iOS SDK allows you to seamlessly integrate the BillDesk payment suite with your application and start collecting payments from customers. The BillDesk iOS SDK takes away the complexity of handling and integrating payment stack in a Native android project. The SDK opens the payment page in a webview and completes the payment journey within your 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 your company logo, payment methods as well as themes to give your customers an integrated experience.

Integration Steps

Step 1: Download the BillDesk iOS SDK Libraries

Click here to download the BillDesk iOS SDK library

Note: We currently support iOS versions 12 and above

Step 2: Integrating the BillDesk SDK library

Create an iOS app and an init pod within that app
Add the billdeskpgsdk.framework file shared by BillDesk in your project
Embed and sign this framework in Frameworks, libraries, and Embedded Content Section

Sample screenshot of these configurations

Add the below following configuration in the pod file to include all the libraries

pod 'SwiftyJSON', '~> 5.0'
pod 'SVGKit'
pod "PromiseKit/CorePromise", "~> 6.8"
pod "JOSESwift-AES256GCM",:git => 'https://github.com/tb-bdsk/JOSESwift-AES256GCM.git'

Run the command pod install
Update the all pod library version of Minimum Deployments target to 15.6

Step 3: Preparing the Configurations

3.1 Creating an order

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

To create an order use the Create Order API. The response of this API provides the bdorderIdand authorization & rdata values which are required to launch the BillDesk iOS SDK (explained in the subsequent steps)

Attribute	Description
mercid	Unique identifier provided by BillDesk for each merchant.
bdorderid	Value generated by BillDesk and provided in the Create Order API response. This value is unique for every order which is created.
authorization	An authorization token created by BillDesk and provided in the Create Order API response. This value is unique for every order which is created.

{
	"objectid": "order",
	"orderid": "ORDERID280920230002",
	"bdorderid": "OAZY21S8GXAC",
	"mercid": "BDMERCID",
	"order_date": "2023-09-28T12:25:00+05:30",
	"amount": "2.00",
	"currency": "356",
	"ru": "https://www.merchanturl.com/response.jsp",
	"additional_info": {
		"additional_info1": "Details1",
		"additional_info2": "Details2"
	},
	"itemcode": "DIRECT",
	"createdon": "2023-09-28T12:33:36+05:30",
	"next_step": "redirect",
	"links": [
		{
			"href": "https://www.domainname.com/pgi/ve1_2/orders/ORDERID280920230002",
			"rel": "self",
			"method": "GET"
		},
		{
			"href": "https://www.domainname.com/pgi/MerchantPayment/",
			"rel": "redirect",
			"method": "POST",
			"parameters": {
				"mercid": "BDMERCID",
				"bdorderid": "OAZY21S8GXAC",
				"rdata": "89fd934cf8ca5ad76b8efbcf1d56caf8546a28d5b7876ad0f4070d48fa9b6bc00d3d5c85cda042d681d4593a28dd4ecf19b97c4f15eddff452885653e3f08425d35868fc0b05dd1af21d6eec07364e13b9a3b8f4fd56bdc6983fa732a7ab5267c2708da2b41de3edbb05919787dd5f7c52d17b8e9522e0965164100632eda8575a59483f667255b1c4b0f63bb4ef61d.70675f706172616d5f656e6333"
			},
			"valid_date": "2023-09-28T13:03:36+05:30",
			"headers": {
				"authorization": "OToken 89fd934cf8ca5ad76b8efbcf1d56caf8546a28d5b7876ad0f4070d48fa9b6bc00d3d5c85cda042d681d4593a28dd4ecf19b97c4f15eddff452885653e3f08425d35868fc0b05dd1af21d6eec07364e13b9a3b8f4fd56bdc6983fa732a7ab5267c2708da2b41de3edbb05919787dd5f7c52d17b8e9522e0965164100632eda8575a59483f667255b1c4b0f63bb4ef61d.70675f706172616d5f656e6333"
			}
		}
	],
	"status": "ACTIVE",
	"invoice": {
		"invoice_number": "11221133",
		"invoice_display_number": "11221133",
		"invoice_date": "2023-09-26T12:25:00+05:30",
		"customer_name": "John",
		"gst_details": {
			"cgst": "8.00",
			"sgst": "8.00",
			"igst": "0.00",
			"gst": "16.00",
			"cess": "0.00",
			"gstincentive": "5.00",
			"gstpct": "16.00",
			"gstin": "07AAAAA2194A1A1"
		}
	}
}

💬
Preparing a request payload
Every API request needs to encrypted. Similarly the response of each API is also returned in an encrypted format by BillDesk.
A step by step guide to prepare the request payload, transmit it and capture the response is available here.

💬
Pick and choose your flow
The Create Order API is modular and supports 2 additional workflows as add-on's:

Account Validation Service (AVS): - AVS can be used in case you wish to permit the customer to complete the transaction with a pre-defined account. More details on AVS available here.

Split Settlement: Applicable in case you want the the transaction settlements in multiple accounts. More details on Split Settlement are available here.

Note: If you would like to implement these flows, please contact your BillDesk Relationship Manager prior to initiating the integration.

💬
Validity of an order
Every order created with the Create Order API is valid for a period of 30 minutes. Thus the customer needs to be complete a transaction within this timeframe.

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 Android SDK. It serves as the main configuration object for the SDK integration.

Attribute	Classification	Description
responseHandler	mandatory	JavaScript callback function to receive the transaction's metadata after completion of the transaction journey
flowType	mandatory	Set value as “payments”
flowConfig	mandatory	A JSON object which defines how certain aspects of the the SDK will render
merchantLogo	optional	base64 image of merchant’s logo. For optimal viewing, we recommend maintaining the logo size as 120 (width)*60 pixels(height)

return SdkConfig(
           merchantLogo: Constants.merchantLogoBilldesk,
           flowType: flowType,
           flowConfig: flowConfig,
           responseHandler: CallBackHandler(view: self, flowType: flowType)
       )

3.3: Building the flowConfig

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

Values received from the Create Order API (Step 1).
Customizations which you would like to make on the BillDesk iOS SDK.

Elements in the flow_config object:

Attribute	Classification	Description
merchantId	mandatory	Unique identifier provided by BillDesk for each merchant.
bdOrderid	mandatory	Value generated by BillDesk and provided in the Create Order API Response. This value is unique for every order which is created.
authToken	mandatory	An authorization token created by BillDesk and provided in the Create Order API Response This value is unique for every order which is created.
childWindow	mandatory	Fixed value of `false`
returnUrl	mandatory	The URL where the customer is to be redirected post completion of the payment on the BillDesk Web SDK. BillDesk will also `POST` the transaction response to this URL. Note: *Please ensure that the value of the returnURL is the same as the one passed in the "ru" parameter of the Create Order API. This ensures that the transaction responses for all payment methods are posted on a single URL. HTTPS protocol is mandatory for the "ru"
retryCount	optional	Number of retry attempts you want the customer to be able to get. In case, the earlier attempt to complete the transaction failed, the customer will get an option to retry the payment.
prefs	optional	Changes in the SDK UI based on specific parameters: • payment_categories Payment categories passed here will be displayed in that specific order. Possible values are: ["card", "emi", "nb", "upi", "wallets", "bhim", "gpay"] . In case you do not want a particular payment category which is enabled for you to show on the SDK, you can remove it from payment_categories and it will not show on the SDK. •allowed_bins: Applicable only for cards as a payment method. BIN is the first 6 digits of any card. Multiple BINs can be passed in this attribute. If this value(s) in passed in the prefs object, the customer will be able to make a payment with only that card of that bin. •netBanking object: If this object is passed, the flow config object, there are 2 possible orchestrations: 1. The "showPopularBanks" attribute is : "Y" In this case, you can decide which banks should show as popular banks once the customer clicks on “Net Banking” on the SDK. The list of these banks needs to be passed in the “popularBanks" attribute. The list of these banks needs to be passed in the required order in the popularBanks attribute. Possible values which can be passed here are: Axis Bank [Retail] HDFC Bank [Retail] ICICI Bank [Retail] Kotak Bank State Bank of India 2. The "showPopularBanks" attribute is: "N” In this case, no popular banks will be shown on the SDK and the customers will have to choose a bank from the drop down. Note: Even if a list of banks has been passed in the "popularBanks" attribute in this case, no popular banks will be shown.

var flowConfig: FlowConfig = PaymentsConfig(merchantId: "BDMERCID",
bdOrderId: "TSFFDHWE",
authToken: "OToken FDD5C104249A4CDAE734623",
childWindow: true,
retryAttempt: 3,
showConvenienceFeeDetails: true,
paymentOptions: ["card", "emi", "nb", "gpay"]) ,
netBanking: NetBanking(),
showAllowedBins: "Y",
allowedBins: "459150","400000"
)
class NetBanking {
var showPopularBanks: String? = "Y"
var popularBanks: [String]? = ["Kotak Bank","HDFC Bank","ICICI"]
}

Step 4: Include the function to launch the SDK

To launch the iOS SDK, please invoke the function: SdkManager.startBilldeskFlow(sdkConfig: config, viewController: viewController)

Attribute	Description
viewController	It is of type UIViewController. The merchant needs to pass the reference of viewController to start the SDK’s ViewController
config	It is ok type SdkConfig. Please refer to section 3.2 of this document

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 Android 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.

class CallBackHandler: ResponseHandler {
    private let view: ViewController
    private let flowType: String
    
    init(view: ViewController, flowType: String) {
        self.view = view
        self.flowType = flowType
    }
    
    func onTransactionResponse(txnInfo: TxnInfo) {
        // Capture needed values in local constants
        _ = txnInfo.sdkState
        _ = JSON(rawValue: txnInfo)
 
        print("Callback Received via responseHandler()")
        print("Txn:: \(txnInfo.description)")
 
    }
 
    @MainActor func showUserCanceledAlert(msg: String) {
        let alert = UIAlertController(title: "Transaction Details", message: msg, preferredStyle: UIAlertController.Style.alert)
        let OKAction = UIAlertAction(title: "Ok", style: .default) { (action) in
            exit(0);
        }
        alert.addAction(OKAction)
        view.present(alert, animated: true, completion: nil)
    }
    
    func onError(sdkError: SdkError) {
        print("Callback Received via responseHandler()")
        print("\(sdkError.description)")
    }
}

5.2 : Implement Response Handling Functions

Next, you need 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.

Attribute	Description
ResponseHandler Class	The ResponseHandler class is an interface that defines two methods for handling transaction responses and errors
onTransactionResponse	This method is called when a transaction response is received from BillDesk. It provides the TxnInfo object that contains information about the transaction
onError	This method is called when an error occurs during the transaction process. It provides the `SdkError` object that contains details about the error.

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 
}')

Attribute	Description
isCancelledByUser	Can take the value of either `true` or `false` If this value is `true`, it would mean that the user has cancelled the transaction by clicking on the cancel button on the top right corner of the SDK. In this response, there is no need to query this transaction further for a final status If this value is `false` it would mean that the user has proceeded further along in the transaction journey. In this case, please use the `orderId` parameter and call the Retrieve Transaction API to retrieve the status of the transaction and display it appropriately to the customer.
orderId	Order id passed in the Request of the Create Order API

Attribute

Description

isCancelledByUser

Can take the value of either true or false

If this value is true, it would mean that the user has cancelled the transaction by clicking on the cancel button on the top right corner of the SDK. In this response, there is no need to query this transaction further for a final status
If this value is false it would mean that the user has proceeded further along in the transaction journey. In this case, please use the orderId parameter and call the Retrieve Transaction API to retrieve the status of the transaction and display it appropriately to the customer.

orderId

Order id passed in the Request of the Create Order API

Next Steps

Once the transaction is completed, the below 3 APIs are available to Create a Refund or Query the status of a transaction / refund

💬
Transaction Status Check
You can check the status of a transaction at any point using the Retrieve Transaction API

💬
Refunds
You can initiate a refund for any successful transaction using the Create Refund API

💬
Refund Status Check
You can check the status of a Refund at any point using the Retrieve Refund API

BillDesk iOS SDK

Introduction

Salient Features

Integration Steps

Step 1: Download the BillDesk iOS SDK Libraries

Step 2: Integrating the BillDesk SDK library

Step 3: Preparing the Configurations

3.1 Creating an order

Preparing a request payload

Pick and choose your flow

Validity of an order

3.2: Building the sdkConfig

3.3: Building the flowConfig

Elements in the flow_config object:

Step 4: Include the function to launch the SDK

Step 5: Capture the transaction response

5.1 : Initialize the SDK Response Handler

5.2 : Implement Response Handling Functions

Next Steps

Transaction Status Check

Refunds

Refund Status Check

See Also

Review the associated add- on workflows