How to integrate with Xamarin SDK
Follow the guide to set-up Xamarin SDK integration
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
- In Visual Studio, from the project navigator, right-click on your App project > Add > NuGet Package.
- Search for
DapiConnect
. - Click Add Package.
App.Android
- In Visual Studio, from the project navigator, right click on your App.Android project > Add > NuGet Package.
- Search for
DapiConnect.Droid
. - Click Add Package.
- In MainActivity.cs, add
Xamarin.Forms.DependencyService.Register<IDapiPlatformService, DapiPlatformService>();
just beforeLoadApplication(new App());
.
Note: Visual Studio should auto import the following (if not, add them manually):
using DapiConnect;
using DapiConnect.Droid;
App.iOS
- In Visual Studio, from the project navigator, right click on your App.iOS project > Add > NuGet Package.
- Search for
DapiConnect.iOS
. - Click Add Package.
- In AppDelegate.cs, add
Xamarin.Forms.DependencyService.Register<IDapiPlatformService, DapiPlatformService>();
just beforeLoadApplication(new App());
.
Note: Visual Studio should auto import the following (if not, add them manually):
using DapiConnect;
using DapiConnect.iOS;
Start SDK
- Import Dapi
using DapiConnect;
- 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:
- Open your Android application settings
- Copy the value of Package name
- Open your app in the dashboard
- Go to App Settings -> Bundle IDs
- Click on the + icon, paste the copied value and click Submit
For iOS:
- Open your info.plist file
- Copy the value of Bundle Identifier
- 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.
Parameter | Description |
---|---|
toBeneficiary | If you are accepting a transfer into your own company's account, you don't need to set the parameter. You can simply add one in your dashboard under your app. The toBeneficiary will automatically be set to that account. |
fromAccount | Account from where the amount must be transferred. If you don't set a from account, SDK will simply display a popup screen for your user to pick the account from our UI. If you do provide a from object, this screen won't be displayed. |
amount | Amount to be transferred. If you don't set an amount SDK will display a screen with a numpad screen for your user to enter the amount in. |
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
Parameter | Description |
---|---|
fromAccount | Account from where the amount must be transferred. |
toBeneficiaryID | The id of the beneficiary to which the money must be transferred. Obtain by connection.getBeneficiaries() |
amount | Amount to be transferred |
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
Parameter | Description |
---|---|
beneficiary | Information of the beneficiary to add. |
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
Parameter | Description |
---|---|
account | Account from where the transaction was performed |
fromDate | Start date of transactions history range |
toDate | End date of transactions history range |
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
Parameter | Description |
---|---|
card | Card from where the transaction was performed |
fromDate | Start date of transactions history range |
toDate | End date of transactions history range |
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
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!
Updated 10 months ago