iOS Integration

Payment Gateway iOS Guide

This integration allows you to integrate with a Telr iOS SDK in your app.

Setting Up SDK

CocoaPods

In your pod file add the following line pod 'CashfreePG', '2.2.1' . Ensure you are using the latest version of the SDK (find the versions here). 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.

<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 Telr 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. Telr offers backend SDKs to simplify the integration process. You can find the SDKs here.

import { Cashfree } from "cashfree-pg";

Cashfree.XClientId = {Client ID};
Cashfree.XClientSecret = {Client Secret Key};
Cashfree.XEnvironment = Cashfree.Environment.PRODUCTION;

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("2023-08-01", request).then((response) => {
    var a = response.data;
    console.log(a)
  })
    .catch((error) => {
      console.error('Error setting up order request:', error.response.data);
    });
}

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: Opening the Payment Page

Web Checkout is a streamlined payment solution that integrates Telr’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:

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

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.

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

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

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

Step 3: 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)")
  }
}

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.

Ensure you check the order status from your server endpoint.

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

Testing

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

Click the checkout button.
You’re redirected to the Telr 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.

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

Payments

Payment Gateway

​Payment Gateway iOS Guide

​Setting Up SDK

CocoaPods

​Step 1: Creating an Order

API Request for Creating an Order

​Step 2: Opening the Payment Page

​Create a Session

​Create a Web Checkout Payment object

​Setup callback

​Step 3: Sample Code

​Step 4: Confirming the Payment

​Testing

​Error Codes

Payment Gateway iOS Guide

Setting Up SDK

Step 1: Creating an Order

Step 2: Opening the Payment Page

Create a Session

Create a Web Checkout Payment object

Setup callback

Step 3: Sample Code

Step 4: Confirming the Payment

Testing

Error Codes