SpotFlow - iOS SDK Documentation

Overview

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.

Installation

Swift Package Manager

To add SpotFlow - iOS SDK to your project using Swift Package Manager, add the following dependency to your Package.swift file:

dependencies: [
    .package(url: "<https://github.com/spotflow-one/SpotFlow-iOS-SDK.git>", from: "1.0.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: ["SpotFlow-iOS-SDK"]),
]

Usage

Importing the Library

To use SpotFlow - iOS SDK in your SwiftUI view, import the library at the top of your Swift file:

import SpotFlow_iOS_SDK

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

import SwiftUI
import SpotFlow_iOS_SDK

struct ContentView: View {
    @State private var showPaymentScreen = false

    var body: some View {
        VStack {
            Text("Welcome to My App")
                .font(.largeTitle)
                .padding()

            Button("Buy Now") {
                showPaymentScreen = true
            }
            .padding()
            .background(Color.blue)
            .foregroundColor(.white)
            .cornerRadius(8)
        }
        .background(
            NavigationLink(
                destination: SpotFlowPaymentUI(
                    manager: SpotFlowPaymentManager(
                        merchantId: "your_merchant_id",
                        paymentId: "your_payment_id",
                        fromCurrency: "USD",
                        toCurrency: "EUR",
                        amount: 9.99,
                        key: "your_key",
                        provider: "your_provider",
                        customerEmail: "[email protected]",
                        customerName: "John Doe",
                        customerPhoneNumber: "1234567890",
                        customerId: "customer_id",
                        paymentDescription: "Payment for goods",
                        appLogo: Image(systemName: "app.fill"),
                        appName: "My App"
                    ),
                    onPaymentSuccess: {
                        print("Payment successful")
                    },
                    onPaymentFailure: { error in
                        print("Payment failed: \\(error.localizedDescription)")
                    }
                ),
                isActive: $showPaymentScreen,
                label: {
                    EmptyView()
                }
            )
        )
    }
}

SpotFlowPaymentUI Parameters

• manager: An instance of SpotFlowPaymentManager containing payment and customer information.
• onPaymentSuccess: A closure that gets called when the payment is successful.
• onPaymentFailure: 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

• merchantId: The merchant ID (String).
• planId: The plan ID (String).
• fromCurrency: The currency being paid from (String).
• toCurrency: The currency being paid to (String).
• amount: The amount to be paid (Double).
• key: The API key for the payment provider (String).
• customerEmail: The customer's email (String).
• customerName: The customer's name (String, optional).
• customerPhoneNumber: The customer's phone number (String, optional).
• customerId: The customer ID (String, optional).
• paymentDescription: A description of the payment (String, optional).
• appLogo: The logo of the app (Image, optional).
• appName: The name of the app (String, optional).
• encryptionKey: The encrpytion key that will be used to encrypt your card.

Initializer

init(
    merchantId: String,
    paymentId: String,
    fromCurrency: String,
    toCurrency: String,
    amount: Double,
    key: String,
    customerEmail: String,
    customerName: String? = nil,
    customerPhoneNumber: String? = nil,
    customerId: String? = nil,
    paymentDescription: String? = nil,
    appLogo: Image? = nil,
    appName: String? = nil
)

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 allow you to simulate different payment scenarios.

For your convenience, here are the testing helpers available:

• Card Testing: Use the card details provided by your payment provider’s documentation to simulate successful and failed card transactions.
• Bank Transfer Testing: Test bank transfer scenarios with the testing account details provided by your payment provider’s documentation.
• USSD Testing: You can also test USSD transactions using the provided USSD codes and instructions from your payment provider’s documentation.

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.