> ## Documentation Index
> Fetch the complete documentation index at: https://cashfreepayments-d00050e9-theme-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Integration

> Learn more about the sdk integration in your iOS app

### Setting Up 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:

1. Open your project in Xcode.
2. Go to **File > Add Package Dependencies**.
3. Enter the repository URL: [https://github.com/cashfree/core-ios-sdk.git](https://github.com/cashfree/core-ios-sdk.git).
4. Select the version rule (**Recommended:** *Up to Next Major Version*).
5. 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.2.4'`. Install the package using `pod install`.

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

```xml
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>bhim</string>
  <string>paytmmp</string>
  <string>phonepe</string>
  <string>tez</string>
  <string>credpay</string>
</array>
```

### Step 1: Creating an Order

The first step in the Cashfree Payment Gateway integration is to create an Order. You need to do this before any payment can be processed. You can add an endpoint to your server which creates this order and is used for communication with your frontend.

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

You can find the SDKs [here](/api-reference/payments/sdk#payment-sdk).

<CodeGroup>
  ```javascript javascript
  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);
  		});
  }
  ```

  ```python python
  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)
  ```

  ```java java
  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);
    }
  }
  ```

  ```go go
  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)
      }
  }
  ```

  ```csharp csharp
  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);
      }
  }
  ```

  ```php php
  \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;
  }
  ```

  ```bash curl
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2023-08-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"
    }
  }'
    }

  }'
  ```
</CodeGroup>

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](/api-reference/payments/latest/orders/create).

### Step 2: Opening the Payment Page

Web Checkout is a streamlined payment solution that integrates Cashfree's payment gateway into your iOS app through our 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 our SDK, eliminating the need for complex custom implementation.

To complete the payment, we can follow the following steps:

1. Create a CFSession object.
2. Create a Web Checkout Payment object.
3. Set payment callback.
4. 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).

<CodeGroup>
  ```swift swift
  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)
  }
  ```

  ```objective-c objective-c
  @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);
  }
  ```
</CodeGroup>

#### Create a Web Checkout Payment object

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

<CodeGroup>
  ```swift swift
  let webCheckoutPayment = try CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
      .setSession(session)
      .build()
  ```

  ```objective-c objective-c
  @try {
      CFWebCheckoutPaymentBuilder* web = [[CFWebCheckoutPaymentBuilder alloc] init];
      web = [web setSession:session];
      CFWebCheckoutPayment* webPayment = [web buildAndReturnError:nil];
          
  } @catch (NSException *exception) {
      NSLog(@"%@", exception);
  }
  ```
</CodeGroup>

#### Setup callback

You need to set up callback handlers to handle events after payment processing.. The callback implements CFResponseDelegate to handle payment responses and errors. It must be initialized 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

<Tip>Make sure to set the callback at activity's onCreate as this also handles the activity restart cases.</Tip>

<CodeGroup>
  ```swift swift
  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) 
  }
  ```
</CodeGroup>

### Step 3: Sample Code

<CodeGroup>
  ```swift swift
  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)")
    }
  }
  ```

  ```objective-c objective-c
  @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);
  }
  ```
</CodeGroup>

### Step 4: Confirming the Payment

Once the payment is completed, you need to confirm whether the payment was successful by checking the order status. Once the payment finishes, the user will be redirected back to your activity.

<Note>Ensure you check the order status from your server endpoint.</Note>

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```go golang
  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)
  }
  ```

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

  ```php php
  $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;
  }
  ```

  ```java java
  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);
  }
  ```

  ```python python
  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)

  ```

  ```csharp csharp
  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);
  }
  ```

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

### Testing

You should now have a working checkout button that redirects your customer to Cashfree Checkout.

1. Click the checkout button.
2. 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.

<Accordion title="Click to 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                                                                                                                              |
</Accordion>

<div className="callout info">
  ### 💻 Quick dev-to-dev talk

  You clearly care about building better payment experiences for your clients, here's a quick tip: Earn additional income doing exactly what you’re doing now!

  Join the [Cashfree Affiliate Partner Program](https://partner.cashfree.com/partner-ui/authentication/signup?utm_source=dev%20docs\&utm_medium=dev%20doc\&utm_campaign=signup) and get rewarded every time your clients use Cashfree.

  What’s in it for you?

  * Earn up to 0.25% commission on every transaction
  * Be more than a dev - be the trusted fintech partner for your clients
  * Get a dedicated partner manager, your go-to expert

  What’s in it for your clients?

  * Instant activation, go live in minutes.
  * Industry-best success rate across all payment modes.
  * Effortlessly accept international payments in 140+ currencies

  Ready to push to prod? 👉 [Become a Partner now](https://partner.cashfree.com/partner-ui/authentication/signup?utm_source=dev%20docs\&utm_medium=dev%20doc\&utm_campaign=signup)
</div>