NodeJS Library Reference
To get started with the library first install it in your local project using the following command:
npm i @dapi-co/dapi-node
BaseResponse
All the responses extend BaseResponse interface. Meaning all the responses described below in the document will have following parameters besides the ones described in appropriate response sections.
Parameter | Type | Description |
---|---|---|
operationID |
| Unique ID generated to identify a specific operation. |
success |
| Returns |
status |
| The status of the job.
*For further explanation see Operation Statuses |
userInputs |
| Specifies the type of further information required from the user before the job can be completed. Is only returned if operation status is `user_input_required |
type |
| Type of error encountered Is only returned when operation was not successful |
msg |
| Detailed description of the error Is only returned if the request was not successful |
Auth
auth.exchangeToken
Method is used to obtain user's permanent access token by exchanging it with access code received during the user authentication.
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<IExchangeTokenResponse>;
Input Parameters
Parameter | Type | Description |
---|---|---|
accessCode |
| Unique code for a user’s successful login to Connect. Returned in the response of UserLogin. |
connectionID |
| The |
Response
Parameter | Type | Description |
---|---|---|
accessToken |
| A unique permanent token linked to the user. |
Data
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
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Response
Parameter | Type | Description |
---|---|---|
identity |
| An object containing the identity data of the user |
Identity Schema
Parameter | Type | Description |
---|---|---|
nationality |
| User's nationality as reported by the financial institution. |
dateOfBirth |
| User's date (in YYYY-MM-DD format) of birth as reported by the financial institution. |
emailAddress |
| User's email address as reported by the financial institution. |
name |
| User's full name as reported by the financial institution. |
numbers |
| Array of user's phone numbers as provided by the financial institution. |
identification |
| Array of user's identification information as provided by the bank. |
address |
| Object containing user's address information. |
PhoneNumbers Schema
Parameter | Type | Description |
---|---|---|
type |
| The type of number. |
value |
| The user's number as provided by the financial institution. |
Identification Schema
Parameter | Type | Description |
---|---|---|
type |
| Type of document.
|
value |
| User's document number as provided by the financial institution. |
Address Schema
Parameter | Type | Description |
---|---|---|
flat |
| User's flat as provided by the financial institution. |
building |
| User's building as provided by the financial institution. |
full |
| User's full address as provided by the financial institution. |
area |
| User's area as provided by the financial institution. |
poBox |
| User's PO box as provided by the financial institution. |
city |
| User's city as provided by the financial institution. |
state |
| User's state as provided by the financial institution. |
country |
| User's country as provided by the financial institution. |
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, including:
- Savings
- Credit
- Current....
Method Description
async getAccounts(accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
Input Parameters
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Response
Account | Array | An array containing the accounts data of the user. Is only returned if request was successful |
---|
Account Schema
Note
Routing Number object is only returned for USA banks. For all other banks it will not be provided
Parameter | Type | Description |
---|---|---|
iban |
| The account's IBAN number as provided by the financial institution. |
number |
| The account's number as provided by the financial institution. |
name |
| The account's name. |
isFavourite |
| If the account is the user's favourite account. |
id |
| The account's unique identifier. |
currency |
| An object containing the account's currency information. |
routingNumbers |
| An object containing accounts routing numbers information. Is only returned for US Bank Accounts |
type |
| The account type.
|
Routing Numbers Schema
Parameter | Type | Description |
---|---|---|
type | Enum | Type of routing number provided.
|
value |
| Routing number of the account |
Currency Schema
Parameter | Type | Description |
---|---|---|
code |
| The ISO 4217 code of the currency. |
name |
| The full name of the currency. |
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
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
accountID |
| Bank account ID which balance is requested |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Response
Parameter | Type | Description |
---|---|---|
balance |
| Object containing the account's balance information. |
Balance Schema
Parameter | Type | Description |
---|---|---|
amount |
| Current balance of requested account |
accountNumber |
| The account's number as provided by the financial institution. |
currency |
| An object containing the account's currency information. |
Currency Schema
Parameter | Type | Description |
---|---|---|
code |
| The ISO 4217 code of the currency. |
name |
| The full name of the currency. |
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 getAccountTransactions(accessToken: string, userSecret: string, accountID: string, fromDate: Date, toDate: Date, operationID?: string, userInputs?: IUserInputs[])
Input Parameters
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
accountID |
| Bank account ID which balance is requested |
fromDate |
| Date to start transactions from. Format as “YYYY-MM-DD”. |
toDate |
| Date to end transactions on. |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Response
transactions |
| Array containing the transactional data for the specified period. |
---|
Transaction schema
Parameter | Type | Description |
---|---|---|
afterAmount |
| Account balance after this transaction was executed. |
beforeAmount |
| Account balance before the transaction was executed. |
amount |
| Transaction amount. |
date |
| Transaction timestamp as provided by the financial institution (in the financial institution's timezone). |
description |
| Transaction description as provided by the financial institution. |
details |
| Any extra details provided by the financial institution. |
type |
| Specifies if the transaction is debit or credit.
|
currency |
| Object containing the transaction's currency information. |
Currency schema
Parameter | Type | Description |
---|---|---|
code |
| ISO 4217 code of the currency. |
name |
| Currency's full name. |
data.getCards
Method is used to retrieve list of all the cards registered on the user.
Method Description
async getCards(accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
Input Parameters
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Response
Cards | Array | An array containing the cards data of the user. Is only returned if request was successful |
---|
Card Schema
Parameter | Type | Description |
---|---|---|
cardNumber |
| The card's number as provided by the financial institution. |
creditLimit |
| The account's number as provided by the financial institution. |
name |
| The account's name. |
id |
| The account's unique identifier. |
currency |
| An object containing the account's currency information. |
type | Credit | The account type.
|
expiryDate |
| The expiry date of the card |
status |
| The card status:
|
Currency Schema
Parameter | Type | Description |
---|---|---|
code |
| The ISO 4217 code of the currency. |
name |
| The full name of the currency. |
data.getCardBalance
Method is used to retrieve balance on specific card of the user.
Method Description
async getCardBalance(accessToken: string, userSecret: string, cardID: string, operationID?: string, userInputs?: IUserInputs[])
Input Parameters
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
cardID |
| Card ID of the card that the balance is requested for. |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Response
Parameter | Type | Description |
---|---|---|
balance |
| Object containing the account's balance information. |
Balance Schema
Parameter | Type | Description |
---|---|---|
amount |
| Current balance of requested account |
accountNumber |
| The account's number as provided by the financial institution. |
currency |
| An object containing the account's currency information. |
Currency Schema
Parameter | Type | Description |
---|---|---|
code |
| The ISO 4217 code of the currency. |
name |
| The full name of the currency. |
data. getCardTransactions
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).
Method Description
async getCardTransactions(accessToken: string, userSecret: string, cardID: string, fromDate: Date, toDate: Date, operationID?: string, userInputs?: IUserInputs[])
Input Parameters
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
cardID |
| Card ID of the card that the transactions are requested for. |
fromDate |
| Date to start transactions from. Format as “YYYY-MM-DD”. |
toDate |
| Date to end transactions on. |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Response
transactions |
| Array containing the transactional data for the specified period. |
---|
Transaction schema
Parameter | Type | Description |
---|---|---|
afterAmount |
| Account balance after this transaction was executed. |
beforeAmount |
| Account balance before the transaction was executed. |
amount |
| Transaction amount. |
date |
| Transaction timestamp as provided by the financial institution (in the financial institution's timezone). |
description |
| Transaction description as provided by the financial institution. |
details |
| Any extra details provided by the financial institution. |
type |
| Specifies if the transaction is debit or credit.
|
currency |
| Object containing the transaction's currency information. |
Currency schema
Parameter | Type | Description |
---|---|---|
code |
| ISO 4217 code of the currency. |
name |
| Currency's full name. |
Payment
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
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Response
Parameter | Type | Description |
---|---|---|
beneficiaries |
| Returns beneficiary information per beneficiary, such as their name, iban, account number, type, and ID. Is only returned if request was successful |
Beneficiaries schema
Parameter | Type | Description |
---|---|---|
name |
| Beneficiary's name. |
iban |
| Beneficiary's IBAN. *Is returned if |
accountNumber |
| Beneficiary's account number.
|
status |
| Status of beneficiary with the financial institution.
For further explanation see Beneficiary Statuses |
type |
| Type of beneficiary
|
id |
| Beneficiary's unique identifier. |
payment.createBeneficiary
Method is used to add a new beneficiary to enable transfers from the user's account to the beneficiary's.
Method Description
async createBeneficiary(beneficiary: ICBBeneficiary, accessToken: string, userSecret: string, operationID?: string, userInputs?: IUserInputs[])
Input Parameters
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
beneficiary |
| Beneficiary object that should be added |
operationID |
| |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Beneficiary Schema
Parameter | Type | Description |
---|---|---|
name |
| Name of the beneficiary. |
nickname |
| Nickname of the beneficiary. |
accountNumber |
| Account number of the beneficiary. |
type |
| Type of beneficiary.
For further explanation see Beneficiary Types |
address |
| An object containing the address information of the beneficiary. |
country |
| Name of the country in all uppercase letters (e.g. “UNITED ARAB EMIRATES”). |
sortCode |
| Financial institution’s sort code. |
branchAddress |
| Address of the financial institution’s specific branch. |
branchName |
| Name of the financial institution’s specific branch. |
phoneNumber |
| Beneficiary's phone number. |
iban |
| Beneficiary's IBAN number. |
swiftCode |
| Beneficiary's financial institution's SWIFT code. |
addresses |
| Specify which webhook URL(s) defined in app settings to send data to. If empty, an update will be sent to all defined webhook URL(s). |
Address schema
Parameter | Type | Description |
---|---|---|
line1 |
| Street name and number. Note: value should not contain any commas or special characters. |
line2 |
| City name. Note: value should not contain any commas or special characters. |
line3 |
| Country name. Note: value should not contain any commas or special characters. |
Response
Method returns standard Base Response
. You can find description of standard response in the beginning of the document.
payment.createTransfer
Method is used to initiate a new payment from one account to another account.
Important
We suggest you use Transfer Auto Flow method instead to initiate a payment. Auto Flow 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
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
transfer |
| Transfer object containing details of the transaction |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Transfer Schema
Parameter | Type | Description |
---|---|---|
receiverID |
| An identifier for the beneficiary that will receive the money. Obtained from the Get Beneficiaries endpoint. Must be specified if the bank requires receiver to be registered as beneficiary to perform a transaction |
amount |
| Amount of money to be sent. Must be number rounded to up to 2 decimal points. |
senderID |
| An identifier for the bank account the user will send money from. Obtained from the Account - GetAccounts endpoint. |
accountNumber |
| Account number where the transfer must be performed |
name |
| Name of the amount receiver |
iban |
| iban account where the transfer must be performed |
Response
Name | Type | Description |
---|---|---|
reference |
| Transaction reference number 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
accessToken |
| Access Token obtained using Exchange Token method. You can read more about how to obtain a permanent token on Obtain an Access Token |
---|---|---|
userSecret |
| User secret returned during the successful authentication in |
transfer |
| TransferAutoFlow object containing details of the transaction |
operationID |
| The |
userInputs |
| Array of UserInputs object, required only if initial request responded with user inputs specification. You can read more about user inputs specification on Specify User Input |
UserInputs Object
id |
| Type of input required. Can be one of the following:
You can read more about user input types on User Input Types |
---|---|---|
query |
| Textual description of what is required from the user side |
index |
| Is used in case more than one user input is requested. will always be 0 If only one input is requested. |
answer |
| User input that must be submitted. In the response it will always be empty. |
Transfer Schema
Parameter | Type | Description |
---|---|---|
amount |
| Amount of money to be sent. Must be number rounded to up to 2 decimal points. |
senderID |
| An identifier for the bank account the user will send money from. Obtained from the Account - GetAccounts endpoint. |
beneficiary
|
| Beneficiary object containing details where the transaction should be transfered |
Beneficiary Schema
Parameter | Type | Description |
---|---|---|
name |
| Name of the beneficiary. |
nickname |
| Nickname of the beneficiary. |
accountNumber |
| Account number of the beneficiary. |
address |
| An object containing the address information of the beneficiary. |
country |
| Name of the country in all uppercase letters (e.g. “UNITED ARAB EMIRATES”). |
branchAddress |
| Address of the financial institution’s specific branch. |
branchName |
| Name of the financial institution’s specific branch. |
phoneNumber |
| Beneficiary's phone number. |
iban |
| Beneficiary's IBAN number. |
swiftCode |
| Beneficiary's financial institution's SWIFT code. |
addresses |
| Specify which webhook URL(s) defined in app settings to send data to. If empty, an update will be sent to all defined webhook URL(s). |
Address schema
Parameter | Type | Description |
---|---|---|
line1 |
| Street name and number. Note: value should not contain any commas or special characters. |
line2 |
| City name. Note: value should not contain any commas or special characters. |
line3 |
| Country name. Note: value should not contain any commas or special characters. |
Response
Name | Type | Description |
---|---|---|
reference |
| Transaction reference number returned by the bank |
Updated 5 months ago