> ## Documentation Index
> Fetch the complete documentation index at: https://developer.novacpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS

> Install and use the Novac iOS SDK with minimal setup config.

## Overview

The Novac iOS SDK allows you to easily collect payments within your iOS apps using Novac's secure checkout experience. It provides APIs for payment initialization and verification, along with a built-in UI that handles the full checkout flow for you.

***

### Prerequisites

<Accordion title="See details" defaultOpen={true}>
  Before you begin, ensure that you've completed the following steps:

  * [Obtain your API keys](/docs/getting-started/obtain-api-keys): required for making authenticated API calls.
  * Xcode project with Swift Package Manager support
  * A Novac account with dashboard access
</Accordion>

### Installation

<Steps>
  <Step title="Step 1 - Add the Package in Xcode">
    In Xcode, navigate to **File → Add Packages…**, select **Add Local…**, and choose your SDK folder (`Novac/`). Then add **Novac** to your app target's dependencies.

    If your SDK is hosted on GitHub, you can add it directly via URL instead of a local folder:

    ```swift theme={null}
        .package(url: "https://github.com/yourusername/Novac.git", from: "1.0.0")
    ```
  </Step>
</Steps>

***

## Initialize the SDK

Before launching any payment, you need to set up two things: an `APIClient` (which authenticates your requests using your API key) and a `PaymentCoordinator` (which manages the entire checkout flow). Both are configured inside your `ViewController`.

You'll need your `apiKey` from the Novac dashboard. The optional `CustomTheme` lets you style the checkout UI to match your brand.

```swift theme={null}
import UIKit
import Novac

class ViewController: UIViewController, PaymentDelegate {

    var coordinator: PaymentCoordinator!

    override func viewDidLoad() {
        super.viewDidLoad()

        let apiClient = APIClient(apiKey: "YOUR_TEST_API_KEY")
        let theme = CustomTheme(primaryColor: .systemBlue, buttonTextColor: .white)

        coordinator = PaymentCoordinator(
            apiClient: apiClient,
            theme: theme,
            delegate: self
        )
    }
}
```

***

### Launch the Checkout Flow

Once the coordinator is set up, you can trigger a payment from any user action — in this case, a button tap. You create a `PaymentRequest` with the transaction details and pass it to the coordinator, which handles the rest.

```swift theme={null}
@IBAction func startPayment(_ sender: UIButton) {
    let payment = PaymentRequest(
        amount: 5000,
        currency: "NGN",
        email: "test@example.com",
        reference: UUID().uuidString
    )
    coordinator.start(presentingViewController: self, request: payment)
}
```

***

### Handle Payment Outcomes

The `PaymentDelegate` protocol defines three callback methods that the SDK calls depending on what happens during checkout. Implement all three in your `ViewController` to handle every possible outcome.

```swift theme={null}
func paymentDidSucceed(transactionId: String) {
    print("Payment succeeded with ID: \(transactionId)")
    // Update your UI, confirm the order, etc.
}

func paymentDidFail(error: Error) {
    print("Payment failed: \(error.localizedDescription)")
    // Show error message, offer retry option, etc.
}

func paymentDidCancel() {
    print("Payment cancelled by user.")
    // Handle cancellation gracefully
}
```

***

### Configure Redirect URL

After a user completes checkout in the SDK's webview, the payment gateway redirects them back to your app using a URL scheme. You need to register this scheme in your `Info.plist` so iOS knows to route that redirect back to your app.

```xml theme={null}
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>exampleapp</string>
    </array>
  </dict>
</array>
```

Replace `exampleapp` with your own unique scheme. This value must match whatever redirect URL is configured in your Novac dashboard.

## Advanced Usage

<Info>
  Ensure you use your Novac test key during development.
</Info>

Keep the following in mind when testing:

* Always use a unique `reference` value for each transaction, duplicate references will be rejected.
* Start with small test amounts (₦100) to validate your integration before going live.
* Check your sandbox dashboard to confirm transaction results and inspect any errors.