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

# Introduction

> The Spotflow iOS SDK is a SwiftUI library that allows developers to integrate payment collection functionality into their iOS applications. It provides a simple interface to navigate to a payment screen, handle payment logic, and manage success or failure callbacks using the `SpotFlowPaymentUI` class.

<Info>The iOS SDK is currently a beta release. If you encounter any issues, kindly reach out to our support team at [support@spotflow.one](mailto:support@spotflow.one).</Info>

## Project Requirements

To integrate the Spotflow iOS SDK into your project, ensure the following prerequisites are met:

* Xcode 13.0 or later
* iOS 11.0 or higher
* Swift 5.3 or later
* Swift Package Manager (SPM) for dependency management

## Installation

### Using Swift Package Manager (SPM)

To add `SpotFlow - iOS` SDK to your project using Xcode or by updating your `Package.swift` file:

```yaml theme={null}
dependencies: [
    .package(url: "https://github.com/Spotflow-One/SpotflowIOS.git", from: "1.0.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: ["Spotflow"]),
]
```

After adding the dependency, import the Spotflow module where needed:

```kotlin wrap theme={null}
import Spotflow
```

### Parameters Required by the SDK

| <p style={{fontWeight: '400'}}>planId<br /><span>`String`</span></p>               | <p style={{fontWeight: '400'}}>The plan ID (optional).</p>                                       |
| :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| <p style={{fontWeight: '400'}}>currency <br /> <span>`String`</span></p>           | <p style={{fontWeight: '400'}}>Currency for the payment (e.g., "NGN").</p>                       |
| <p style={{fontWeight: '400'}}>amount <br /> <span>`String`</span></p>             | <p style={{fontWeight: '400'}}>Amount to be paid (nullable).</p>                                 |
| <p style={{fontWeight: '400'}}>key <br /> <span>`String`</span></p>                | <p style={{fontWeight: '400'}}>The API key for authenticating the transaction.</p>               |
| <p style={{fontWeight: '400'}}>encryptionKey<br /> <span>`String`</span></p>       | <p style={{fontWeight: '400'}}>This key is used to encrypt the card for secure transactions.</p> |
| <p style={{fontWeight: '400'}}>customerEmail<br /> <span>`String`</span></p>       | <p style={{fontWeight: '400'}}>The email address of the customer.</p>                            |
| <p style={{fontWeight: '400'}}>customerName<br /> <span>`String`</span></p>        | <p style={{fontWeight: '400'}}>The name of the customer (optional).</p>                          |
| <p style={{fontWeight: '400'}}>customerPhoneNumber<br /> <span>`String`</span></p> | <p style={{fontWeight: '400'}}>The phone number of the customer (optional).</p>                  |
| <p style={{fontWeight: '400'}}>customerId<br /> <span>`String`</span></p>          | <p style={{fontWeight: '400'}}>The unique identifier for the customer (optional).</p>            |
| <p style={{fontWeight: '400'}}>paymentDescription<br /> <span>`String`</span></p>  | <p style={{fontWeight: '400'}}>Description of the payment (optional).</p>                        |
| <p style={{fontWeight: '400'}}>appLogo<br /> <span>`String`</span></p>             | <p style={{fontWeight: '400'}}>App logo widget (optional).</p>                                   |
| <p style={{fontWeight: '400'}}>appName<br /> <span>`String`</span></p>             | <p style={{fontWeight: '400'}}>The name of the app (optional).</p>                               |
| <p style={{fontWeight: '400'}}>debugMode<br /> <span>`bool`</span></p>             | <p style={{fontWeight: '400'}}>Enable or disable debug mode.</p>                                 |

Never expose your key or encryptionKey directly in the app for production. Use a secure server to perform sensitive operations.

### Navigating to the Payment Screen

To navigate to the payment screen and initiate a payment process, create an instance of `SpotFlowPaymentManager` with the required parameters and pass it to `SpotFlowPaymentUI`.

### Example Usage

```kotlin lines theme={null}
import SwiftUI;
import Spotflow

let config = SpotflowPaymentConfig(
    planId: "plan_001",
    currency: "USD",
    amount: 50.0,
    key: "your_public_key",
    encryptionKey: "your_encryption_key",
    customerEmail: "user@example.com",
    customerName: "Jane Smith",
    customerPhoneNumber: "+123456789",
    customerId: "user_123",
    paymentDescription: "Monthly Subscription",
    appLogo: UIImage(named: "AppLogo"),
    appName: "MyApp",
    debugMode: true
);

Spotflow.shared.startPayment(
    from: self,
    config: config,
    onSuccess: { transactionId, paymentData in
        // Handle success
    },
    onFailure: { errorCode, errorMessage in
        // Handle failure
    }
)
```

## SpotFlowPaymentUI Parameters

<span style={{color: '#81B700'}}>manager</span>: An instance of `SpotFlowPaymentManager` containing payment and customer information.

<span style={{color: '#81B700'}}>onPaymentSuccess</span>: A closure that gets called when the payment is successful.

<span style={{color: '#81B700'}}>onPaymentFailure</span>: A closure that gets called when the payment fails, with an error as a parameter

## SpotFlowPaymentManager

`SpotFlowPaymentManager` is a struct that holds all necessary information for a payment transaction.

### Properties/Parameters

<ParamField path="merchantId" type="string" required>
  The merchant ID
</ParamField>

<ParamField path="planId" type="string" required>
  The plan ID
</ParamField>

<ParamField path="key" type="string" required>
  The API key
</ParamField>

<ParamField path="encryptionKey" type="string" required>
  The Encryption key
</ParamField>

<ParamField path="customerEmail" type="string" required>
  The customer's email
</ParamField>

<ParamField path="customerName" type="string" optional>
  The customer's name
</ParamField>

<ParamField path="customerPhoneNumber" type="string" optional>
  The customer's phone number
</ParamField>

<ParamField path="customerId" type="string" optional>
  The customer ID
</ParamField>

<ParamField path="paymentDescription" type="string" optional>
  paymentDescription
</ParamField>

<ParamField path="appLogo" type="img" optional>
  The logo of the app
</ParamField>

<ParamField path="appName" type="string" optional>
  The name of the app
</ParamField>

## Handling Error Messages

This SDK provides comprehensive error handling mechanisms to assist in troubleshooting and providing informative feedback to users. Upon encountering an error, detailed error codes and descriptions are returned. By extracting error messages from the response, you can effectively communicate the issue to the user and take appropriate actions. Ensure you implement appropriate error handling mechanisms to provide informative feedback to the user.

## Testing

Thoroughly test the integration with different payment scenarios including successful payments, failures, and edge cases to ensure a smooth user experience. Spotflow provides testing helpers that allows you to simulate different payment scenarios

For your convenience, here are the testing helpers available:

* **Card Testing:** Test cards can be found [here](https://app.spotflow.co/)
* **Bank Transfer Testing:** Test bank transfer scenarios with the testing account details provided during your integration.

These testing helpers help you ensure that your integration handles various payment scenarios effectively before deploying your application to a production environment. It's recommended to thoroughly test your integration with these testing details to provide a reliable payment experience to your users.