Getting Started

Use our library to integrate the Cashfree Payment Gateway directly into your app using CFWebSDK for iOS 10 and above. CFWebSDK has been designed to offload the complexity of handling and integrating payments in your app. The Dynamic Framework uses Swift 4 compiler. The SDK runs only on physical iOS devices.

The CFWebSDK is available at a publicly hosted github repo as a Dynamic Framework.

We provide two types of integration for iOS

  1. Webview Checkout - Customer does payment in Cashfree’s web payment page inside a Webview in your app.
  2. Seamless Pro - Customer does payment in your App directly and the request is sent to cashfree backend. A Webview is launched for the Two-factor/Authorization process.

Framework with Bitcode

Below are the latest iOS SDK download links :-

ENABLE_BITCODE should be set to YES
Xcode Version Swift Version Framework Download Link
10 4.2 Download SDK

Proceed to next step.


Set up your Project

Adding iosCashfreeSDK

  1. Drag and drop the contents of CFWebSdk-BitcodeEnabled.zip onto your Xcode project navigator. Click the check box for Copy items if needed. Click Finish.

  2. Then click the + button on Embedded Binaries under the General tab of your ios app project file.

  3. Select CFWebSdk.framework. Click Finish.


Webview Checkout

Step 1

Add the Swift code to your project’s ViewController. In this code, we are importing the iOS SDK. Then we setup variables for the parameters required for creating the order. You can pass paymentOption value empty in case you want to show all available payment methods in the Cashfree payment page.

The variable paymentReady must be the token generated using our Token Generation endpoint. You must use the Struct Result to retrieve the transaction response after user completes payment.


import CFWebSdk //Before the class

class ViewController: UIViewController {    
    // MARK: CONFIG
    let environment = "TEST" // Use "PROD" when you are ready to go live.
    let appId = "YOUR_APP_ID"
    let color1Hex = "#6a5594ff"
    let merchantName = "MERCHANT_NAME"
    let notifyUrl = "HTTPS_NOTIFY_URL"
    
    let orderId = "Z-123-0004"
    let orderAmount = "120.00"
    let customerEmail = "customeremail@address.com"
    let customerPhone = "9876543210"
    let orderNote = "This is a test note"
    let customerName = "Firstname Lastname"
    
    // Available values: cc, dc, nb, paypal, wallet. Leave it blank if you want to display all modes
    let paymentOption = ""
    
    var paymentReady = "CFTOKEN_VALUE"
    var source_config = "iossdk" // MUST be "iossdk"

    // This is Struct for the result
    struct Result : Codable {
        let orderId: String
        let referenceId: String
        let orderAmount: String
        let txStatus: String
        let txMsg: String
        let txTime: String
        let paymentMode: String
        let signature: String
        
        enum CodingKeys : String, CodingKey {
            case orderId
            case referenceId
            case orderAmount
            case txStatus
            case txMsg
            case txTime
            case paymentMode
            case signature
        }
    }
  }

Step 2

Initialise your app’s View Controller (viewDidLoad) with below Swift code. You must use CFViewController() only if you want the user to do payment in a Webview with Cashfree’s payment page.

Set the environment and appId. environment can be either be TEST or PROD. Enter your appid (To get the appId login to Cashfree Merchant Dashboard.)


  super.viewDidLoad()
  
  let CF = CFViewController();  
  CF.setConfig(env: "TEST", appId: appId)

Step 3

To capture all the order details such as orderId, orderAmount etc you need to embed this code (In a button IBAction). This will help us capture the order request.

This code makes a request to the SDK’s createOrder function with the required parameters that you have declared in Step 1.

To define the Navigation across the screens you can use the Navigation Controller. To set it, Select your View Controller in Storyboard and click Edit menu. Then click Embed in Navigation Controller. Then we push the Cashfree View Controller to show the webview.


  let CF = CFViewController()
        
  if paymentReady != "" {
      CF.createOrder(orderId: orderId, orderAmount: orderAmount, customerEmail: customerEmail, customerPhone: customerPhone, paymentReady: paymentReady, orderNote: orderNote, customerName: customerName, notifyUrl: notifyUrl, paymentOption: paymentOption)
      
      self.navigationController?.pushViewController(CF, animated: true)
  } else {
      print("paymentReady is empty")
  }

Step 4

To capture the transaction result add the below swift code to your app’s View Controller (viewDidAppear)


override func viewDidAppear(_ animated: Bool) {
  let paymentVC = CFViewController()

  let transactionResult = paymentVC.getResult()
  let inputJSON = "\(transactionResult)"
  
  let inputData = inputJSON.data(using: .utf8)!
  
  let decoder = JSONDecoder()
  
  if inputJSON != "" {
      
      do {
          let result2 = try decoder.decode(Result.self, from: inputData)
          print(result2.orderId)
          print(result2)
      } catch {
          // handle exception
          print("BDEBUG: Error Occured while retrieving transaction response")
      }
  } else {
      print("BDEBUG: transactionResult is empty")
  }
}

Seamless Pro

In a Seamless Pro payment flow, the customer enters all details on merchant app checkout view itself( Cashfree is whitelabled in such a scenario). Once the customer has entered all details related to the payment mode , the request opens in a webview showing the service provider (eg OTP page in case of card payment).

The CFWebSDK Dynamic Framework provides a view controller named SeamlessProVC. This can be used to pass payment information directly to Cashfree’s backend (without showing Cashfree checkout page).

The Seamless Pro integration requires PCI Certification. Once you have PCI certification, please email us to activate Seamless Pro in your Merchant account.

We will review your PCI complaince status, If it is valid, we will send you a confirmation mail.

Set the environment & appId

On getting the confirmation mail regarding meeting of PCI compliance, you need to set the environment and appId.

environment can be either be TEST or PROD. Enter your appid (To get the appId login to Cashfree Merchant Dashboard.)

override func viewDidLoad() {
    super.viewDidLoad()
    // Use below SeamlessProVC only if you have Seamless Pro enabled at Cashfree
	let CF = SeamlessProVC();    
    CF.setConfig(env: environment, appId: appId)
}

Payment request

To capture all the order details such as orderId, orderAmount etc you need to embed this code. This will help us capture the order request at the backend.

@IBAction func SeamlessProBtn(_ sender: Any) {    
    let CF = SeamlessProVC()
    let paymentParams = [
        "orderId": "ORDER-1230",
        "orderAmount": "124",
        "customerName": "John Doe",
        "orderNote": "Example order note",
        "customerPhone": "9876543210",
        "customerEmail": "johndoe@email.com",
        "paymentOption": "", // Available values: card, nb, wallet, upi
        "notifyUrl": notifyUrl,
        "source": source_config,
        "card_number": "",//If you don't pass these values then it will not be sent in the request.
        "card_holder": "",
        "card_expiryMonth": "",
        "card_expiryYear": "",
        "card_cvv": "",
        "paymentCode": "", // Required if using paymentOption nb or wallet. Eg: "3333" for nb Test Bank. "4001" or "4002" for Wallet.
        "upi_vpa": "", // Required if you are using paymentOption "upi". For testing use this test vpa - "testsuccess@gocash"
        "upiMode": "", //Required if you need to use googlepay use "gpay"
        "paymentReady": "CFTOKEN-VALUE"
    ]
    
    CF.createOrderParams(paymentParams: paymentParams)
    self.navigationController?.pushViewController(CF, animated: true)
}

Token Generation

You will need to generate a token and pass it to SDK while initiating payments for security reasons. For generating token you need to use our token generation API. Please take care that this API is called only from your backend as it uses secretKey which should never be sent to frontend.

For production/live usage set the endpoint will be:

https://api.cashfree.com/api/v2/cftoken/order

For testing the endpoint will be:

https://test.cashfree.com/api/v2/cftoken/order

You need to send order details (orderId, orderCurrency and orderAmount) as a JSON object to the API endpoint and in response a token will received. Please see the description of request below


Request Description

curl -XPOST -H 'Content-Type: application/json' 
-H 'x-client-id: <YOUR_APP_ID>' 
-H 'x-client-secret: <YOUR_SECRET_KEY>' 
-d '{
  "orderId": "<ORDER_ID>",
  "orderAmount":<ORDER_AMOUNT>,
  "orderCurrency": "INR"
}' 'https://test.cashfree.com/api/v2/cftoken/order'


Request Example

curl -XPOST -H 'Content-Type: application/json' -H 'x-client-id: 275432e3853bd165afbf5272' -H 'x-client-secret: 2279c0ffb9550ad0f9e0652741c8d06a49409517' -d '{
  "orderId": "Order0001",
  "orderAmount":1,
  "orderCurrency":"INR"
}' 'https://test.cashfree.com/api/v2/cftoken/order'


Response Example

{
"status": "OK",
"message": "Token generated",
"cftoken": "v79JCN4MzUIJiOicGbhJCLiQ1VKJiOiAXe0Jye.s79BTM0AjNwUDN1EjOiAHelJCLiIlTJJiOik3YuVmcyV3QyVGZy9mIsEjOiQnb19WbBJXZkJ3biwiIxADMwIXZkJ3TiojIklkclRmcvJye.K3NKICVS5DcEzXm2VQUO_ZagtWMIKKXzYOqPZ4x0r2P_N3-PRu2mowm-8UXoyqAgsG"
}

The “cftoken” attribute is the token that needs to be used to secure your request. We will cover in next step

Parameters

Parameter Required Description
appId Yes Your app id
orderId Yes Order/Invoice Id
orderAmount Yes Bill amount of the order
orderCurrency No Currency for the order. INR if left empty. See the Currency Codes below for a list of available currencies.Please contact care@gocashfree.com to enable new currencies.
orderNote No A help text to make customers know more about the order
customerName Yes Name of the customer
customerPhone Yes Phone number of customer
customerEmail Yes Email id of the customer
notifyUrl No Notification URL for server-server communication. Useful when user’s connection drops while
paymentModes No Allowed payment modes for this order. Available values: cc, dc, nb, paypal, wallet. Leave it blank if you want to display all modes

Response parameters, shared with callback functions

These parameters are returned to the functions you implement using paymentVC.getResult() (see Step 4). transactionResult contains the details of the transaction.

Parameter Description
orderId Order id for which transaction has been processed. Ex: GZ-212
orderAmount Amount of the order. Ex: 256.00
referenceId Cashfree generated unique transaction Id. Ex: 140388038803
txStatus Payment status for that order. Values can be : SUCCESS, FLAGGED, PENDING, FAILED, CANCELLED.
paymentMode Payment mode used by customer to make the payment. Ex: DEBIT_CARD, MobiKwik, etc
txMsg Message related to the transaction. Will have the reason, if payment failed
txTime Time of the transaction

Running your App

The CFWebSDK Dynamic Framework works on iOS 10 and 11.

If you are any facing issues with the integration, please send us an email or reach us on the Chat on our homepage

Test Credentials

Parameter Required Description
Card Number Yes 4111111111111111
Card Holder Yes Test
Expiry Month Yes 10
Expiry Year Yes 22
CVV/CVC Yes 123