How to integrate with Xamarin SDK

Required Flow

Before starting the integration with our Xamarin 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 Xamarin 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 Side Libraries 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 Xamarin integration!

Xamarin SDK Example

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

Xamarin SDK Configuration

Install SDK

You will be installing the SDK as 3 components, in your main App, App.iOS, and App.Android projects. All the 3 components are available on NuGet.

The first step is to open your solution in Visual Studio.

App

1. In Visual Studio, from the project navigator, right-click on your App project > Add > NuGet Package.
2. Search for DapiConnect.
3. Click Add Package.

App.Android

1. In Visual Studio, from the project navigator, right click on your App.Android project > Add > NuGet Package.
2. Search for DapiConnect.Droid.
3. Click Add Package.
4. In MainActivity.cs, add Xamarin.Forms.DependencyService.Register<IDapiPlatformService, DapiPlatformService>(); just before LoadApplication(new App());.

Note: Visual Studio should auto import the following (if not, add them manually):

using DapiConnect;
using DapiConnect.Droid;

App.iOS

1. In Visual Studio, from the project navigator, right click on your App.iOS project > Add > NuGet Package.
2. Search for DapiConnect.iOS.
3. Click Add Package.
4. In AppDelegate.cs, add Xamarin.Forms.DependencyService.Register<IDapiPlatformService, DapiPlatformService>(); just before LoadApplication(new App());.

Note: Visual Studio should auto import the following (if not, add them manually):

using DapiConnect;
using DapiConnect.iOS;

Start SDK

1. Import Dapi

using DapiConnect;

2. Start the SDK with your configuration

DapiClient client = new DapiClient(DependencyService.Get<IDapiPlatformService>());
string[] countries = new string[] { "AE", "EG" };
var configurations = new DapiConfigurations(countries, DapiEnvironment.Production);
await client.StartDapi("APP_KEY", "JohnDoe", configs);

In case you get App config not found error double check your Package name for Android or Bundle Identifier for iOS is the same as the bundleID you set on the dashboard.

For Android:

1. Open your Android application settings
2. Copy the value of Package name

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

For iOS:

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

3. Add it to the dashboard too If it is different from your Android Package name

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.

client.PresentConnect()

Add listeners to handle a successful or a failed connection attempt.

client.BankConnectionFailed += (string bankID, string error) =>
{
    Console.WriteLine($"[App] Failed to connect to {bankID} due to {error}");
};

client.BankConnectionSuccessful += async (string bankID, DapiConnection connection) =>
{
    Console.WriteLine($"[App] Connected to {bankID}");
};

client.BankRequested += (string bankName, string iban) =>
{
    Console.WriteLine($"[App] {bankName} requested for user IBAN: {iban}");
};

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.

client.GetConnections() returns the list of connections in cache.

DapiConnection[] connections = await client.GetConnections();

Xamarin 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 toBeneficiary 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.

await connection.CreateTransfer(connection.Accounts.First(), null, 100);

Example - When toBeneficiary 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.

DapiBeneficiary beneficiary = new DapiBeneficiary(
  "EBILAEAD",
  "Emirates NBD Bank PJSC",
  "John Doe",
  "AE140260000959040184901",
  "0959040184901",
  "UNITED ARAB EMIRATES",
  "Emirates NBD Bank PJSC",
  "Baniyas Road Deira PO Box 777 Dubai UAE",
  "0585859206",
  new DapiLinesAddress("baniyas road", "dubai", "united arab emirates")
);
await connection.CreateTransfer(connection.Accounts.First(), beneficiary, 100);

Example - When fromAccount Is Not Specified

await connection.CreateTransfer(null, null, 100);

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

Example - When amount Is Not Specified

await connection.CreateTransfer(connection.Accounts.First());

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

Example - When nothing is specified

await 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

DapiAccount account = connection?.Accounts[0];
DapiResponse<DapiBankBeneficiary[]> beneficiaries = await connection?.GetBeneficiaries();
await connection?.CreateTransferToExistingBeneficiaryFromAccount(
  beneficiaries.Data[0].Id,
  account,
  1,
  "remark"
);

🚧

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

DapiBeneficiary beneficiary = new DapiBeneficiary(
  "EBILAEAD",
  "Emirates NBD Bank PJSC",
  "John Doe",
  "AE140260000959040184901",
  "0959040184901",
  "UNITED ARAB EMIRATES",
  "Emirates NBD Bank PJSC",
  "Baniyas Road Deira PO Box 777 Dubai UAE",
  "0585859206",
  new DapiLinesAddress("baniyas road", "dubai", "united arab emirates")
);

await connection?.CreateBeneficiary(beneficiary);

GetBeneficiaries()

A method for obtaining registered beneficiaries

Parameters

Method does not receive any parameter.

Example

await connection?.GetBeneficiaries();

Metadata Endpoints

GetAccountMetaData()

A method for obtaining bank account metadata

Parameters

Method does not receive any parameter.

Example

await connection?.GetAccountMetadata();

Data Endpoints

GetAccounts()

A method for obtaining and displaying bank accounts of the user

Parameters

Method does not receive any parameter.

Example

await connection.GetAccounts();

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

await connection.GetIdentity();

GetCards()

A method for obtaining and displaying bank cards of the user

Parameters
Method does not receive any parameter.

Example

await connection.GetCards();

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

await connection?.GetTransactions(
  account,
  DateTime.Now.Subtract(TimeSpan.FromDays(60)),
  DateTime.Now.Subtract(TimeSpan.FromDays(2))
);

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

await connection?.GetTransactions(
  card,
  DateTime.Now.Subtract(TimeSpan.FromDays(60)),
  DateTime.Now.Subtract(TimeSpan.FromDays(2))
);

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()
• Prompt the user with Connect screen call client.PresentConnect() to reconnect the bank account. User selects the bank and logs in again.
• Prompt the user with the same bank login screen client.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 DapiEnvironment.Production

DapiClient client = new DapiClient(DependencyService.Get<IDapiPlatformService>());
string[] countries = new string[] { "AE", "EG" };
var configurations = new DapiConfigurations(
  countries,
  DapiEnvironment.Production //Used to be DapiEnvironment.Sandbox
);
await client.StartDapi("APP_KEY", "JohnDoe", configs);

Congratulations, you are all set with your Dapi integration!