BankPay SDK for iOS Documentation v.1
This SDK allows you to implement ACH payments in your iOS app.
Installing the SDK
Requirements
- Xcode or other iOS development IDE
- Swift 4+
Set up
- Clone the
BankPay_sdk_ios
repository - Open your project in Xcode
- In your
Info.plist
file, you may add the dictionary key ofBankPay-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. - This can be detected by the SDK via the
- 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
.
- When asked, remember to select
- 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.
- Under the Frameworks, Libraries, and Embedded Content section, add the
- 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 asRequired
in the Link Binary with Libraries section.
- Make sure
- 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
(ortest
) 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 astest
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 yourInfo.plist
file.
- The enrollment flow’s key is set via the
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 theBankPay_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 thetype
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
- data : Best formatted to [String:String]
- 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.
-
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
- type :
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 thetype
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
- data : Best formatted to [String:String]
- 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.
-
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
- type :
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 theBankPay_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 thetype
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
- data : Best formatted to [String:String]
- 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.
-
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
- type :
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 thetype
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
- data : Best formatted to [String:String]
- 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.
-
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
- type :
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);
}
}
}