How to integrate with iOS SDK

Required Flow

Before starting the integration with our iOS SDK, it is important to understand the overall flow of requests coming from the SDK to Dapi's system. In addition to setting up the iOS SDK, you will also need to configure a backend server. The purpose of the backend server is to provide an extra layer of security and allow you to confirm the information on your backend if required by your use case.

Setting-up App Backend Server (Node.js)

If you are not interested in setting up the server using Node.js, you can refer to the Server set-up for SDKs and follow any quickstart instructions for a different language.

Install npm libraries in your project

npm i @dapi-co/dapi-node
npm i express
npm i cors

Save the following file as server.js. You might need to install the other dependencies if they don't already exist on your machine.

var express = require('express')
const DapiApp = require('@dapi-co/dapi-node')
var cors = require('cors')

const app = express()
const port = 8060 // default port to listen
app.use(cors())
app.use(express.json())

const dapi = new DapiApp.default({
  appSecret: 'YOUR_APP_SECRET',
})

// define a route handler for the sdk
app.post('/dapi', async (req, res) => {

  try {
    
    const dapiResponse = await dapi.handleSDKDapiRequests(req.body, req.headers)
    res.send(dapiResponse)

  } catch (error) {

    //Handle Network Errors
    console.dir(error)
  }
})

// start the Express server
app.listen(port, () => {
  console.log(`server started at http://localhost:${port}`)
})

In the directory of server.js use the following command to run the server:

node server.js

Once the server is running successfully, also make sure to add the App Server URL to the Dapi Dashboard. In this way, the SDK will automatically know where to send its requests to.

If you followed the above NodeJS and Express example the App Server URL value is http://localhost:8060/dapi.

You are now all set to start your iOS integration!

iOS SDK Example

Clone this repository, run the application and see Dapi in action.

iOS SDK Configuration

Install SDK

1. Open the pod file in a text editor and add following line

pod 'DapiSDK'

2. Run the following command in your project directory

pod install

Start SDK

1. Import DapiConnect in your AppDelegate

import DapiConnect

2. Create Dapi client with your configurations in the AppDelegate in the didFinishLaunchingWithOptions method.

let configuration = DapiConfigurations(countries: ["AE"], environment: .production) // or .sandbox
configuration.endPointExtraBody = [DPCEndPoint.getAccounts: ["key": "value"]]
configuration.endPointExtraHeaderFields = [DPCEndPoint.getAccounts: ["key": "value"]]
configuration.endPointExtraQueryItems = [DPCEndPoint.getAccounts: [URLQueryItem.init(name: "key", value: "value")]]
Dapi.start(appKey: "your_app_key", clientUserID: "your_current_logged_in_user_id", configuration: configuration) { (dapi, error) in
}

In case you get App config not found error double check your Bundle Identifier is the same as the bundleID you set on the dashboard.

1. Open your .xcodeproj file
2. Copy the value of Bundle Identifier

3. Open your app in the dashboard
4. Go to App Settings -> Bundle IDs
5. Click on the + icon, paste the copied value and click Submit

Create Bank Connection

Let's now create a connection object. A connection represents a user's connection to a bank. So if they authenticate and login, through Dapi, to 2 banks there will be 2 connections.
Since you don't know yet which bank the user will choose, you will just display the connect page. The user has to then pick the bank and enter their credentials.

Dapi.shared.presentConnect(self)

Add an extension to handle a successful or a failed connection attempt.

extension ViewController: DapiConnectDelegate {

    func connectDidSuccessfullyConnect(toBankID bankID: String, connection: DapiBankConnection) {
        
    }
    
    func connectDidFailConnecting(toBankID bankID: String, withError error: String) {
        
    }

}

That's it. You can now try to run your app on the emulator and call the presentConnect function and see Dapi in action!

Create Sandbox User

You can create users for sandbox environment to test your integration with Dapi instead of connecting your real accounts

Navigate to Dashboard -> Apps -> Your App -> Sandbox -> Create a Sandbox User

Enter the following details and click Submit.

• Sandbox Bank: select a bank from the dropdown list
• Sandbox Username : username of your choice
• Sandbox Password : password of your choice

In order to add accounts to a sandbox user, click the NEW button on the Accounts column and provide the following information:

• Acount Name: user's account name (You can see it on the Account Information dialog when you click an account from the Sandbox Users table.)
• Account Number: user's account number (You can see it on the Account Information dialog)
• IBAN: user's IBAN (You can see it on the Account Information dialog)
• Account Type: choose a value from the dropdown
• Balance: set a starting balance for the account
• Currency: choose the currency for the account from the dropdown

Get Cached Connections

When you authenticate and login through Dapi, a DapiConnection object is created and stored in the local cache containing information about your connection to the bank, so that you don't have to authenticate and login again every time you open the app.

Dapi.getConnections() returns the list of connections in cache.

Dapi.shared.getConnections()

iOS SDK Reference

Payment Endpoints

createTransfer()

A method for creating a transfer. Can be used to make a payment:

• from the user's account to your own account
• from the user's account to another external account

So in a nutshell, you can send money from an account to an account with a specific amount.All 3 variables are optional.

Parameters

📘

Note

Behavior of the SDK depends on the parameters that will be set.

Example - When to Is Not Specified

Here we will pick the first account in the connection object. Remember, a bank connection might have several accounts, so the accounts object is a list. You will need to pick which account you're sending from.

connection.createTransfer(from: connection.accounts.first!, amount: 10) 
{ (account, amount, error, operationID) in

}

Example - When to Is Specified

We first need to create a new Object called Beneficiary. We will then need to set a few details about the bank account we're sending the money to.

let beneficiaryInfo = DapiBeneficiaryInfo()
let lineAddress = DapiLinesAddress()
lineAddress.line1 = "baniyas road"
lineAddress.line2 = "dubai"
lineAddress.line3 = "united arab emirates"
beneficiaryInfo.linesAddress =  lineAddress
beneficiaryInfo.accountNumber = "0959040184901"
beneficiaryInfo.bankName = "Emirates NBD Bank PJSC"
beneficiaryInfo.swiftCode = "EBILAEAD"
beneficiaryInfo.iban = "AE140260000959040184901"
beneficiaryInfo.country = "AE"
beneficiaryInfo.branchAddress = "Baniyas Road Deira PO Box 777 Dubai UAE"
beneficiaryInfo.branchName = "Emirates NBD Bank PJSC"
beneficiaryInfo.phoneNumber = "0585859206"
beneficiaryInfo.name = "John Doe"
beneficiaryInfo.nickname = "John Doe ENBD"

connection.createTransfer(from: connection.accounts.first!, to: beneficiaryInfo, amount: 10) 
{ (account, amount, error, operationID) in
   
}

Example - When from Is Not Specified

connection.createTransfer(from: nil, amount: 10) 
{ (account, amount, error, operationID) in

}

The SDK shows UI for the user to select an account to send money from

Example - When amount Is Not Specified

connection.createTransfer(from: connection.accounts.first!) 
{ (account, amount, error, operationID) in

}

The SDK shows UI for the user to enter the amount to send

Example - No arguments

connection.createTransfer()

The SDK shows UI for the user to select an account to send money from then navigate to the amount screen to enter the amount to send

createTransferToExistingBeneficiary()

A method for sending money to an existing beneficiary.

Parameters

Example

connection.createTransferToExistingBeneficiary(
  from: acc,
  beneficiaryID: id, //get from getBeneficiaries call
  amount: 100,
  remark: nil) { (acc, amount, err, opID) in
    
}

🚧

Beneficiary Not Activated error on Sandbox

This error occurs If you make a transfer on Sandbox to wrong or random beneficiary details, instead you should make the beneficiary details to be of another sandbox user.

To get the beneficiary details of a sandbox user you can do the following:

1- Open your app on the dashboard and navigate to the Sandbox tab. You'll see the Sandbox Users table.
2- Click an Account from the Accounts column.
3- A dialog shows up containing beneficiary details.

createBeneficiary()

A method for adding a new beneficiary

Parameters

Example

let beneficiary = DapiBeneficiary()
let lineAddress = DapiLinesAddress()
lineAddress.line1 = "baniyas road"
lineAddress.line2 = "dubai"
lineAddress.line3 = "united arab emirates"
beneficiary.linesAddress =  lineAddress
beneficiary.accountNumber = "123456789"
beneficiary.bankName = "Emirates NBD Bank PJSC"
beneficiary.swiftCode = "EBILAEAD"
beneficiary.iban = "123456789123456789"
beneficiary.country = "AE"
beneficiary.branchAddress = "Baniyas Road Deira PO Box 777 Dubai UAE"
beneficiary.branchName = "Emirates NBD Bank PJSC"
beneficiary.phoneNumber = "0585123456"
beneficiary.name = "JohnDoe"

connection.createBeneficiary(beneficiary, completion: { (result, error, opID) in
    
})

getBeneficiaries()

A method for obtaining registered beneficiaries

Parameters

Method does not receive any parameter.

Example

connection.getBeneficiaries({ beneficiaries, error, operationID in
    
})

Metadata Endpoints

getAccountsMetaData()

A method for obtaining bank account metadata

Parameters

Method does not receive any parameter.

Example

connection.getAccountMetadata({ (metadata, error, opID) in
    
})

Data Endpoints

getAccounts()

A method for obtaining and displaying bank accounts of the user

Parameters

Method does not receive any parameter.

Example

connection.getAccounts { (accounts, error, operationID) in
  
}

Present Account Selection

Open Dapi's Accounts Screen to allow your user to select an account.

connection.presentAccountSelection { (account, error) in
                                            
}

getIdentity()

Get the identity information that has been confirmed by the bank.

These are the identity details that you will get. Not all banks provide all this data. So we will provide as much of it as possible.

Parameters
Method does not receive any parameter.

Example

connection.getIdentity({ (identity, error, opID) in
    
})

getCards()

A method for obtaining and displaying bank cards of the user

Parameters
Method does not receive any parameter.

Example

connection.getCards({ (cards, error, operationID) in
    
})

Account - getTransactions()

A method for obtaining and displaying transactions created from users bank accounts. The list will not be filtered. In other words, this will display all the transactions performed by the user from the specified account (not filtered by app).

Parameters

Example

connection.getTransactionsFor(connection.accounts[0], from: Date(timeIntervalSince1970: 0), to: Date()) 
{ (transactions, error, operationID) in

}

Card - getTransactions()

A method for obtaining and displaying transactions created from a card. The list will not be filtered. In other words, this will display all the transactions performed by the user from the specified account (not filtered by app).

Parameters

Example

connection.getTransactionsFor(card, from: Date.init(timeIntervalSince1970: 1619092001), to: Date(), completion: { (transactions, error, operationID) in

})

📘

Note

Date range of the transactions that can be retrieved varies for each bank. The range supported by the users bank is shown in the response parameter transactionRange of Get Accounts Metadata endpoint. If the date range you provide is bigger than the transactionRange you'll get INVALID_DATE_RANGE error.

To make sure you always send a valid date range you should check the transactionsRange.
Example:

Swift

private func getTransactionsFor(numberOfMonths: Int ) {
    self.selectedConnection?.getAccountMetadata({ response, error, operationID in
        let transactionsRetentionPeriod = response?.transactionsRetentionPeriod
        let now = Date()
        var fromDate = Date()
        if(Int(transactionsRetentionPeriod!.magnitude / 2628000) > numberOfMonths) {
            fromDate = Calendar.current.date(byAdding: .month, value: numberOfMonths * -1, to: now)!
        } else {
            fromDate = Calendar.current.date(byAdding: .second, value: Int(transactionsRetentionPeriod!.magnitude * -1), to: now)!
        }
        
        if let accs = self.selectedConnection?.accounts, !accs.isEmpty {
            self.selectedConnection?.getTransactionsFor(accs[0], from: fromDate, to: Date(), type: .default, completion: { (transactions, error, opID) in
                print(transactions, error, opID)
            })
        }
        
    })
}

Enable Network Logging

Enable network logging to get full information on the requests happening inside the SDK.

1. Open Product -> Scheme -> Edit Scheme -> Arguments
2. Add DAPI_NETWORK_LOGGIN_ENABLED environment variable with value YES

Launch in Production Checklist

This section highlights best practices and recommendations to help you achieve the best user experience with Dapi integration.

👍

ClientUserID configuration

ClientUserID is used to distinguish between different users on the same device. The value for ClientUserID needs to be set by you. We recommend setting clientUserID to your actual user ID that you use to distinguish between users. You should update the clientUserID once the user logs out and another user logs in.

Why? clientUserID is used to keep track of the bank connections in the cache.

👍

INVALID_CREDENTIALS or INVALID_CONNECTION

When receiving this error, the bank account should be connected again. Depending on your flow, you can do one or multiple of those steps:

• Delete the connection connection.delete({ result, err in })
• Prompt the user with Connect screen call Dapi.presentConnect() to reconnect the bank account. User selects the bank and logs in again.
• Prompt the user with the same bank login screen Dapi.presentConnect(bankID) to reconnect the bank account. User can log in again to the same bank that was connected before and skips the bank choosing stage.

Why? This error indicates that the user has updated their online banking credentials. This means that also the linked bank account details should be updated. If your application continues to use outdated details, it may result in blocking the user's banking account.

To reproduce this error on Sandbox to test your implementation you can do the following:

1- Login to your sandbox account
2- Open your app on the dashboard and navigate to the Sandbox tab. You'll see the Sandbox Users table.
3- Delete the account you're currently logged in to.
4- Go back to the Dapi SDK and make any API call and it will return this error

👍

Bank IDs

If your logic is relying on bankIDs, then note that sandbox and production bankIDs are different. For example, ADCB:

• Sandbox: DAPIBANK_AE_ADCB
• Production: ADCBAEAA

👍

Do you have internal timeouts?

Do you usually have a default timeout for the requests going out of your application or server? It is possible that resolving a request with the bank can take longer. Dapi has an internal timeout at 2 minutes for any request.

Having a shorter timeout on your end can result in it occasional 504 errors.

Additional checklist for Payment API

👍

Special characters

Please double-check that you are only passing in alpha-numeric values in the beneficiary information. Including special characters in any of the fields will result in errors later on.

👍

BENEFICIARY_COOL_DOWN_PERIOD

Make sure you have handled the beneficiary cooldown period. Receiving this error means that beneficiary activation will take time from the bank side and the user must wait for the cooldown period to end before attempting the transfer again.

The exact time taken varies based on the user's bank. You can get the time take for the beneficiary to be active for any bank by using getAccountsMetaData API. You can for example use it to schedule a notification for the user to send money again when the beneficiary is activated.

Production Access

Once you have completed the above checklist here are the 2 simple steps to move your application from Sandbox to Production.

1. AppKey Permissions

Contact the Dapi team to give your existing appKey the permission to make calls in our Production environment.

2. Change the environment variable to .production

let configuration = DapiConfigurations(countries: ["AE"], environment: .production) // used to be .sandbox
configuration.endPointExtraBody = [DPCEndPoint.getAccounts: ["key": "value"]]
configuration.endPointExtraHeaderFields = [DPCEndPoint.getAccounts: ["key": "value"]]
configuration.endPointExtraQueryItems = [DPCEndPoint.getAccounts: [URLQueryItem.init(name: "key", value: "value")]]
Dapi.start(appKey: "your_app_key", clientUserID: "your_current_logged_in_user_id", configuration: configuration) { (dapi, error) in
}

Congratulations, you are all set with your Dapi integration!