Payments SDK for iOS

The Payments SDK is a solution to ease the integration with the Alviere services.

Features

  • Payment Methods Management
  • Account Wallet
  • Check Deposit

Requirements

  • iOS 13.0+
  • Xcode 15+
  • Swift 5.5+

Installation

Swift Package Manager

1. Add the dependency to your project. Open your project and navigate to your project’s settings. Select the tab named Swift Packages and click on the add button + at the bottom left.

image

2. Enter the url of Payments SDK for the iOS repository (https://github.com/Alviere/alviere-payments-ios) in the text field and click Next.

image

3. On the next screen, select the SDK version and click Next.

image

4. Select the Payments package and click Finish.

image

5. Repeat the same process for AlCore SDK (https://github.com/Alviere/alviere-core-ios). The current version is compatible with AlCore SDK version 0.9.0 and up.

CocoaPods

1. Get the latest version of CocoaPods, if you haven’t already.

2. Create the Podfile by running the following command, if you don’t have one already.

pod init

3. Add this line to your Podfile.

pod 'Payments'

4. Run the following command to install the library. Also, run this to update to newer releases in the future.

pod install

Carthage

1. Get the latest version of Carthage, if you haven’t already.

2. Add the following entries in your Cartfile:

binary https://raw.githubusercontent.com/Alviere/alviere-core-ios/master/AlCore.json
binary https://raw.githubusercontent.com/Alviere/alviere-payments-ios/master/Payments.json

3. Run the following command to download the latest version of the SDK.

carthage update --use-xcframeworks

4. Follow the Manual instructions below to embed the SDK into your project.

Manual

1. Get the latest versions of Payments.xcframework and AlCore.xcframework and embed them into your application by dragging and dropping the files onto the Frameworks, Libraries and Embedded Content project section, as shown below.

image

2. Depending on the location of Payments.xcframework and AlCore.xcframework on the filesystem you may need to change the Framework Search Paths build setting to avoid the error: fatal error: ‘Payments/Payments.h’ file not found. For example, the Xcode project below have it set to FRAMEWORK_SEARCH_PATHS = $(PROJECT_DIR)/../ since the xcframeworks files are shared between them and are kept in the directory that also contains the project directories.

image

Usage

To initialize the Payments SDK for iOS, you need to set the Environment at the entry point of your application. For example, you can do this on your AppDelegate file on the application(_:,didFinishLaunchingWithOptions:) method, as shown below.

import AlCore

...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Setup Alviere SDK.
    if !AlCoreSDK.shared.setEnvironment(.sandbox) {
        print("Error initializing SDK.")
    }
    return true
}

After this setup, you just need to import the Payments SDK for iOS on the files where you want to use the features.

import Payments

Optionally, if you will use the Deposit Check features you have to adjust your app’s permissions for camera usage. You just need to add the NSCameraUsageDescription in your Info.plist file. Right-click somewhere outside the table and select Add Row. Now add the entries like below.

image

Or if you prefer to do this step with code, right-click on Info.plist and select Open As > Source Code. Add the lines below somewhere inside the <dict> </dict>.

<!-- Permission to be include in Info.plist -->
<key>NSCameraUsageDescription</key>
<string>This will let you easily take pictures of your Checks so you can deposit them.</string>

When writing the permission request message always follow the iOS Human Design Guidelines as a guideline.

Payment Methods

Adopt the PaymentMethodsDelegate protocol

This can be handled, for instance, by the view controller object that will present the UI.

extension ViewController : PaymentMethodsDelegate

The PaymentMethodsDelegate methods are the main communication backchannel to your application for the account payment methods management on Payments SDK for iOS. For each action there is one method associated as follows:

  • Create Card: didCreateCard(_:validation:)
  • List Cards: didListCards(_:)
  • Get Card: didGetCard(_:)
  • Delete Card: didDeleteCard()
  • Create Bank Account: didCreateBankAccount(_:)
  • List Bank Accounts: didListBankAccounts(_:)
  • Get bank Account: didGetBankAccount(_:)
  • Delete Bank account: didDeleteBankAccount()
  • Create Plaid Bank Account: didCreatePlaidBankAccount(_:)
  • Activate Plaid Bank Account: didActivatePlaidBankAccount()

There is also a global method didHandleEvent(_,metadata:) to receive events, like errors for instance. This enables your application to gain further insight into what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display error-related information to the user and have them try doing the action again.

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

Create Card

To create a card you can either do it by presenting the included UI objects or by providing the card data directly to createCard method of the SDK. The result of creating a card will return the card and it’s validation status on the didCreateCard(_:validation:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreateCard(_ card: Card, validation: Validation) {
    print("Card:\n\(Card)")
}

Create Card UI Presentation

Presenting the Create Card is as simple as creating a new auth_token, using it to initialize AlPayments, and get/register the CreateCardViewController / CreateCardView instances. You can also use the card creation with your own UI.

Presenting Create Card View Controller

From code

To instantiate CreateCardViewController from code, use createCreateCardViewController to create a new auth_token and pass the PaymentMethodsDelegate delegate instance. Optionally, you can also pass an extra data model, with an account id, and customization objects with the style and validation overrides you want to apply. You can either present the newly created view controller by pushing it, with show, or modally, with present.

let viewController = AlPayments.shared
    .createCreateCardViewController(token: authToken,
                                    delegate: self,
                                    validation: validation,
                                    style: style)

self.navigationController?.show(viewController, sender: self)

When presenting modally, you still need to embed the view controller on a navigation controller and then present the navigation controller itself.

⚠️

If the CreateCardViewController has no navigation controller it will throw an error and crash your application.

let viewController = AlPayments.shared
    .createCreateCardViewController(token: authToken,
                                    delegate: self,
                                    validation: validation,
                                    style: style)

let navigationController = UINavigationController(rootViewController: viewController)

self.present(navigationController, animated: true)

From Storyboard

To create an CreateCardViewController from a Storyboard or a xib you need to select your view controller. On the Custom Class section, set the Class as CreateCardViewController and enable the Inherit Module From Target checkbox. At this point, you only need to register your view controller with AlPayments, using the registerCreateCardViewController, create a new auth_token and pass the PaymentMethodsDelegate delegate instance. Optionally, you can also pass an extra data model, with an account id.

⚠️

When presenting modally the CreateCardViewController ensure that it’s embedded on a navigation controller or it will throw an error and crash your application.

image

If you present the view controller with a Segue you need to implement a prepare(for:, sender:) callback and then register the view controller.

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
    AlPayments.shared
        .registerCreateCardViewController(token: authToken,
                                          viewController: segue.destination,
                                          delegate: self)
}

If you choose to instantiate the view controller by Storyboard ID and navigate manually, you just need to register the view controller.

let viewController = UIStoryboard(name: "Main", bundle: nil)
    .instantiateViewController(identifier: "CreateCardViewController") as! CreateCardViewController

AlPayments.shared
    .registerCreateCardViewController(token: authToken,
                                      viewController: viewController,
                                      delegate: self)

self.navigationController?.show(viewController, sender: self)

Presenting Create Card View Component

When using the Card Creation as a component, be advised that you will also have the task of handling the errors and navigation.

From Code

To instantiate CreateCardView from code, use createCreateCardView where you will need to create a new auth_token and pass the PaymentMethodsDelegate delegate instance. You also have the option to pass an extra data model, with an account id, and customization objects with the style and validation overrides you want to apply.

let view = AlPayments.shared
    .createCreateCardView(token: authToken,
                          delegate: self,
                          validation: validation,
                          style: style)

From Storyboard

To create an CreateCardView from a Storyboard or a xib you need to select your view, and on the Custom Class section, set the Class as CreateCardView and enable the Inherit Module From Target checkbox.

image

Create an IBOutlet and register your view with AlPayments on the viewDidLoad method, using the registerCreateCardView and, create a new auth_token and pass the PaymentMethodsDelegate delegate instance. If you wish, you may also pass an extra data model, with an account id, and customization objects with the style and validation overrides you want to apply. Be advised that by this method you will miss the open event on the delegate.

@IBOutlet weak var view: CreateCardView!

...

override func viewDidLoad() {
    super.viewDidLoad()

    AlPayments.shared
        .registerCreateCardView(token: authToken,
                                view: view,
                                delegate: self)
}

Create Card Usage without UI

If you want to call the create card service directly, use createCard where you will need to create a new auth_token, pass the accountUuid, the CardRequest model with the data, and the PaymentMethodsDelegate delegate instance. You also have the option to pass a customization object with the validation overrides you want to apply, for example for the zip/postal code field.

let model = CardRequest( ... )

AlPayments.shared
    .createCard(token: authToken,
                accountUuid: accountUuid,
                data: model,
                delegate: self)

List Cards

To list the cards you will need to create a new auth_token, pass the accountUuid and the PaymentMethodsDelegate delegate instance. You can also define the number of items (limit) to be returned as well as the offset.

AlPayments.shared
    .listCards(token: authToken,
               accountUuid: accountUuid,
               query, query,
               delegate: self)

The result of this action will return the [Card] list on the didListCards(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListCards(_ cards: [Card]) {
    print("Cards:\n\(cards)")
}

Get Card

To get a single card you will need to create a new auth_token, pass the accountUuid, the paymentMethodUuid and the PaymentMethodsDelegate delegate instance.

AlPayments.shared
    .getCard(token: authToken,
             accountUuid: accountUuid,
             paymentMethodUuid: paymentMethodUuid,
             delegate: self)

The result of this action will return the Card on the didGetCard(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetCard(_ card: Card) {
    print("Card:\n\(card)")
}

Delete Card

To delete a card you will need to create a new auth_token, pass the accountUuid, the paymentMethodUuid and the PaymentMethodsDelegate delegate instance.

AlPayments.shared
    .deleteCard(token: authToken,
                accountUuid: accountUuid,
                paymentMethodUuid: paymentMethodUuid,
                delegate: self)

The result of this action will return a confirmation on the didDeleteCard() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didDeleteCard() {
    print("Success")
}

Create Bank Account

To create a bank account you will need to create a new auth_token, pass the accountUuid, the BankRequest model with the data and the PaymentMethodsDelegate delegate instance.

let model = BankRequest(...)

AlPayments.shared
    .createBankAccount(token: authToken,
                       accountUuid: accountUuid,
                       data: model,
                       delegate: self)

The result of this action will return the Bank on the didCreateBankAccount(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreateBankAccount(_ bank: Bank) {
    print("Bank:\n\(bank)")
}

List Bank Accounts

To list the bank accounts you will need to create a new auth_token, pass the accountUuid and the PaymentMethodsDelegate delegate instance. You can also define the number of items (limit) to be returned as well as the offset.

AlPayments.shared
    .listBankAccounts(token: authToken,
                      accountUuid: accountUuid,
                      query: query,
                      delegate: self)

The result of this action will return the [Bank] on the didListBankAccounts(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListBankAccounts(_ bank: [Bank]) {
    print("Banks:\n\(banks)")
}

Get Bank Account

To get a bank account you will need to create a new auth_token, pass the accountUuid, the paymentMethodUuid and the PaymentMethodsDelegate delegate instance.

AlPayments.shared
    .getBankAccount(token: authToken,
                    accountUuid: accountUuid,
                    paymentMethodUuid: paymentMethodUuid,
                    delegate: self)

The result of this action will return the Bank on the didGetBankAccount(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetBankAccount(_ bank: Bank) {
    print("Bank:\n\(bank)")
}

Delete Bank Account

To delete a bank account you will need to create a new auth_token, pass the accountUuid, the paymentMethodUuid and the PaymentMethodsDelegate delegate instance.

AlPayments.shared
    .deleteBankAccount(token: authToken,
                       accountUuid: accountUuid,
                       paymentMethodUuid: paymentMethodUuid,
                       delegate: self)

The result of this action will return a confirmation on the didDeleteCard() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didDeleteBankAccount() {
    print("Success")
}

Plaid Integration

You can also create bank accounts through Plaid Link SDK with the Alviere system.

Create Plaid Bank Account

To create a plaid bank account, use createPlaidBankAccount where you will need to create a new auth_token, pass the accountUuid, the PlaidBankRequest model with the data, and the PaymentMethodsDelegate delegate instance.

let model = PlaidBankRequest( ... )

AlPayments.shared
    .createPlaidBankAccount(token: authToken,
                            accountUuid: accountUuid,
                            data: model,
                            delegate: self)

The result of this action will return the Bank on the didCreatePlaidBankAccount(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCreatePlaidBankAccount(_ bank: Bank) {
    print("Bank:\n\(bank)")
}

Activate Plaid Bank Account

To activate a plaid bank account, use activatePlaidBankAccount where you will need to create a new auth_token, pass the accountUuid, the paymentMethodUuid and the PaymentMethodsDelegate delegate instance.

AlPayments.shared
    .activatePlaidBankAccount(token: authToken,
                              accountUuid: accountUuid,
                              paymentMethodUuid: paymentMethodUuid,
                              delegate: self)

The result of this action will return the Bank on the didActivatePlaidBankAccount() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didActivatePlaidBankAccount() {
    print("Bank activated")
}

Wallets

Adopt the WalletsDelegate protocol

This can be handled, for instance, by the view controller object that will present the UI.

extension ViewController : WalletsDelegate

The WalletsDelegate methods are the main communication backchannel to your application for the account wallet actions on Payments SDK for iOS. For each action there is one method associated as follows:

  • List Wallets: didListWallets(_:)
  • Get Wallet: didGetWallet(_:)
  • List Wallet Transactions: didListWalletTransactions(_:)
  • Load Funds: didLoadFunds(_:)
  • Withdraw Funds: didWithdrawFunds(_:)
  • Send Funds: didSendFunds(_:)
  • Transfer Funds: didTransferFunds(_:)

There is also a global method didHandleEvent(_,metadata:) to receive events, like errors for instance. This enables your application to gain further insight into what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display error-related information to the user and have them try doing the action again.

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

List Wallets

To list the wallets you will need to create a new auth_token, pass the accountUuid and pass the WalletsDelegate delegate instance.

AlPayments.shared
    .listWallets(token: authToken,
                 accountUuid: accountUuid,
                 delegate: self)

The result of this action will return the [Wallet] on the didListWallets(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListWallets(_ wallets: [Wallet]) {
    print("Wallets:\n\(wallets)")
}

Get Wallet

To get a wallet you will need to create a new auth_token, pass the accountUuid, the walletUuid and pass the WalletsDelegate delegate instance.

AlPayments.shared
    .getWallet(token: authToken,
               accountUuid: accountUuid,
               walletUuid: walletUuid,
               delegate: self)

The result of this action will return the Wallet on the didGetWallet(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetWallet(_ wallet: Wallet) {
    print("Wallet:\n\(wallet)")
}

List Wallet Transactions

To list the transactions in a wallet you will need to create a new auth_token, pass the walletUuid and pass the WalletsDelegate delegate instance. Optionally you can pass a WalletTransactionsQuery to filter the data.

AlPayments.shared
    .listWalletTransactions(token: authToken,
                            walletUuid: walletUuid,
                            delegate: self)

The result of this action will return the [Transaction] on the didListWalletTransactions(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListWalletTransactions(_ transactions: [Transaction]) {
    print("Transactions:\n\(transactions)")
}

Load Funds

To load funds from a payment method you will need to create a new auth_token and pass the walletUuid, provide the LoadFundsRequest model with the data of the load, and pass the WalletsDelegate delegate instance.

let model: LoadFundsRequest = LoadFundsRequest( ... )

AlPayments.shared
    .loadFunds(token: authToken,
               walletUuid: walletUuid,
               request: model,
               delegate: self)

The result of this action will return the Transaction on the didLoadFunds(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didLoadFunds(_ transaction: Transaction) {
    print("Transaction:\n\(transaction)")
}

Withdraw Funds

To withdraw funds from a payment method you will need to create a new auth_token and pass the walletUuid, provide the WithdrawFundsRequest model with the data of the withdraw, and pass the WalletsDelegate delegate instance.

let model: WithdrawFundsRequest = WithdrawFundsRequest( ... )

AlPayments.shared
    .withdrawFunds(token: authToken,
                   walletUuid: walletUuid,
                   request: model,
                   delegate: self)

The result of this action will return the Transaction on the didWithdrawFunds(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didWithdrawFunds(_ transaction: Transaction) {
    print("Transaction:\n\(transaction)")
}

Send Funds

To send funds from a wallet you will need to create a new auth_token and pass the walletUuid, provide the SendFundsRequest model with the data of the send, and pass the WalletsDelegate delegate instance.

let model: SendFundsRequest = SendFundsRequest( ... )

AlPayments.shared
    .sendFunds(token: authToken,
               walletUuid: walletUuid,
               request: model,
               delegate: self)

The result of this action will return the Transaction on the didSendFunds(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didSendFunds(_ transaction: Transaction) {
    print("Transaction:\n\(transaction)")
}

Transfer Funds

To transfer funds from a wallet you will need to create a new auth_token and pass the walletUuid, provide the TransferFundsRequest model with the data of the send, and pass the WalletsDelegate delegate instance.

let model: TransferFundsRequest = TransferFundsRequest( ... )

AlPayments.shared
    .transferFunds(token: authToken,
                   walletUuid: walletUuid,
                   request: model,
                   delegate: self)

The result of this action will return the Transaction on the didTransferFunds(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didTransferFunds(_ transaction: Transaction) {
    print("Transaction:\n\(transaction)")
}

Transactions

Adopt the TransactionsDelegate protocol

This can be handled, for instance, by the view controller object that will present the UI.

extension ViewController : TransactionsDelegate

The WalletsDelegate methods are the main communication backchannel to your application for the account wallet actions on Payments SDK for iOS. For each action there is one method associated as follows:

  • List Child Transactions: didListChildTransactions(_:)
  • Get Transaction Details: didGetTransactionDetails(_:)
  • Get Receipt: didGetReceipt(_:)
  • Cancel Transaction: didCancelTransaction()

There is also a global method didHandleEvent(_,metadata:) to receive events, like errors for instance. This enables your application to gain further insight into what is going on as the user goes through the Payments SDK flow. In case of an error, you may want to display error-related information to the user and have them try doing the action again.

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

List Child Transactions

To list the child transactions of a transaction you will need to create a new auth_token, pass the transactionUuid and pass the TransactionsDelegate delegate instance. Optionally you can pass a ChildTransactionsQuery to filter the data.

AlPayments.shared
    .listChildTransactions(token: authToken,
                           transactionUuid: transactionUuid,
                           delegate: self)

The result of this action will return the [Transaction] on the didListChildTransactions(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListChildTransactions(_ transactions: [Transaction]) {
    print("Transactions:\n\(transactions)")
}

Get Transaction Details

To get a transaction’s details you will need to create a new auth_token, pass the transactionUuid and pass the TransactionsDelegate delegate instance.

AlPayments.shared
    .getTransactionDetails(token: authToken,
                           accountUuid: accountUuid,
                           delegate: self)

The result of this action will return the Transaction on the didGetTransactionDetails(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetTransactionDetails(_ transaction: Transaction) {
    print("Transaction:\n\(transaction)")
}

Get Receipt

To get a receipt of a transaction you will need to create a new auth_token, pass the transactionUuid and pass the TransactionsDelegate delegate instance.

AlPayments.shared
    .getReceipt(token: authToken,
                transactionUuid: transactionUuid,
                delegate: self)

The result of this action will return the Receipt on the didGetReceipt(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetReceipt(_ receipt: Receipt) {
    print("Receipt:\n\(receipt)")
}

Cancel Transaction

To cancel a transaction you will need to create a new auth_token, pass the transactionUuid and pass the TransactionsDelegate delegate instance.

AlPayments.shared
    .cancelTransaction(token: authToken,
                       transactionUuid: transactionUuid,
                       delegate: self)

The result of this action will invoke the didCancelTransaction() delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCancelTransaction() {
    print("Success!")
}

Check deposits

Adopt the CheckDepositsDelegate Protocol

This can be handled, for instance, by the view controller object that will call the user account actions.

extension ViewController : CheckDepositsDelegate

The CheckDepositsDelegate and CheckDepositsCaptureDelegate methods are the main communication back channel to your application for the user check deposit on Payments SDK for iOS. For each action there is one method associated as follows:

  • Deposit: didDepositCheck(_:)
  • Capture: didCaptureCheck(::)
  • Get: didGetCheck(_:)
  • List: didListChecks(_:)

There is also a global method didHandleEvent(_,metadata:) to receive events, like errors for instance. This enables your application to gain further insight into what is going on as the user goes through the Payments SDK flow. In case of an error you may want to display error related information to the user and have them try doing the action again.

func didHandleEvent(_ event: String, metadata: [String : String]?) {
    print("Received event: \(event)\nmetadata: \(metadata ?? [:])")
}

The event keys are defined on the Event enum and the metadata keys on Metadata enum.

Deposit Check

To deposit a check you can either do it by presenting the included UI objects or by providing the check data directly to depositCheck method of the SDK. The result of depositing a check will return the check on the didDepositCheck(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didDepositCheck(_ check: Check) {
    print("Check:\n\(check)")
}
⚠️

Be aware that you should request camera permission before presenting DepositCheckViewController or it will throw an error and crash your application.

Deposit Check UI Presentation

Presenting the Deposit Check is as simple as creating a new auth_token and a camera_token, using it to initialize AlPayments, and get/register the DepositCheckViewController instance. To obtain a camera token you need to call the AlCore.shared.getCameraToken method providing the user accountUUID.

var cameraToken: String?

AlCore.shared.getCameraToken(accountUUID: "accountUUID") { (token: String) in
    cameraToken = token
} failure: { (error: AlError) in
    print(error)
}

Presenting Deposit Check View Controller

From Code

To instantiate CheckDepositViewController from code, use createCheckDepositViewController where you will need to pass the previous data. Optionally, you can also pass a UI customization object with the style overrides you want to apply.

ℹ️

Be aware that you need to present the view controller with show, presenting modally with present can produce unexpected results.

let data = DepositCheckRequest(...)

let viewController = AlPayments.shared
    .createCheckDepositViewController(token: authToken,
                                      cameraToken: cameraToken,
                                      data: data,
                                      extraData: extraData,
                                      delegate: delegate,
                                      style: style)

self.navigationController?.show(viewController, sender: self)

From Storyboard

To create a CheckDepositViewController from a Storyboard or a xib you need to select your view controller. On the Custom Class section, set the Class as CheckDepositViewController and enable the Inherit Module From Target checkbox. At this point, you only need to register your view controller with AlPayments, using the registerCheckDepositViewController and passing the previous data. Optionally, you can also pass a UI customization object with the style overrides you want to apply.

ℹ️

Be aware that you need to present the view controller with show, presenting modally with present can produce unexpected results.

image

If you present the view controller with a Segue you need to implement a prepare(for:, sender:) callback and then register the view controller.

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
    let data = DepositCheckRequest(...)

    AlPayments.shared
        .registerCheckDepositViewController(token: authToken,
                                            cameraToken: cameraToken,
                                            viewController: segue.destination,
                                            data: data,
                                            extraData: extraData,
                                            delegate: self,
                                            style: style)
}

If you choose to instantiate the view controller by Storyboard ID and navigate manually, you just need to register the view controller.

let viewController = UIStoryboard(name: "Main", bundle: nil)
    .instantiateViewController(identifier: "CheckDepositViewController") as! CheckDepositViewController

let data = DepositCheckRequest(...)

AlPayments.shared
    .registerCheckDepositViewController(token: authToken,
                                        cameraToken: cameraToken,
                                        viewController: viewController,
                                        data: data,
                                        extraData: extraData,
                                        delegate: self,
                                        style: style)

self.navigationController?.show(viewController, sender: self)

Deposit Check Usage without UI

If you want to call the deposit check service directly, use depositCheck where you will need to create a new auth_token, pass the walletUuid, the DepositCheckRequest model with the data, and the CheckDepositsDelegate delegate instance.

let model = DepositCheckRequest( ... )

AlPayments.shared
    .depositCheck(token: authToken,
                  walletUuid: walletUuid,
                  data: model,
                  delegate: self)

Capture Check

To capture a check you need to present an instance of DepositCheckViewController either from code or from a storyboard. To start this instance you will need to pass the and pass the CheckDepositsCaptureDelegate delegate instance.

⚠️

Be aware that you should request camera permission before presenting DepositCheckViewController or it will throw an error and crash your application.

The result of this action will return the base64 strings of the front and back images of the captured check on the didCaptureCheck(_:_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didCaptureCheck(frontImage: String, backImage: String) {
    print("Front image:\n\(frontImage)")
    print("Back image:\n\(backImage)")
}

Present from Code

To instantiate CheckDepositViewController from code, use createCaptureCheckDepositViewController where you will need to pass the previous data. Optionally, you can also pass a UI customization object with the style overrides you want to apply.

ℹ️

Be aware that you need to present the view controller with show, presenting modally with present can produce unexpected results.

let viewController = AlPayments.shared
    .createCaptureCheckDepositViewController(cameraToken: cameraToken,
                                             delegate: delegate,
                                             style: style)

self.navigationController?.show(viewController, sender: self)

Present from Storyboard

To create a CheckDepositViewController from a Storyboard or a xib you need to select your view controller. On the Custom Class section, set the Class as CheckDepositViewController and enable the Inherit Module From Target checkbox. At this point, you only need to register your view controller with AlPayments, using the registerCaptureCheckDepositViewController and passing the previous data. Optionally, you can also pass a UI customization object with the style overrides you want to apply.

ℹ️

Be aware that you need to present the view controller with show, presenting modally with present can produce unexpected results.

image

If you present the view controller with a Segue you need to implement a prepare(for:, sender:) callback and then register the view controller.

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
    AlPayments.shared
        .registerCaptureCheckDepositViewController(cameraToken: cameraToken,
                                                   viewController: segue.destination,
                                                   delegate: self,
                                                   style: style)
}

If you choose to instantiate the view controller by Storyboard ID and navigate manually, you just need to register the view controller.

let viewController = UIStoryboard(name: "Main", bundle: nil)
    .instantiateViewController(identifier: "CheckDepositViewController") as! CheckDepositViewController

AlPayments.shared
    .registerCaptureCheckDepositViewController(cameraToken: cameraToken,
                                               viewController: viewController,
                                               delegate: self,
                                               style: style)

self.navigationController?.show(viewController, sender: self)

List Checks

To withdraw funds from a payment method you will need to create a new auth_token, pass the walletUuid and pass the CheckDepositsDelegate delegate instance.

AlPayments.shared
    .listChecks(token: authToken,
                walletUuid: walletUuid,
                query: query,
                delegate: self)

The result of this action will return the [Check] on the didListChecks(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didListChecks(_ checks: [Check]) {
    print("Checks:\n\(checks)")
}

Get Check

To get a check you will need to create a new auth_token, pass the checkUuid and pass the CheckDepositsDelegate delegate instance.

AlPayments.shared
    .getCheck(token: authToken,
              checkUuid: checkUuid,
              delegate: self)

The result of this action will return the Check on the didGetCheck(_:) delegate method. Any errors will be returned on didHandleEvent(_,metadata:) delegate method.

func didGetCheck(_ check: Check) {
    print("Check:\n\(check)")
}

Alternative Usage

The SDK can also be integrated using Closures, Combine or Async/Await methods. They can be accessed respectively by:

  • Closures - A closure can be passed instead of the delegate.
  • Combine - AlPayments.shared.combine can be used to access methods that return Combine Future objects.
  • Async/Await - AlPayments.shared.async can be used to access async methods.

Customization

The Payments SDK for iOS provides a set of UI styling and field validation customizations to allow you to adjust the provided UI to fit your needs by setting a style model. To customize the UI, start from the default style and make the changes; you can also select the card brands that you wish to support on validations. The default includes all brands. You can check the supported brands on CardBrand enum.

var style = CreateCardStyle.getDefaultStyle()
style.backgroundColor = UIColor.white
...

Styling

Below are the styling options provided that are used to compose style models like CreateCardStyle.

Class Attribute Description
ViewStyle backgroundColor UIColor that affects the background color of UIView
  darkBackgroundColor UIColor that affects the background color of UIView in dark mode
TextStyle color UIColor that affects the text color of UILabel
  darkColor UIColor that affects the text color of UILabel in dark mode
  font UIFont that affects the text font of UILabel
ButtonStyle backgroundColor UIColor that affects the background color of UIButton
  darkBackgroundColor UIColor that affects the background color of UIButton in dark mode
  titleStyle TextStyle that affects the text font and color of UIButton
  cornerRadius CGFloat that controls the corner radius of UIButton
  height CGFloat that controls the height of UIButton
  margins UIEdgeInsets that controls the margins of UIButton
TextFieldStyle backgroundColor UIColor that affects the background color of UITextField
  darkBackgroundColor UIColor that affects the background color of UITextField in dark mode
  textStyle TextStyle that affects the text font and color of UITextField text
  placeholderStyle TextStyle that affects the text font and color of UITextField placeholder
  keyboardType UIKeyboardType for field
CreateCardFieldStyle backgroundColor UIColor that affects the background color of a field
  darkBackgroundColor UIColor that affects the background color of a field in dark mode
  textFieldStyle TextFieldStyle that affects the style of UITextField
  errorLabelStyle TextStyle that affects the text font and color of error UILabel

Validation

Below are the validation customizations provided that you can use to change some field validations to fit your needs. They are used to compose validation models like CardValidation.

Class Attribute Description
CardBrand enum of supported card brands
TextValidation regex validation regex
  minimumCharacters minimum allowed characters
  maximumCharacters maximum allowed characters
  isRequired sets the field as required

Text and Localization

The Payments SDK for iOS allows you to customize the UI text. To do so, you will need to redefine the localization key that you want to change on your Localizable.strings file. The next section details a list of the current localization keys. Currently, the SDK only provides english localization.

Localization Keys

Key English Value
alviere_sdk_payments_create_card_title Create Card
alviere_sdk_payments_create_card_number_placeholder Number
alviere_sdk_payments_create_card_expiration_date_placeholder Expiration Date
alviere_sdk_payments_create_card_cvc_placeholder CVC
alviere_sdk_payments_create_card_cvv_placeholder CVV
alviere_sdk_payments_create_card_cardholder_name_placeholder Cardholder Name
alviere_sdk_payments_create_card_zip_code_placeholder Zip Code
alviere_sdk_payments_create_card_add_title Create
alviere_sdk_payments_create_card_add_error_required_field Required
alviere_sdk_payments_create_card_add_error_invalid_field Invalid
alviere_sdk_payments_create_card_add_error_invalid_card Invalid or unsupported card
alviere_sdk_payments_create_card_error_title Error
alviere_sdk_payments_create_card_error_retry Try again
alviere_sdk_vo_payments_error_on_field Error on field %@. %@.\n
alviere_sdk_vo_payments_create_card_loading_title Sending data
alviere_sdk_vo_payments_create_card_loading_complete Card created
alviere_sdk_payments_deposit_check_title_check_front Check front
alviere_sdk_payments_deposit_check_title_check_back Check back
alviere_sdk_payments_deposit_check_hint_glare Reduce glare
alviere_sdk_payments_deposit_check_hint_low_contrast Low contrast
alviere_sdk_payments_deposit_check_hint_busy_background Busy background
alviere_sdk_payments_deposit_check_hint_not_check_back Not check back
alviere_sdk_payments_deposit_check_hint_not_check_front Not check front
alviere_sdk_payments_deposit_check_hint_not_identity_back Not document back
alviere_sdk_payments_deposit_check_hint_not_identity_front Not document front
alviere_sdk_payments_deposit_check_hint_not_passport Not passport
alviere_sdk_payments_deposit_check_hint_nothing Nothing detected
alviere_sdk_payments_deposit_check_hint_too_dim Too dim
alviere_sdk_payments_deposit_check_hint_too_bright Too bright
alviere_sdk_payments_deposit_check_hint_not_sharp Not sharp
alviere_sdk_payments_deposit_check_hint_rotation Reduce rotation
alviere_sdk_payments_deposit_check_hint_angle_too_large Angle too large
alviere_sdk_payments_deposit_check_hint_too_close Too close
alviere_sdk_payments_deposit_check_hint_too_far Too far
alviere_sdk_payments_deposit_check_hint_hold_steady Hold Still
alviere_sdk_payments_deposit_check_hint_data_obstructed Data obstructed
alviere_sdk_payments_deposit_check_warning_not_portrait Hold device in portrait mode
alviere_sdk_payments_deposit_check_step Step %d of %d
alviere_sdk_payments_deposit_check_title_preview Photo preview
alviere_sdk_payments_deposit_check_preview_title Accept photo?
alviere_sdk_payments_deposit_check_preview_retake Cancel
alviere_sdk_payments_deposit_check_preview_ok Accept
alviere_sdk_payments_deposit_check_completed_title Success
alviere_sdk_payments_deposit_check_uploading_title Uploading your check…
alviere_sdk_vo_payments_deposit_check_uploading_title Uploading your check
alviere_sdk_vo_payments_deposit_check_uploading_complete Upload finished
alviere_sdk_payments_deposit_check_error_title Error
alviere_sdk_payments_deposit_check_error_generic We couldn’t upload your check.
alviere_sdk_payments_deposit_check_error_retry Try again
alviere_sdk_loading_title Loading
alviere_sdk_error_title Error
alviere_sdk_error_try_again Try Again
alviere_sdk_error_generic An error has occurred
alviere_sdk_vo_loading_done Finished loading

Assets and Icons

The Payments SDK for iOS allows you to customize the assets and icons used. You just need to create an entry on an Asset Catalog (.xcassets) file with the same key as ours. The currently available keys are below.

Key Description
create-card-error-icon Icon presented on the create card submit error screen.
deposit-check-error-icon Icon presented on the deposit check submit error screen.