iOS

Integrate the Nimbbl iOS SDK with your iOS app and start accepting payments from your customers.

SAMPLE EXPERIENCE

• You can refer to the Nimbbl sample app to learn how the SDK has been integrated.
• Nimbbl iOS Sample App

Compatibilities and Dependencies

1. Your app should target iOS version 13+

Pod Installation

Add the following code to your project pod file:

target 'Target name' do
    pod 'nimbbl_mobile_kit_ios_webview_sdk', '~> 2.0.16'
end

Using the terminal, navigate to your project and run the below command:

pod install

Add URL Schemes

Open Info.plist as a source code. Add the following URL schemes to Info.plist.

<key>LSApplicationQueriesSchemes</key>
 <array>
 <string>gpay</string>
 <string>phonepe</string>
 <string>paytmmp</string>
</array>

Import Nimbbl framework

import nimbbl_mobile_kit_ios_webview_sdk
class ViewController: UIViewController {
}

Implement the Checkout Delegate

import nimbbl_mobile_kit_ios_webview_sdk

class ViewController: UIViewController, NimbblCheckoutSDKDelegate {

    override func viewDidLoad() {
        super.viewDidLoad()

        // Set the delegate
        NimbblCheckoutSDK.shared.delegate = self
    }

    // MARK: - NimbblCheckoutSDKDelegate

    func onCheckoutResponse(data: [AnyHashable: Any]) {
        // Handle payment response
        let status = data["status"] as? String
        let orderId = data["order_id"] as? String
        let transactionId = data["transaction_id"] as? String

        switch status?.lowercased() {
        case "success":
            print("Payment successful: \(data)")
            // Handle success
        case "failed":
            print("Payment failed: \(data)")
            // Handle failure
        case "cancelled":
            print("Payment cancelled: \(data)")
            // Handle cancellation
        default:
            print("Payment response: \(data)")
        }
    }
}

Invoke the Checkout

IMPORTANT

In order to invoke the checkout, your server should provide you the following information:

• orderToken - this would have been generated from your server.

Understanding Checkout Options

Nimbbl lets you enforce a payment mode on the Checkout. This can be done by passing the paymentModeCode property. There are other related properties for each different payment mode, you can read them in the table below. If you don't pass paymentModeCode the customer is shown the full Checkout with all available payment modes.

Properties	Type	Mandatory?	Description
orderToken	string	true	Order token generated via Creating an Order step
paymentModeCode	string	false	In case of specific payment mode, this property is mandatory. Possible values net_banking, card, upi, wallet. If you don't pass paymentModeCode the customer is shown the full Checkout with all available payment modes.
bankCode	string	false	Only to be passed in case of net_banking. Example: hdfc. To get the full list of banks supported for you, please use this API. If it isn't passed, Checkout will open with a page for the user to choose their bank from enabled banks
walletCode	string	false	Only to be passed in case of wallet. Example: jio_money. To get the full list of wallets supported for you, please use this API. If it isn't passed, Checkout will open with a page for the user to choose their wallet from enabled wallets
paymentFlow	string	false	Only to be passed in case of upi to determine the flow. Possible value is intent. If it isn't passed, Checkout will open with page for the user to pay using a QR or choose a UPI app
upiAppCode	string	false	Only to be passed in case of upi and paymentFlow is intent. Possible values phonepe, gpay. Checkout will open with the transaction initiated for the upi app passed in the upiAppCode field. If it isn't passed, Checkout will show a UPI QR or prompt user to choose a UPI app

Process Payment

func startCheckout(orderToken: String) {
    // Only orderToken is required, other parameters can be nil
    let options = NimbblCheckoutOptions(
        orderToken: orderToken,
        paymentModeCode: nil, // Optional: 'net_banking', 'card', 'upi', 'wallet' or nil for all
        bankCode: nil,        // Optional: Only for 'net_banking'. Bank code for specific bank
        walletCode: nil,      // Optional: Only for 'wallet'. Wallet code for specific wallet
        paymentFlow: nil,     // Optional: Only for 'upi' 'intent'
        upiAppCode: nil       // Optional: Only for 'upi' with paymentFlow 'intent'. 'phonepe' or 'gpay'
    )

    // Start checkout on main thread
    DispatchQueue.main.async {
        NimbblCheckoutSDK.shared.checkout(from: self, options: options)
    }
}

Note: displayController is the ViewController on which you want to present the checkout screen

Capture Transaction Response

The onCheckoutResponse callback provides a comprehensive response object containing:

Field	Type	Description
status	String	Payment status: "success", "failed", "cancelled"
order_id	String	Your order ID
nimbbl_order_id	String	Nimbbl's internal order ID
transaction_id	String	Transaction ID
nimbbl_transaction_id	String	Nimbbl's internal transaction ID
signature	String	Payment signature for verification
message	String	Status message
reason	String	Failure reason (if applicable)
order	Object	Complete order details including amount, currency, etc.

Example Response

{
  "status": "success",
  "order_id": "order_12345",
  "nimbbl_order_id": "order_RoQ7Zl92G2qqB3rg",
  "transaction_id": "txn_67890",
  "nimbbl_transaction_id": "order_RoQ7Zl92G2qqB3rg-20210217071936",
  "signature": "hmac_sha256",
  "message": "Payment successful",
  "order": {
    "amount": 100.0,
    "currency": "INR",
    "invoice_id": "inv_123"
  }
}

IMPORTANT

• Share the response parameters received to your server
• This will need to be validated on your server before you decide to provide goods or services
• More details available on processing the response in Completing the Integration

Migration Guide for SDK v2.x.x

If you're upgrading from SDK version 1.x.x or earlier, follow this migration guide:

1. Update Dependencies

Before (v1.x.x)

pod 'nimbbl_mobile_kit_ios_webview_sdk', '~> 1.0.12'

After (v2.x.x)

pod 'nimbbl_mobile_kit_ios_webview_sdk', '~> 2.0.4'

2. Update Delegate Implementation

Before (v1.x.x)

class ViewController: UIViewController, NimbblCheckoutSDKDelegate {
    func onPaymentSuccess(_ response: [AnyHashable: Any]) {
        // Handle success
    }

    func onError(_ error: [AnyHashable: Any]) {
        // Handle error
    }
}

After (v2.x.x)

class ViewController: UIViewController, NimbblCheckoutSDKDelegate {
    func onCheckoutResponse(data: [AnyHashable: Any]) {
        let status = data["status"] as? String
        switch status?.lowercased() {
        case "success":
            // Handle success
        case "failed":
            // Handle failure
        case "cancelled":
            // Handle cancellation
        default:
            // Handle other cases
        }
    }
}

3. Breaking Changes

1. Delegate Methods: The onPaymentSuccess and onError methods have been replaced with a single onCheckoutResponse method.

4. Testing Your Migration

1. Update your Podfile with the new SDK version
2. Run pod install
3. Update your delegate implementation
4. Test the integration thoroughly in your development environment

Migration Note

Make sure to test your integration thoroughly after migration. The new SDK version includes enhanced error handling and improved response structure.

For SDK Version 1.x.x and Earlier

If you're using SDK version 1.x.x or earlier and want to continue with the existing implementation, follow the instructions below:

Installation for v1.x.x

pod 'nimbbl_mobile_kit_ios_webview_sdk', '~> 1.0.12'

Delegate Implementation for v1.x.x

class ViewController: UIViewController, NimbblCheckoutSDKDelegate {
    func onPaymentSuccess(_ response: [AnyHashable: Any]) {
        // Handle payment success
    }

    func onError(_ error: [AnyHashable: Any]) {
        // Handle payment error
    }
}

Legacy Support Note

SDK version 1.x.x is maintained for backward compatibility but will not receive new features or major updates. We recommend upgrading to v2.x.x for the latest features, security updates, and improved performance.

Related Reading

Creating an OrderRequired server-side configurationStandard Checkout OverviewIntegration overviewSonic Product OverviewWhat customers see