## Zoho Payments Documentation Index Access the complete documentation index at: https://www.zoho.com/in/payments/llms.txt Use this file to discover all available documentation pages before proceeding. # iOS Integration Zoho Payments mobile SDK allows you to integrate directly with your iOS mobile app to collect payments from your customers. **Note:** The minimum deployment iOS version for the ZohoPayments SDK is iOS 15. **Insight:** If you’d like to test your widget integration and payment flows, you can use the Zoho Payments Sandbox environment. Refer to the [Sandbox help doc](https://www.zoho.com/in/payments/developerdocs/sandbox/setup/#iOS-SDK "Sandbox") for more details. To enable, Zoho Payments sandbox [contact support.](https://www.zoho.com/in/payments/contact-us/ "Contact Us") * [Install Zoho Payments SDK](#Import-Zoho-Payments-SDK) * [Integrate Checkout Widget](#Integrate-Checkout-Widget) * [Initialize SDK](#Initialize-SDK) * [Create Payment Session](#Create-payment-session) * [Invoke Checkout Widget](#Invoke-checkout-widget) * [Confirm Payment](#Confirm-payment) * [Verify Payment Status](#verify-status) Here’s the end-to-end iOS integration flow: [![Integrate Zoho Payments Checkout Widget](/in/payments/developerdocs/ios-integration-flow.png)](/in/payments/developerdocs/ios-integration-flow.png) ## 1\. Install Zoho Payments SDK First, you’ll have to add the Zoho Payments SDK to your iOS app to initiate the integration. To install the SDK to your iOS project: 1. Open your project in Xcode. 2. Select your **project.pbxproj file**, go to the _Package Dependencies_ tab, and click **Add Package Dependency.** 3. Enter the URL: [https://github.com/zoho/zpayments-ios-sdk](https://github.com/zoho/zpayments-ios-sdk "SDK URL") in the search bar to fetch the Zoho Payments package. 4. Set the dependency rule to **Exact Version** and specify the latest SDK version, **1.0.2**. This ensures that only the tested and approved version is used. 5. Click **Add Package.** Once added, import `ZohoPayments` into your Swift files to integrate the checkout widget within your app. ## 2\. Integrate Checkout Widget Zoho Payments provides a native iOS SDK for embedding payments into your iOS app using **SwiftUI** and **UIKit.** You can integrate the checkout widget by initializing the SDK and invoking it with the required payment session details. ### 2.1. Initialize SDK First, initialize the SDK using your API key and account ID, and provide a delegate from your app to process the payment results. Initialize SDK Copy ```javascript class PaymentController { var checkout: ZohoPaymentsCheckout? = nil init() { checkout = ZohoPaymentsCheckout(apiKey: Secrets.apiKey, accountId: Secrets.accId, domain: .IN, environment: .live, withCheckoutDelegate: self) } } extension PaymentController: ZohoPaymentsCheckoutDelegate { func onPaymentSuccess(object: ZohoPayments.PaymentSuccessObject) { //Handle Success case } func onPaymentFailure(object: ZohoPayments.PaymentFailureObject) { // Handle Failure case } } ``` Payment Result Object Copy ```javascript public struct PaymentSuccessObject { public var paymentId: String public var mandateId: String? public var signature: String } public struct PaymentFailureObject { public var code: String public var message: String } ``` If you’re facing any errors while processing payments via mobile app, refer to the [error messages](https://www.zoho.com/in/payments/developerdocs/mobile-errors/ "error messages") to identify and resolve the issue. Specify the domain as IN for businesses registered in India. Zoho Payments Domain Copy ```javascript public enum ZohoPayDomain { case IN } ``` Use the sandbox environment for testing, and switch to production when you’re ready to go live. **Insight:** When using sandbox, set `environment` to `.sandbox`. Refer to the [Sandbox iOS developer doc](https://www.zoho.com/in/payments/developerdocs/sandbox/setup/#iOS-SDK "iOS") for more details. Zoho Payments Environment Copy ```javascript public enum ZohoPaymentsEnvironment { case live case sandbox } ``` ### 2.2. Create Payment Session To initiate the payment process, you need to create a payment session on your server. Based on your payment type, you can create the session for one-time or recurring payments. One-Time PaymentsRecurring Payments #### Payment Session for One-time Payments Create a payment session to obtain the `paymentSessionId`. To do this: * Collect the payment details, such as the amount, currency, etc. * Call the [Payment Session Create API.](https://www.zoho.com/in/payments/api/v1/payment-session/#create-payment-session "payment session") The API will return a `paymentSessionId`. Use this ID to invoke the checkout widget and initiate the payment process. #### Create Customer Collect customer details (name, email, phone, and metadata) and call the [Create Customer API.](https://www.zoho.com/in/payments/api/v1/mandates/#create-customer "Create Customer") The API will return a `customer_id`, which you can use to initiate a payment session for mandate enrollment. #### Create Payment Session for Mandate Enrollment Call the [Create Payment Session for Mandate Enrollment API](https://www.zoho.com/in/payments/api/v1/mandates/#create-payment-session-mandate-enrollment "Mandate Enrollment") on your server using an OAuth token to obtain a `payment_session_id.` **Note:** Each session allows up to three payment attempts, but only one can succeed. Any additional attempts return an `invalid_payment_session` response. Use the `payment_session_id` when invoking the checkout widget. ### 2.3. Invoke Checkout Widget Invoke the checkout widget from your app to initiate the payment process. Use the `CheckoutOptions` with your `paymentSessionId` and other parameters such as name, invoice number, and payment method. **UIKit** If you’re using UIKit (Storyboard, XIB, or UIViewController), invoke the checkout widget using the following function: UIKit Copy ```javascript func open(on viewController: UIViewController, with options: CheckoutOptions) ``` **SwiftUI** If you’re using SwiftUI, invoke the checkout widget using the following function: SwiftUI Copy ```javascript func open(with options: CheckoutOptions) ``` The payment parameters for `CheckoutOptions` and the supported payment methods are listed below: **Parameter** **Description** `paymentSessionId` A unique identifier created for each payment session. Learn [how to create a payment session.](https://www.zoho.com/in/payments/api/v1/payment-session/#create-payment-session "payment session") `description` Description of the payment session. The maximum length of the description can be 500 characters. `invoiceNumber` Invoice number of the payment session. The maximum length of the invoice number can be 50 characters. `referenceNumber` Reference number for the payment. `name` Name of the customer. `email` Email address of the customer. `phone` Phone number associated with the customer. `paymentMethod` Type of payment method (e.g., Cards, Net Banking, or UPI). Choose your preferred payment method from the below listed enums to receive payments from customers. Payment Method Copy ```javascript public enum PaymentMethod { case card case netBanking case upi } ``` Request Example Copy ```javascript extension PaymentController { func openCheckout(viewController: UIViewController) { let options = CheckoutOptions(paymentSessionId: "1234567890", description: "description of this payment", invoiceNumber: "Inv_01", referenceNumber: "Ref_01", name: "Patricia Boyle", email: "pboyle@zylker.com", phone: "9898xxxxxx", paymentMethod: .card) // UIKit checkout.open(on: viewController, with: options) // SwiftUI checkout.open(with: options) } } ``` ## 4\. Confirm Payment After payment completion, the SDK returns the `paymentId` and `signature` via the `ZohoPaymentsCheckoutDelegate`. You can confirm the payment on your server and update your system accordingly. **Note:** In some cases, you may not receive the `paymentId` if the customer accidentally closes the widget before a response is returned. In such cases, use your configured webhooks or the `paymentSessionId` to retrieve the payment status. ## 5\. Verify Payment Status You can verify your payment status in three ways: * **Verify via Widget Response:** After receiving the `paymentId`, verify the payment status using the [Payment Retrieve API](/in/payments/api/v1/payments/#retrieve-payment "Retrieve API"). For recurring payments, use the [Retrieve Mandate API](https://www.zoho.com/in/payments/api/v1/mandates/#retrieve-mandate "Retrieve Mandate") to check specific mandates. Based on the status returned (success, failure, or pending), update your system. * **Verify via Webhooks:** Use your [configured webhooks](/in/payments/developerdocs/webhooks/configure/ "configure-webhooks") for the events **payment.success** and **payment.failed** to receive the final payment status directly. * **Verify via Session ID:** Use this method when the payment status is not received through the widget response or webhooks. This can happen in the following scenarios: * The customer closes the payment widget before completion. * The `payment.success` or `payment.failed` webhooks are not configured. * Webhooks are temporarily inactive due to repeated delivery failures. In such cases, retrieve the payment status using the [Payment Session Retrieve API](https://www.zoho.com/in/payments/api/v1/payment-session/#retrieve-payment-session "Session"). This allows you to check the final outcome of the payment using the session ID. **Note:** Ensure that all three options are configured for reliable payment verification. Update your system only after verifying the payment status using any of the methods listed above.