Installing the SDK

Requirements

• Xcode or other iOS development IDE
• Swift 4+

Set up

1. Clone the BankPay_sdk_ios repository
2. Open your project in Xcode
3. In your Info.plist file, you may add the dictionary key of BankPay-publishableKey with your designated value.
   • This can be detected by the SDK via the BankPay_setPublicKey method.
     • Alternatively, you can pass the method a nameless string parameter with the publishable key as its content.
   Note: The publishable key allows you the appropriate access for using the SDK.
4. Open the repository’s root directory and drag the BankPay-sdk-ios.xcodeproj into Xcode on to the root of your project’s .xcodeproj file in the Project Navigator tab.
   • When asked, remember to select Copy items if needed.
5. Select your project via the Project Navigator tab, and view the General settings tab of the appropriate
   build target for your project.
   • Under the Frameworks, Libraries, and Embedded Content section, add the BankPay_sdk_ios.framework file to the list.
6. Move to the Build Phases tab
   • Make sure BankPay_sdk_ios.framework is also listed in the Embed Frameworks section, the Dependencies section, and set as Required in the Link Binary with Libraries section.
7. Now you should be able to call import BankPay_sdk_ios in your project’s Swift files to use the SDK’s functionalities.

Return value reference

Type: bankAccountAdded
Data:

• intent_id string
  Permanent unique identifier of the enrollment intent.

Type: enrollmentError
Data:

• error string
  The error code. (Example: declined)
• message string
  The error message. (Example: According to our records, this financial institution does not permit ACH transactions.)

Type: acceptedTransactionIntentServiceFee
Data:

• transactionIntentId string
  Permanent unique identifier of the transaction intent.

Type: close
Data:

• No data

Using the SDK

In a .swift file in your project, you can simply import the SDK. From this point, you have access to the SDKs methods & functionalities.

• import BankPay_sdk_ios

Methods

BankPay has the following methods available to you.

BankPay_setVersionAPI

You can set the API version to the cce server or the production server.

• The cce (or test) server is useful for your environments where you do not expect to be using real client or customer data. It is for testing.
• The production server is for your final customer-facing environment.

Parameters

Takes a string of either cce or production;

• The default is production;
• cce can alternatively be called as test

BankPay_setPublishableKey

Parameters

This function takes an optional nameless string parameter.

• If the parameter is passed
  • The enrollment flow’s key is set with the parameter’s value.
  • This is best for the case when you have multiple keys you are attempting to use for your application.
• If the parameter is not passed
  • The enrollment flow’s key is set via the BankPay-publishableKey key-value pair that you would need to add in your Info.plist file.

BankPay_setEnrollmentIntentToken

This method sets an intent token for the enrollment flow to start accepting an intent.

Parameters

token (nameless)

This is the intent token created by your server to be passed and confirmed via the BankPay SDK.

Type:

• String

BankPay_startEnrollment

This method initiates an enrollment intent flow that allows a user to securely enroll their bank account.

Note: If you are presented with an error about simultaneous presentations, you may benefit from a more manual approach by using the BankPay_linkEnrollmentFlow method covered below instead.

Parameters

onSuccess()

This is a method that is called by this SDK multiple times during the enrollment flow. At each Update Point of the enrollment flow, it is passed a Dictionary ([String:Any]) of data you can use to continue and complete your own application’s enrollment flow.

Note: Make checks in this function for the type value from the data return you will be receiving. That way you know when to close the SDK view or take other actions. Examples can be seen in the Usage Examples section

Type:

• Method that receives a Dictionary as a parameter, returns nothing.
• ([String:Any]) -> Void

Update Points:

• Intent Redemption
  • This is the first response returned from the SDK’s enrollment flow. It passes back intent token data that must be redeemed by your server for usage.
    • Redemption is required before continuing the enrollment flow successfully.
    • Redemption should be handled by your organization’s server.
  • Key Return Values:
    • data : Best formatted to [String:String]
      • intent_id
    • type : bankAccountAdded
      • Best formatted to String
• Completion
  • This is the second response returned from the SDK’s enrollment flow. It passes back the indicator that the view may be closed.
  • Key Return Values:
    • type : close
      • Best formatted to String

onError()

This is a method that is called after an erroneous completion of the enrollment flow of this SDK. It is passed a Dictionary ([String:Any]) of data you can use to continue and complete your own application’s enrollment flow.

Type:

• Method that receives a Dictionary as a parameter, returns nothing.
• ([String:Any]) -> Void

Key Return Values:

• errors : Best formatted to [String:Any]
• error : Best formatted to String
• message : Best formatted to String

BankPay_endEnrollment

This method closes the view that the BankPay_startEnrollment method initiates. This method is not automatically called upon completion of the SDK’s enrollment flow. It requires your application to call it when appropriate in your user flow. We recommend calling it within the onSuccess & onError method that the BankPay_linkEnrollmentFlow method receives as its parameter.

BankPay_linkEnrollmentFlow

This method returns a ViewController that you can link to and update your own views with when executing the SDK’s enrollment flow;

Parameters

onSuccess()

This is a method that is called by this SDK multiple times during the enrollment flow. At each Update Point of the enrollment flow, it is passed a Dictionary ([String:Any]) of data you can use to continue and complete your own application’s enrollment flow.

Note: Make checks in this function for the type value from the data return you will be receiving. That way you know when to close the SDK view or take other actions. Examples can be seen in the Usage Examples section

Type:

• Method that receives a Dictionary as a parameter, returns nothing.
• ([String:Any]) -> Void

Update Points:

• Intent Redemption
  • This is the first response returned from the SDK’s enrollment flow. It passes back intent token data that must be redeemed by your server for usage.
    • Redemption is required before continuing the enrollment flow successfully.
    • Redemption should be handled by your organization’s server.
  • Key Return Values:
    • data : Best formatted to [String:String]
      • intent_id
    • type : bankAccountAdded
      • Best formatted to String
• Completion
  • This is the second response returned from the SDK’s enrollment flow. It passes back the indicator that the view may be closed.
  • Key Return Values:
    • type : close
      • Best formatted to String

onError()

This is a method that is called after an erroneous completion of the enrollment flow of this SDK. It is passed a Dictionary ([String:Any]) of data you can use to continue and complete your own application’s payment flow.

Type:

• Method that receives a Dictionary as a parameter, returns nothing.
• ([String:Any]) -> Void

Key Return Values:

• errors : Best formatted to [String:Any]
• error : Best formatted to String
• message : Best formatted to String

BankPay_setTransactionIntentToken

This method sets an intent token for the transaction flow to start accepting an intent.

Parameters

token (nameless)

This is the intent token created by your server to be passed and confirmed via the BankPay SDK.

Type:

• String

BankPay_startTransaction

This method initiates a transaction intent flow that allows a user to securely complete a transaction.

Note: If you are presented with an error about simultaneous presentations, you may benefit from a more manual approach by using the BankPay_startTransactionLink method covered below instead.

Parameters

onSuccess()

This is a method that is called by this SDK multiple times during the transaction flow. At each Update Point of the transaction flow, it is passed a Dictionary ([String:Any]) of data you can use to continue and complete your own application’s payment flow.

Note: Make checks in this function for the type value from the data return you will be receiving. That way you know when to close the SDK view or take other actions. Examples can be seen in the Usage Examples section

Type:

• Method that receives a Dictionary as a parameter, returns nothing.
• ([String:Any]) -> Void

Update Points:

• Intent Redemption
  • This is the first response returned from the SDK’s transaction flow. It passes back intent token data that must be redeemed for usage by your servers.
    • Redemption is required before continuing the transaction flow successfully.
    • Redemption should be handled by your organization’s server.
  • Key Return Values:
    • data : Best formatted to [String:String]
      • transactionIntentId
    • type : acceptedTransactionIntentServiceFee
      • Best formatted to String
• Completion
  • This is the second response returned from the SDK’s transaction flow. It passes back the indicator that the view may be closed.
  • Key Return Values:
    • type : close
      • Best formatted to String

onError()

This is a method that is called after an erroneous completion of the transaction flow of this SDK. It is passed a Dictionary ([String:Any]) of data you can use to continue and complete your own application’s payment flow.

Type:

• Method that receives a Dictionary as a parameter, returns nothing.
• ([String:Any]) -> Void

Key Return Values:

• errors : Best formatted to [String:Any]
• error : Best formatted to String
• message : Best formatted to String

BankPay_endTransaction

This method closes the view that the BankPay_startTransaction method initiates. This method is not automatically called upon completion of the SDK’s transaction flow. It requires your application to call it when appropriate in your user flow. We recommend calling it within the onSuccess & onError method that the BankPay_linkTransactionFlow method receives as its parameter.

BankPay_linkTransactionFlow

This method returns a ViewController that you can link to and update your own views with when executing the SDK’s transaction flow;

Parameters

onSuccess()

This is a method that is called by this SDK multiple times during the transaction flow. At each Update Point of the transaction flow, it is passed a Dictionary ([String:Any]) of data you can use to continue and complete your own application’s payment flow.

Note: Make checks in this function for the type value from the data return you will be receiving. That way you know when to close the SDK view or take other actions. Examples can be seen in the Usage Examples section

Type:

• Method that receives a Dictionary as a parameter, returns nothing.
• ([String:Any]) -> Void

Update Points:

• Intent Redemption
  • This is the first response returned from the SDK’s transaction flow. It passes back intent token data that must be redeemed for usage by your servers.
    • Redemption is required before continuing the transaction flow successfully.
    • Redemption should be handled by your organization’s server.
  • Key Return Values:
    • data : Best formatted to [String:String]
      • transactionIntentId
    • type : acceptedTransactionIntentServiceFee
      • Best formatted to String
• Completion
  • This is the second response returned from the SDK’s transaction flow. It passes back the indicator that the view may be closed.
  • Key Return Values:
    • type : close
      • Best formatted to String

onError()

This is a method that is called after an erroneous completion of the transaction flow of this SDK. It is passed a Dictionary ([String:Any]) of data you can use to continue and complete your own application’s payment flow.

Type:

• Method that receives a Dictionary as a parameter, returns nothing.
• ([String:Any]) -> Void

Key Return Values:

• errors : Best formatted to [String:Any]
• error : Best formatted to String
• message : Best formatted to String

Using the SDK

Enrollment Flow

Via BankPay_startEnrollment

import UIKit;
import BankPay_sdk_ios;

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad();

        // Sets publishable key via a string
        BankPay_setPublishableKey("FAKE-PUBLISHABLE-KEY");

        BankPay_setEnrollmentIntentToken("FAKE-INTENT-TOKEN");

        // Present the enrollment flow
        BankPay_startEnrollment(onSuccess: getData);
    }

    //  Success callback for the SDK to return your data
    func getData(response: [String:Any]?) {
        if ((response?.keys.contains("type") ?? false) && response!["type"] as! String == "bankAccountAdded") {
            //  Redeem intent API call to your internal server
        } else if ((response?.keys.contains("type") ?? false) && response!["type"] as! String == "close") {
            //  Dismiss the enrollment flow when you're done with it
            BankPay_endEnrollment();
        }
    }
}

Via BankPay_linkEnrollmentFlow

import UIKit;
import BankPay_sdk_ios;

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad();

        //  Sets publishable key from the Info.plist
        BankPay_setPublishableKey();

        BankPay_setEnrollmentIntentToken("FAKE-INTENT-TOKEN");

        //  Link the enrollment flow to your view
        let ACHCtrl = BankPay_linkEnrollmentFlow(onSuccess: getData);
        addChild(ACHCtrl);
        view.addSubview(ACHCtrl.view);
        ACHCtrl.view.frame = view.bounds;
        ACHCtrl.view.autoresizingMask = [.flexibleWidth, .flexibleHeight];
        ACHCtrl.didMove(toParent: self);
        ACHCtrl.view.isHidden = false;
    }

    //  Success callback for the SDK to return your data
    func getData(response: [String:Any]?) {
        if ((response?.keys.contains("type") ?? false) && response!["type"] as! String == "bankAccountAdded") {
            //  Redeem intent API call to your internal server
        } else if ((response?.keys.contains("type") ?? false) && response!["type"] as! String == "close") {
            //  Dismiss this view when you're done with it
            dismiss(animated: true, completion: nil);
        }
    }
}

Transaction Flow

Via BankPay_startTransaction

import UIKit;
import BankPay_sdk_ios;

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad();

        //  Sets publishable key via a string
        BankPay_setPublishableKey("FAKE-PUBLISHABLE-KEY");

        BankPay_setIntentToken("FAKE-INTENT-TOKEN");

        //  Present the transaction flow
        BankPay_startTransaction(onSuccess: getData);
    }

    //  Success callback for the SDK to return your data
    func getData(response: [String:Any]?) {
        if ((response?.keys.contains("type") ?? false) && response!["type"] as! String == "acceptedTransactionIntentServiceFee") {
            //  Redeem intent API call to your internal server
        } else if ((response?.keys.contains("type") ?? false) && response!["type"] as! String == "close") {
            //  Dismiss the transaction flow when you're done with it
            BankPay_endTransaction();
        }
    }
}

Via BankPay_linkTransactionFlow

import UIKit;
import BankPay_sdk_ios;

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad();

        //  Sets publishable key from the Info.plist
        BankPay_setPublishableKey();

        BankPay_setIntentToken("FAKE-INTENT-TOKEN");

        //  Link the transaction flow to your view
        let ACHCtrl = BankPay_linkTransactionFlow(onSuccess: getData);
        addChild(ACHCtrl);
        view.addSubview(ACHCtrl.view);
        ACHCtrl.view.frame = view.bounds;
        ACHCtrl.view.autoresizingMask = [.flexibleWidth, .flexibleHeight];
        ACHCtrl.didMove(toParent: self);
        ACHCtrl.view.isHidden = false;
    }

    //  Success callback for the SDK to return your data
    func getData(response: [String:Any]?) {
        if ((response?.keys.contains("type") ?? false) && response!["type"] as! String == "acceptedTransactionIntentServiceFee") {
            //  Redeem intent API call to your internal server
        } else if ((response?.keys.contains("type") ?? false) && response!["type"] as! String == "close") {
            //  Dismiss this view when you're done with it
            dismiss(animated: true, completion: nil);
        }
    }
}