ForageSDK

The ForageSDK processes Electronic Benefits Transfer (EBT) payments in your e-commerce application. It provides secure user interfaces for collecting and tokenizing an EBT cardholder's PAN and accepting an EBT cardholder's PIN to execute a balance check and process a payment.

Table of contents

• Integration
  • CocoaPods
  • Swift Package Manager
• Usage
  • Create ForageSDK instance
  • Forage UI Elements
  • ForagePANTextField
  • ForagePINTextField
  • Demo Application
• Dependencies

Integration

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate ForageSDK into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'ForageSDK', '~> 0.1.1'

Swift Package Manager

The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.

We recommend using Xcode with Swift tools version 5.3 or higher. Earlier Xcode versions don't support Swift packages with resources. To check your current Swift tools version run in your terminal:

xcrun swift -version

Follow the official Apple SPM guide instructions for more details.

Step-by-step

Add package:

To use Swift Package Manager, in Xcode add the https://github.com/teamforage/forage-ios-sdk dependency and choose the Dependency Rule as Branch and the branch enter main.

Click on Add Package button. And, on the next screen, select the package ForageSDK, and finish by clicking on Add Package.

Usage

Import SDK into your file

import ForageSDK

Create ForageSDK instance

To initialize a ForageSDK instance, you need to provide the environment.

ForageSDK.setup(
    ForageSDK.Config(environment: .sandbox)
)

Forage UI Elements

ForageSDK provides two UI Elements to securely communicate with the Forage API.

ForagePANTextField

A component that securely accepts the PAN number. This field validates the PAN number based on the StateIIN list

private let panNumberTextField: ForagePANTextField = {
    let tf = ForagePANTextField()
    tf.placeholder = "PAN Number"
    return tf
}()

ForagePANTextField uses a delegate ForagePANTextFieldDelegate to communicate the updates to the client side.

panNumberTextField.delegate = self

public protocol ForagePANTextFieldDelegate: AnyObject {
    func panNumberStatus(_ view: UIView, cardStatus: CardStatus)
}

public enum CardStatus: String {
    case valid
    case invalid
    case identifying
}

To send the PAN number, we can use ForageSDK to perform the request.

Tokenize card number

// Signature

func tokenizeEBTCard(
    bearerToken: String,
    merchantAccount: String,
    customerID: String,
    completion: @escaping (Result<PaymentMethodModel, Error>) -> Void
)

// Usage

ForageSDK.shared.tokenizeEBTCard(
    bearerToken: bearerToken,
    merchantAccount: merchantID,
    // NOTE: The following line is for testing purposes only and should not be used in production.
    // Please replace this line with a real hashed customer ID value.
    customerID: UUID.init().uuidString) { result in
        // handle callback here
    }

ForagePINTextField

A component the securely accepts an EBT PIN for balance requests and payment capture. It only accepts 4 digit numbers.

private let pinNumberTextField: ForagePINTextField = {
    let tf = ForagePINTextField()
    tf.placeholder = "PIN Field"
    tf.isSecureTextEntry = true
    tf.pinType = .balance
    return tf
}()

To identify the type of pin we are handling in the component, you can use the pinType property. We have support for these types:

public enum PinType: String {
    case snap
    case nonSnap
    case balance
}

ForagePINTextField uses a delegate ForagePINTextFieldDelegate to communicate the updates to the client side.

pinNumberTextField.delegate = self

public protocol ForagePINTextFieldDelegate: AnyObject {
    func pinStatus(_ view: UIView, isValid: Bool, pinType: PinType)
}

To send the PIN number, we can use the ForageSDK to perform the request.

Balance

// Signature

func checkBalance(
    bearerToken: String,
    merchantAccount: String,
    paymentMethodReference: String,
    foragePinTextEdit: ForagePINTextField,
    completion: @escaping (Result<BalanceModel, Error>) -> Void
)

// Usage

ForageSDK.shared.checkBalance(
    bearerToken: bearerToken,
    merchantAccount: merchantID,
    paymentMethodReference: paymentMethodReference,
    foragePinTextEdit: pinNumberTextField) { result in
        // handle callback here
    }

Capture payment

// Signature

func capturePayment(
    bearerToken: String,
    merchantAccount: String,
    paymentReference: String,
    foragePinTextEdit: ForagePINTextField,
    completion: @escaping (Result<PaymentModel, Error>) -> Void
)

// Usage

ForageSDK.shared.capturePayment(
    bearerToken: bearerToken,
    merchantAccount: merchantID,
    paymentReference: paymentReference,
    foragePinTextEdit: pinNumberTextField) { result in
        // handle callback here
    }

Demo Application

Demo application for using our components on iOS is here.

To get the application running,

1. Clone this repo and open the Sample Project in the Sample folder.
2. Ensure that you have a valid FNS number for the Forage API, which can be found on the dashboard (sandbox | prod).
3. Create a bearer token with pinpad_only scope.
4. Run the Sample app project and provide your FNS number and bearer token on the first screen.
5. These credentials will be passed through to all the SDK calls inside the sample app.

Dependencies

• iOS 10+
• Swift 5
• 3rd party libraries:
  • VGS-Collect-iOS
  • LaunchDarkly