#iOS integration with your own payment gateway

Setu provides ready to use URLs for iOS integration. Contact Setu to update your logo, colours, fonts as per your branding. You can reach out to billpay.support@setu.co for any further clarifications. This quickstart page provides the sample code for the following specs—

• Programming language — Swift 5.* (Latest version 5.3)
• Interface — Storyboard
• Life Cycle delegation — UI Kit
• iOS versions supported — 12+ (Latest version 14.4)

#Step 1 — Implement web view in your app

The following steps need to be taken for webview integration—

1. Get link from the backend
2. Open the link in WKWebView and attach a userContentController
3. Execute payment flow and redirect back to the WKWebView on success/failure

Get link from the backend

This step gives a one time Setu URL to be used by your customer for the bill fetch or payment flow. The Create link API needs to be called when Android app wants to obtain a one time link to load Setu’s screen flow inside a webview.

You can have the following scenarios—

• If no other input is passed, it will take the user to the home page with all BBPS categories.
• If category code is passed, it will show user a list of billers in that category.
• If category code and biller ID is passed, it will show the bill fetch form where a customer can enter their identifers (biller specified parameters)
• If the category code, biller ID and parameters are passed, it will show the bill directly.

The above request will return URL based on the input params. Here’s a sample—

{
  "link": "https://billpay-qa.setu.co/1238993883748223",
  "sessionId": "1238993883748223",
  "success": true,
  "traceId": "GHSUU99128DBVU"
}

Switch control from your app to Setu

The link returned by the API should be loaded within WKWebView in a ViewController which implements UIViewController, and WKScriptMessageHandler. The controller must also extend and use a custom WKNavigationDelegate class to intercept and download PDF files.

The userContentController will need to implement two functions—

• initiate_payment — Used to initiate payment and transfer control from webview to iOS application
• unload — Used by the parent app to dismiss the webview

// The iOS observer function
func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
    guard let dict = message.body as ? [String: AnyObject]
    else {
        return
    }
    let functionToPerform: String = dict["function"] as ? String ?? ""
    
    switch functionToPerform {
        case "initiate_payment":
        let successLink = dict["data"]?["callback"] as! String
        let remarks = dict["data"]?["remarks"] as! String
        let billAmount = dict["data"]?["amount"] as! String
        let orderID = dict["data"]?["orderId"] as! String
        let beneficiaryVPA = dict["data"]?["beneficiaryVPA"] as! String
        let mobileNumber = dict["data"]?["mobileNumber"] as! String
        let refId = dict["data"]?["refId"] as! String
        let customerId = dict["data"]?["customerId"] as! String
        let allowedPaymentModes = dict["data"]?["allowedPaymentModes"] as! String
        
        let vc = PaymentViewController(
          successLink: successLink + successParams,
          remarks: remarks,
          billAmount: billAmount,
          orderID: orderID,
          beneficiaryVPA: beneficiaryVPA,
          mobileNumber: mobileNumber,
          refId: refId,
          customerId: customerId,
          allowedPaymentModes: allowedPaymentModes
        )
        
        let navVC = UINavigationController(rootViewController: vc)
        present(navVC, animated: true)
        case "unload": closeView()
        default: break
    }
}

The WKWebviewDownloadHelper which downloads our PDF file is used as below

override func viewDidLoad() {
  super.viewDidLoad()
  let mimeTypes = [MimeType(type: "pdf", fileExtension: "pdf")]
  helper = WKWebviewDownloadHelper(webView: webView, mimeTypes: mimeTypes, delegate: self)
  webView.configuration.userContentController.add(self, name: "ios_observer")
}

WKWebviewDownloadHelper is dependent on the custom WKNavigationDelegate class

extension WebViewController: WKWebViewDownloadHelperDelegate {
  func fileDownloadedAtURL(url: URL) {
    DispatchQueue.main.async {
      let activityVC = UIActivityViewController(activityItems: [url], applicationActivities: nil)
      activityVC.popoverPresentationController?.sourceView = self.view
      activityVC.popoverPresentationController?.sourceRect = self.view.frame
      activityVC.popoverPresentationController?.barButtonItem = self.navigationItem.rightBarButtonItem
      self.present(activityVC, animated: true, completion: nil)
    }
  }
}

Handle payment flow

The initiate_payment case in the the userContentController takes the following parameters

• orderId on the Setu COU System. It always starts with COUWL. Example— COUWLZ7pFtTgr9LtO
• amount to be paid by the customer. Example — 3522.20
• callback URL which needs to be loaded in the webview once the payment is completed. Example — https://billpay.setu.co/payment-callback/68c7217b-8fa7-4c1f-8e5f-317ff3027668
• beneficiaryVPA to which amount is to be transferred—this is relevant only if you can transfer in real time using UPI rails.
• remarks used to communicate information between mobile app and webview.
• mobileNumber mobile number used for the session. Example - 9876543210
• refId BBPS reference ID linked to a particular bill (only available for fetch billers). Example - CMA0I65RCU2I32C3L0H0KNYQYAG40021831
• customerId linked to a particular session. Example - cust@1234
• allowedPaymentModes comma separated list of modes allowed for this payment. One of these should be sent in the paymentMode in the payment confirmation webhook.

When initiate_payment case is called by the webview, your app needs to do the following-

1. Remove the webview
2. Initiate the payment flow
3. Send Setu the webhook event for payment—this need not be done for UPI transfers in real time
4. Once payment is executed, load the webview again with the callback URL

#Step 2 — Optionally configure webhook

You may optionally want to listen to user events—like successful or failed bill fetch, bill payment status and more—through webhooks. Refer to this guide for more information.

#Step 3 — Get Production credentials and go live

Once you are done testing your integration, ensure that all KYC and legal agreements are submitted. Contact Setu for getting enabled on production.