iOS Payment SDK | Cashfree Payments

Cashfree’s iOS SDK provides a streamlined payment solution that integrates the payment gateway into your iOS applications through a WebView-based checkout implementation, supporting iOS deployment target 11 and above.

Key benefits

The iOS SDK offers the following advantages for your payment integration:

Simplified integration: Provides a pre-built SDK that delivers an optimised payment experience for iOS applications.
Secure and compliant: Securely handles payment processing with built-in security measures managed by the SDK.
Multiple integration methods: Supports both Swift Package Manager (recommended) and CocoaPods for easy installation.

Prerequisites

Ensure you complete the following tasks before starting the integration:

Create a Cashfree Merchant Account.
Log in to the Merchant Dashboard and generate an App ID and Secret Key. Learn how to generate API keys.

The iOS integration consists of three essential steps:

Step 1

Create an order

Step 2

Open the payment page

Step 3

Confirm the payment

The step-by-step guide for each step of the integration process is as follows:

Step 1: Create an order Server-side

To integrate the Cashfree Payment Gateway, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You can’t call this API from the client-side.

Create orders through your server as this API requires your secret key. Don’t call it directly from your mobile application.

API request for creating an order

Here’s a sample request for creating an order using your desired backend language. Cashfree offers backend SDKs to simplify the integration process.

import { Cashfree, CFEnvironment } from "cashfree-pg";

const cashfree = new Cashfree(
	CFEnvironment.PRODUCTION,
	"{Client ID}",
	"{Client Secret Key}"
);

function createOrder() {
	var request = {
		order_amount: "1",
		order_currency: "INR",
		customer_details: {
			customer_id: "node_sdk_test",
			customer_name: "",
			customer_email: "example@gmail.com",
			customer_phone: "9999999999",
		},
		order_meta: {
			return_url:
				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
		},
		order_note: "",
	};

	cashfree
		.PGCreateOrder(request)
		.then((response) => {
			var a = response.data;
			console.log(a);
		})
		.catch((error) => {
			console.error("Error setting up order request:", error.response.data);
		});
}

from cashfree_pg.models.create_order_request import CreateOrderRequest
from cashfree_pg.api_client import Cashfree
from cashfree_pg.models.customer_details import CustomerDetails


Cashfree.XClientId = {Client ID}
Cashfree.XClientSecret = {Client Secret Key}
Cashfree.XEnvironment = Cashfree.XSandbox
x_api_version = "2023-08-01"

def create_order():
        customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
        createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
        try:
            api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
            print(api_response.data)
        except Exception as e:
            print(e)

import com.cashfree.*;

Cashfree.XClientId = {Client Key};
Cashfree.XClientSecret = {Client Secret Key};
Cashfree.XEnvironment = Cashfree.SANDBOX;

static void createOrder() {
  CustomerDetails customerDetails = new CustomerDetails();
  customerDetails.setCustomerId("123");
  customerDetails.setCustomerPhone("9999999999");

  CreateOrderRequest request = new CreateOrderRequest();
  request.setOrderAmount(1.0);
  request.setOrderCurrency("INR");
  request.setCustomerDetails(customerDetails);
  try {
    Cashfree cashfree = new Cashfree();
    ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
    System.out.println(response.getData().getOrderId());

  } catch (ApiException e) {
    throw new RuntimeException(e);
  }
}

import (
  cashfree "github.com/cashfree/cashfree-pg/v3"
)

func createOrder() {

clientId := {Client ID}
clientSecret := {Client Secret Key}
cashfree.XClientId = &clientId
cashfree.XClientSecret = &clientSecret
cashfree.XEnvironment = cashfree.SANDBOX

request := cashfree.CreateOrderRequest{
		OrderAmount: 1,
		CustomerDetails: cashfree.CustomerDetails{
			CustomerId:    "1",
			CustomerPhone: "9999999999",
		},
		OrderCurrency: "INR",
		OrderSplits:   []cashfree.VendorSplit{},
	}
	version := "2023-08-01"
	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
	if err != nil {
		fmt.Println(err.Error())
	} else {
		fmt.Println(httpResponse.StatusCode)
		fmt.Println(response)
    }
}

using cashfree_pg.Client;
using cashfree_pg.Model;

Cashfree.XClientId = {Client ID};
Cashfree.XClientSecret = {Client Secret Key};
Cashfree.XEnvironment = Cashfree.PRODUCTION;
var cashfree = new Cashfree();
var xApiVersion = "2023-08-01";

void CreateOrder() {
    var customerDetails = new CustomerDetails("123", null, "9999999999");
    var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
    try {
        // Create Order
        var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
        Console.WriteLine(result);
        Console.WriteLine(result.StatusCode);
        Console.WriteLine((result.Content as OrderEntity));
    } catch (ApiException e) {
        Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
        Console.WriteLine("Status Code: " + e.ErrorCode);
        Console.WriteLine(e.StackTrace);
    }
}

\Cashfree\Cashfree::$XClientId = "<x-client-id>";
\Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
\Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

$cashfree = new \Cashfree\Cashfree();

$x_api_version = "2023-08-01";
$create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
$create_orders_request->setOrderAmount(1.0);
$create_orders_request->setOrderCurrency("INR");
$customer_details = new \Cashfree\Model\CustomerDetails();
$customer_details->setCustomerId("123");
$customer_details->setCustomerPhone("9999999999");
$create_orders_request->setCustomerDetails($customer_details);

try {
    $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
}

curl --location 'https://sandbox.cashfree.com/pg/orders' \
--header 'X-Client-Secret: {{clientKey}}' \
--header 'X-Client-Id: {{clientId}}' \
--header 'x-api-version: 2025-01-01' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "order_amount": 10.10,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "USER123",
    "customer_name": "joe",
    "customer_email": "joe.s@cashfree.com",
    "customer_phone": "+919876543210"
  },
  "order_meta": {
    "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
  }
}'
  }

}'

After successfully creating an order, you will receive a unique order_id and payment_session_id that you need for subsequent steps. You can view all the complete API request and response for /orders here.

Step 2: Open the payment page Client-side

Web Checkout is a streamlined payment solution that integrates Cashfree’s payment gateway into your iOS app through the SDK. This implementation uses a WebView to provide a secure, feature-rich payment experience. Your customers are presented with a familiar web interface where they can enter their payment details and complete their transaction seamlessly. All payment logic, UI components, and security measures are managed by the SDK, eliminating the need for complex custom implementation.

1. Set up the SDK

Swift Package Manager (recommended)

The recommended way to integrate the Cashfree iOS SDK is by using Swift Package Manager. You can do this through the Xcode interface. To add the Cashfree iOS SDK to your project, follow these steps:

Open your project in Xcode.
Go to File > Add Package Dependencies.
Enter the repository address: https://github.com/cashfree/core-ios-sdk.git.
Select the version rule (Recommended: Up to Next Major Version).
Choose the products you need:
- CashfreePG—Complete Payment Gateway SDK (recommended)
- CashfreePGCoreSDK—Core payment processing
- CashfreePGUISDK—UI components
- CashfreeAnalyticsSDK—Analytics and tracking
- CFNetworkSDK—Networking layer

CocoaPods

In your pod file add the following line pod 'CashfreePG', '2.4.0'. Install the package using pod install.

iOS configuration

To provide UPI payments on iOS you need to enable the following permissions in your app. Open the info.plist file and add the below content:

<key>LSApplicationQueriesSchemes</key>

</array>
		<string>amazonpay</string>
		<string>upi</string>
		<string>credpay</string>
		<string>bhim</string>
		<string>paytmmp</string>
		<string>phonepe</string>
		<string>tez</string>
		<string>navipay</string>
		<string>mobikwik</string>
		<string>myairtel</string>
		<string>popclubapp</string>
		<string>super</string>
		<string>kiwi</string>
    <string>simplypayupi</string>
    <string>whatsapp</string>
</array>

2. Complete the payment

To complete the payment, follow these steps:

Create a CFSession object.
Create a Web Checkout Payment object.
Set payment callback.
Initiate the payment using the payment object created.

Create a session

This object contains essential information about the order, including the payment session ID (payment_session_id) and order ID (order_id) obtained from Step 1. It also specifies the environment (sandbox or production).

do {
    let session = try CFSession.CFSessionBuilder()
        .setOrderID(order_id)
        .setPaymentSessionId(payment_session_id)
        .setEnvironment(Utils.environment)
        .build()
      return session;
} catch let e {
    let error = e as! CashfreeError
    self.createAlert(title: "Warning", message: error.localizedDescription)
}

@try {
    CFSessionBuilder* sessionBuilder = [[CFSessionBuilder alloc] init];
    sessionBuilder = [sessionBuilder setPaymentSessionId:paymentSessionId];
    sessionBuilder = [sessionBuilder setOrderID:orderId];
    sessionBuilder = [sessionBuilder setEnvironment:CFENVIRONMENTPRODUCTION];
    CFSession* session = [sessionBuilder buildAndReturnError:nil];
        
} @catch (NSException *exception) {
    NSLog(@"%@", exception);
}

Create a web checkout payment object

Use CFWebCheckoutPayment to create the payment object. This object accepts a CFSession, like the one created in the previous step.

let webCheckoutPayment = try CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
    .setSession(session)
    .build()

@try {
    CFWebCheckoutPaymentBuilder* web = [[CFWebCheckoutPaymentBuilder alloc] init];
    web = [web setSession:session];
    CFWebCheckoutPayment* webPayment = [web buildAndReturnError:nil];
        
} @catch (NSException *exception) {
    NSLog(@"%@", exception);
}

Setup callback

Set up callback handlers to handle events after payment processing. The callback implements CFResponseDelegate to handle payment responses and errors. Initialise it in viewDidLoad by calling CFPaymentGatewayService.getInstance().setCallback(self).

onError: Handles payment failures by displaying an alert with error details
verifyPayment: Called when payment needs merchant verification, shows status alert to user

Make sure to set the callback at activity’s onCreate as this also handles the activity restart cases.

extension ViewController: CFResponseDelegate {
        
    func onError(_ error: CFErrorResponse, order_id: String) {
        self.createAlert(title: error.status ?? "ERROR", message: error.message ?? "error_message_not_present")
    }
    
    func verifyPayment(order_id: String) {
        self.createAlert(title: "VERIFY PAYMENT", message: "Payment has to be verified by merchant for \(order_id)")
    }
        
}

// Class Variable
let pgService = CFPaymentGatewayService.getInstance()

override func viewDidLoad() {
   super.viewDidLoad()
   pgService.setCallback(self) 
}

Sample code

import CashfreeAnalyticsSDK
import CashfreePG
import CashfreePGCoreSDK
import CashfreePGUISDK

class ViewController: UIViewController, CFResponseDelegate {

  // Class Variable
  let pgService = CFPaymentGatewayService.getInstance()

  override func viewDidLoad() {
    super.viewDidLoad()
    pgService.setCallback(self)
  }

  @IBAction func webCheckoutButtonTapped(_ sender: Any) {
    do {
      let session = try CFSession.CFSessionBuilder()
        .setPaymentSessionId(payment_session_id)
        .setOrderID(order_id)
        .setEnvironment(Utils.environment)
        .build()
      let webCheckoutPayment = try CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
        .setSession(session)
        .build()
      try pgService.doPayment(webCheckoutPayment, viewController: self)
    } catch let e {
      let err = e as! CashfreeError
      print(err.description)
    }

  }

  // Protocol Implementation
  func onError(_ error: CFErrorResponse, order_id: String) {
    self.createAlert(
      title: error.status ?? "ERROR", message: error.message ?? "error_message_not_present")
  }

  func verifyPayment(order_id: String) {
    self.createAlert(
      title: "VERIFY PAYMENT", message: "Payment has to be verified by merchant for \(order_id)")
  }
}

@try {
    CFSessionBuilder* sessionBuilder = [[CFSessionBuilder alloc] init];
    sessionBuilder = [sessionBuilder setPaymentSessionId:paymentSessionId];
    sessionBuilder = [sessionBuilder setOrderID:orderId];
    sessionBuilder = [sessionBuilder setEnvironment:CFENVIRONMENTPRODUCTION];
    CFSession* session = [sessionBuilder buildAndReturnError:nil];
    
    CFWebCheckoutPaymentBuilder* web = [[CFWebCheckoutPaymentBuilder alloc] init];
    web = [web setSession:session];
    CFWebCheckoutPayment* webPayment = [web buildAndReturnError:nil];
    
    CFPaymentGatewayService* pg = [CFPaymentGatewayService alloc];
    [pg setCallback:self];
    [pg doPayment:webPayment viewController:self error:nil];
        
} @catch (NSException *exception) {
    NSLog(@"%@", exception);
}

Step 3: Confirm the payment Server-side

After the customer completes the payment, you must confirm the payment status. Once the payment finishes, the user redirects back to your activity. To verify an order you can call our /pg/orders endpoint from your backend. You can also use our SDK to achieve the same.

version := "2023-08-01"
response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
if err != nil {
	fmt.Println(err.Error())
} else {
	fmt.Println(httpResponse.StatusCode)
	fmt.Println(response)
}

cashfree
	.PGFetchOrder("<order_id>")
	.then((response) => {
		console.log("Order fetched successfully:", response.data);
	})
	.catch((error) => {
		console.error("Error:", error.response.data.message);
	});

$x_api_version = "2023-08-01";
try {
    $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
    print_r($response);
} catch (Exception $e) {
    echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
}

import com.cashfree.*;
//other code

try {
    Cashfree.XClientId = "<x-client-id>";
    Cashfree.XClientSecret = "<x-client-secret>";
    Cashfree.XEnvironment = Cashfree.SANDBOX;

    Cashfree cashfree = new Cashfree();
    String xApiVersion = "2023-08-01";

    ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
    System.out.println(response.getData().getOrderId());
} catch (ApiException e) {
    throw new RuntimeException(e);
}

from cashfree_pg.models.create_order_request import CreateOrderRequest
from cashfree_pg.api_client import Cashfree
from cashfree_pg.models.customer_details import CustomerDetails
from cashfree_pg.models.order_meta import OrderMeta

Cashfree.XClientId = "<x-client-id>"
Cashfree.XClientSecret = "<x-client-secret>"
Cashfree.XEnvironment = Cashfree.SANDBOX
x_api_version = "2023-08-01"

try:
    api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
    print(api_response.data)
except Exception as e:
    print(e)

using cashfree_pg.Client;
using cashfree_pg.Model;

Cashfree.XClientId = "<x-client-id>";
Cashfree.XClientSecret = "<x-client-secret>";
Cashfree.XEnvironment = Cashfree.SANDBOX;
var cashfree = new Cashfree();
var xApiVersion = "2023-08-01";

try {
    var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
    Console.WriteLine(result);
    Console.WriteLine(result.StatusCode);
    Console.WriteLine((result.Content as OrderEntity));
} catch (ApiException e) {
    Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
    Console.WriteLine("Status Code: " + e.ErrorCode);
    Console.WriteLine(e.StackTrace);
}

curl --request GET \
     --url https://sandbox.cashfree.com/pg/orders/{order_id} \
     --header 'accept: application/json' \
     --header 'x-api-version: 2025-01-01'
     --header 'x-client-id: "YOUR APP ID GOES HERE"'
     --header 'x-client-secret: "YOUR SECRET KEY GOES HERE'

Always verify the order status before you deliver services to the customer. You can use the Get Order API for this. An order is successful when the order_status is PAID.

Testing

After you integrate the checkout functionality, verify that it opens the Cashfree-hosted payment page. Follow these steps to test:

Click the checkout button.
Verify you’re redirected to the Cashfree Checkout payment page.

Error codes

To confirm the error returned in your iOS application, you can view the error codes that are exposed by the SDK.

Show error codes

CashfreeError is an Enum that inherits Foundations Error class. The following are some of the error codes that are exposed by the SDK:

Error codes	Message
MISSING_CALLBACK	The callback is missing in the request.
ORDER_ID_MISSING	The “order_id” is missing in the request.
CARD_EMI_TENURE_MISSING	The “emi_tenure” is missing or invalid (It has to be greater than 0).
INVALID_UPI_APP_ID_SENT	The id sent is invalid. The value has to be one of the following: “tez://”,“phonepe://”,“paytmmp://”,“bhim://. Please refer the note in CFUPI class for more details
INVALID_PAYMENT_OBJECT_SENT	The payment object that is set does not match any payment mode. Please set the correct payment mode and try again.
WALLET_OBJECT_MISSING	The CFWallet object is missing in the request
NETBANKING_OBJECT_MISSING	The CFNetbanking object is missing in the request.
UPI_OBJECT_MISSING	The CFUPI object is missing in the request.
CARD_OBJECT_MISSING	The CFCard object is missing in the request.
INVALID_WEB_DATA	The url seems to be corrupt. Please reinstantiate the order.
SESSION_OBJECT_MISSING	The “session” is missing in the request
PAYMENT_OBJECT_MISSING	The “payment” is missing in the request
ENVIRONMENT_MISSING	The “environment” is missing in the request.
ORDER_TOKEN_MISSING	The “order_token” is missing in the request.
CHANNEL_MISSING	The “channel” is missing in the request.
CARD_NUMBER_MISSING	The “card_number” is missing in the request.
CARD_EXPIRY_MONTH_MISSING	The “card_expiry_mm” is missing in the request.
CARD_EXPIRY_YEAR_MISSING	The “card_expiry_yy” is missing in the request.
CARD_CVV_MISSING	The “card_cvv” is missing in the request.
UPI_ID_MISSING	The “upi_id” is missing in the request
WALLET_CHANNEL_MISSING	The “channel” is missing in the wallet payment request
WALLET_PHONE_MISSING	The “phone number” is missing in the wallet payment request
NB_BANK_CODE_MISSING	The “bank_code” is missing in the request

Affiliate partner program

As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.

Join the Cashfree affiliate partner program and get rewarded every time your clients use Cashfree.

What you get:

Earn up to 0.25% commission on every transaction.
Become a trusted fintech partner for your clients.
Access to a dedicated partner manager for expert support.

What your clients get:

Instant activation and go live in minutes.
Industry-best success rate across all payment modes.
Effortless acceptance of international payments in 140+ currencies.

Get started today. Become a partner now.

​Key benefits

​Prerequisites

Step 1

Step 2

Step 3

​Step 1: Create an order Server-side

API request for creating an order

​Step 2: Open the payment page Client-side

​1. Set up the SDK

Swift Package Manager (recommended)

CocoaPods

iOS configuration

​2. Complete the payment

​Create a session

​Create a web checkout payment object

​Setup callback

​Sample code

​Step 3: Confirm the payment Server-side

​Testing

​Error codes

Key benefits

Prerequisites

Step 1: Create an order Server-side

Step 2: Open the payment page Client-side

1. Set up the SDK

2. Complete the payment

Create a session

Create a web checkout payment object

Setup callback

Sample code

Step 3: Confirm the payment Server-side

Testing

Error codes