DAPI Node

Introduction

The DAPI Node is a library that runs as part of your backend and handles communication between your backend and the Dapi API ().

Library Setup

This repo contains the source code of the library. To build the library, run the below script:

``
npm run build
`

This will create a folder called lib in the folder.

$3

I have included an example folder to make it wasy for any developer to play with this library. But since this example is in ts, you will have to compile the ts to js and then run the js output file. To do this run the below script

`sh
tsc ./example/Client.ts && node ./example/Client.js
`

> _Note:_ For the above script to work, you need to install typescript globally on your system.
>
> sh npm install -g typescript

DAPI API

A list of all options on the DAPI Node that your backend can call to perform some operations.

- _Auth Product:_

auth.exchangeToken

- _Data Product:_

data.getIdentity

data.getAccounts

data.getCompleteAccounts

data.getAccountBalance

data.getAccountTransactions

data.getCards

data.getCardBalance

data.getCardTransactions

- _Payment Product:_

payment.getBeneficiaries

payment.createBeneficiary

payment.createTransfer

payment.transferAutoFlow

- _Metadata Product:_

metadata.getAccounts

Reference

$3

All the responses have the fields described here. Meaning all the responses described below in the document will have following fields besides the ones specific to each response.

| Parameter | Type | Description |
| ----------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operationID | string | Unique ID generated to identify a specific operation. |
| success | boolean | Returns true if request is successful and false otherwise." |
| status | string | The status of the job.

done - Operation Completed.
failed - Operation Failed.
user_input_required - Pending User Input.
initialized - Operation In Progress.

For further explanation see Operation Statuses. |
| userInputs | IUserInput[] | Array of IUserInput objects, that are needed to complete this operation.

Specifies the type of further information required from the user before the job can be completed.

Note: It's only returned if operation status is user_input_required |
| type | string | Type of error encountered.

Note: It's only returned if operation status is failed |
| msg | string | Detailed description of the error.

Note: It's only returned if operation status is failed |

#### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| query | string | Textual description of what is required from the user side. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. In the response it will always be empty. |

$3

#### auth.exchangeToken

Method is used to obtain user's permanent access token by exchanging it with access code received during the user authentication (user login).

##### Note:

You can read more about how to obtain a permanent token on Obtain an Access Token.

##### Method Description

`
async exchangeToken(accessCode: string, connectionID: string): Promise
`

##### Input Parameters

| Parameter | Type | Description |
| -------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| accessCode
_REQUIRED_ | string | Unique code for a user’s successful login to Connect. Returned in the response of UserLogin. |
| connectionID
_REQUIRED_ | string | The connectionID from a user’s successful log in to Connect. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be returned if the status is done:

| Parameter | Type | Description |
| --------------- | -------- | -------------------------------------------- |
| accessToken | string | A unique permanent token linked to the user. |

---

#### data.getIdentity

Method is used to retrieve personal details about the user.

##### Method Description

`
async getIdentity(accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be returned if the status is done:

| Parameter | Type | Description |
| --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| identity | IIdentity | An object containing the identity data of the user.

For the exact schema of the identity object, see Identity schema. |

---

#### data.getAccounts

Method is used to retrieve list of all the bank accounts registered on the user. The list will contain all types of bank accounts.

##### Method Description

`
async getAccounts(accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be returned if the status is done:

| Parameter | Type | Description |
| --------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accounts | IAccount[] | An array containing the accounts data of the user.

For the exact schema of the accounts array, see Account schema. |

---

#### data.getCompleteAccounts

Method is used to retrieve list of all the bank accounts registered on the user, with the balance of each account inside it. The list will contain all types of bank accounts.

##### Method Description

`
async getCompleteAccounts(accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be returned if the status is done:

| Parameter | Type | Description |
| --------- | ------------ |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| accounts | IAccount[] | An array containing the accounts data of the user.

For the exact schema of the accounts array, see Account schema.|

---

#### data.getAccountBalance

Method is used to retrieve balance on specific bank account of the user.

##### Method Description

`
async getAccountBalance(accessToken: string, userSecret: string, accountID: string, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accountID
_REQUIRED_ | string | The bank account ID which its balance is requested.
Retrieved from one of the accounts returned from the GetAccounts method. |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be valid if the status is done:

| Parameter | Type | Description |
| --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| balance | IBalance | An object containing the account's balance information.

For the exact schema of the balance object, see Balance schema. |

---

#### data.getAccountTransactions

Method is used to retrieve transactions that user has performed over a specific period of time from their bank account. The transaction list is unfiltered, meaning the response will contain all the transactions performed by the user (not just the transactions performed using your app).

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.

##### Method Description

`
async getTransactions(accessToken: string, userSecret: string, accountID: string, fromDate: Date, toDate: Date, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accountID
_REQUIRED_ | string | The bank account ID which its balance is requested.
Retrieved from one of the accounts returned from the GetAccounts method. |
| fromDate
_REQUIRED_ | Date | The start date of the transactions wanted.
It should be in this format YYYY-MM-DD. |
| toDate
_REQUIRED_ | Date | The end date of the transactions wanted.
It should be in this format YYYY-MM-DD. |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be valid if the status is done:

| Parameter | Type | Description |
| ------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| transactions | ITransaction[] | Array containing the transactional data for the specified account within the specified period.

For the exact schema of the transactions array, see Transaction schema. |

---

#### payment.getBeneficiaries

Method is used to retrieve list of all the beneficiaries already added for a user within a financial institution.

##### Method Description

`
async getBeneficiaries(accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be returned if the status is done:

| Parameter | Type | Description |
| ------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| beneficiaries | IBeneficiary[] | An array containing the beneficiary information.

For the exact schema of the beneficiaries array, see Beneficiary schema. |

---

#### payment.createBeneficiary

Method is used to create a Beneficiary for a user within a financial institution.

##### Method Description

`
async createBeneficiary(beneficiary: ICBBeneficiary, accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| beneficiary
_REQUIRED_ | ICBBeneficiary | An object that contains info about the beneficiary that should be added. |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

##### Response

Method returns only the fields defined in the BaseResponse.

---

#### payment.createTransfer

Method is used to initiate a new payment from one account to another account.

##### Important

We suggest you use transferAutoflow method instead to initiate a payment. transferAutoflow abstracts all the validations and processing logic, required to initiate a transaction using createTransfer method.

You can read about transferAutoflow further in the document.

##### Method Description

`
async createTransfer(transfer: ITransfer, accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| transfer
_REQUIRED_ | ITransfer | An object that contains info about the transfer that should be initiated. |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

###### ITransfer Object

| Parameter | Type | Description |
| --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| senderID
_REQUIRED_ | string | The id of the account which the money should be sent from.
Retrieved from one of the accounts array returned from the getAccounts method. |
| amount
_REQUIRED_ | number | The amount of money which should be sent. |
| receiverID
_OPTIONAL_ | string | The id of the beneficiary which the money should be sent to.
Retrieved from one of the beneficiaries array returned from the getBeneficiaries method.
Needed only when creating a transfer from a bank that requires the receiver to be already registered as a beneficiary to perform a transaction. |
| name
_OPTIONAL_ | string | The name of receiver.
Needed only when creating a transfer from a bank that handles the creation of beneficiaries on its own, internally, and doesn't require the receiver to be already registered as a beneficiary to perform a transaction. |
| accountNumber
_OPTIONAL_ | string | The Account Number of the receiver's account.
Needed only when creating a transfer from a bank that handles the creation of beneficiaries on its own, internally, and doesn't require the receiver to be already registered as a beneficiary to perform a transaction. |
| iban
_OPTIONAL_ | string | The IBAN of the receiver's account.
Needed only when creating a transfer from a bank that handles the creation of beneficiaries on its own, internally, and doesn't require the receiver to be already registered as a beneficiary to perform a transaction. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be returned if the status is done:

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------- |
| reference | string | Transaction reference string returned by the bank. |

---

#### payment.transferAutoflow

Method is used to initiate a new payment from one account to another account, without having to care nor handle any special cases or scenarios.

##### Method Description

`
async transferAutoFlow(transfer: ITransferAutoflow, accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
`

##### Input Parameters

| Parameter | Type | Description |
| ------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| transfer
_REQUIRED_ | ITransferAutoflow | An object that contains info about the transfer that should be initiated, and any other details that's used to automate the operation. |
| accessToken
_REQUIRED_ | string | Access Token obtained using the exchangeToken method. |
| userSecret
_REQUIRED_ | string | The userSecret from a user’s successful log in to Connect. |
| operationID
_OPTIONAL_ | string | The operationID from a previous call's response.
Required only when resuming a previous call that responded with user_input_required status, to provided user inputs. |
| userInputs
_OPTIONAL_ | IUserInputs[] | Array of IUserInputs objects, that are needed to complete this operation.
Required only if a previous call responded with user_input_required status.

You can read more about user inputs specification on Specify User Input |

###### UserInput Object

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Type of input required.

You can read more about user input types on User Input Types. |
| index | number | Is used in case more than one user input is requested.
Will always be 0 If only one input is requested. |
| answer | string | User input that must be submitted. |

###### ITransferAutoflow Object

| Parameter | Type | Description |
| ------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| senderID
_REQUIRED_ | string | The id of the account which the money should be sent from.
Retrieved from one of the accounts array returned from the getAccounts method. |
| amount
_REQUIRED_ | number | The amount of money which should be sent. |
| beneficiary
_REQUIRED_ | IBeneficiary | An object that holds the info about the beneficiary which the money should be sent to. |

##### Response

In addition to the fields described in the BaseResponse, it has the following fields, which will only be returned if the status is done:

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------------- |
| reference | string` | Transaction reference string returned by the bank. |

---