Skip to content

Accounts 🏦

This file will explain how to add and manage bank accounts in Yoli. If you are using the Yoli API without a connected bank account and want to update your users manually, jump to the Using Yoli without a Bank Account section.

Syncing

By default the information and transactions of already added accounts will be synced every few hours. (Note that some banks only refresh their online banking data much less often than that, which unfortunately can't be worked around).

If you want to manually force a sync (i.e. for a pull to refresh gesture in clients), you can use the updateAccounts and updateContracts mutations. There's also the updateUser mutation to do both in one go.

Multiple Accounts Behind One Login

Due to the nature of banks, there actually might be more than one bank account behind single set of online-banking credentials.

For example a user might have a normal account, a daily savings account and a partner account, all behind a single login.

This adds complexity, as we cannot simply remove a single account from being periodically synced without also removing the rest. (More info in the relevant section)

Adding a Bank Account

To add a bank account you need to be properly authenticated.

Initiating a Bank Login

Use the addBankAccount mutation with appropriate bank identifier and credentials to initiate a bank login.

mutation {
  addBankAccount(bankCode: "90090042", credentials: ["demo", "demo"])
}
{
  "data": {
    "addBankAccount": "<task token>"
  }
}

Due to the complex nature of bank login systems this process may take up to a few minutes and may error in a lot of steps in between.

To make handling this easier and eliminate the need for a constant internet connection, every started login will give you a so called "task token", with which you can check on the state of the login and extract information on why it may have failed.

Note that contained in each bank login is also an initial analysis of the accounts' contracts.

Bank Login Status

You can check on the status of a bank login by using the bankLoginStatus. The status field will either be pending, success or failed. To get more on information on why a login failed you use the message and providerError fields.

{
  bankLoginStatus(taskToken: "<task token>") {
    status
    message
  }
}
{
  "data": {
    "bankLoginStatus": {
      "status": "failed",
      "message": "BankLogin for User already exists"
    }
  }
}

Since a user can have multiple accounts in his bank account, the bank login that has been inititated with addBankAccount will remain in the pending state until one or multiple accounts have been selected with selectAccount.

{
  #select all accounts
  selectAccount(taskToken: "<task token>")
}
{
  #select specific accounts
  selectAccount(taskToken: "<task token>", accountIds:["<account Id 1>", "<account Id 2>"])
}

The returning result contains a selectAccount field with true if the selection was successful.

{
  "data": {
    "selectAccount": true
  }
}

You can add the availableAccounts array field to the bankLoginStatus query in order to retrieve the account Ids.

{
  bankLoginStatus(taskToken: "<task token>") {
    status
    message
    availableAccounts {
      accountId
    }
  }
}
{
  "data": {
    "bankLoginStatus": {
      "status": "success",
      "message": null,
      "availableAccounts": [
        {
          "accountId": "<account id>"
        }
      ]
    }
  }
}

Managing Bank Accounts

Customizing a Bank Account

You may want to add new or modified information to existing bank accounts. This can be done with the customizeAccount mutation.

mutation {
  customizeAccount(accountId: "<account id>", customName: "Regenbogen Konto")
}

Removing a Single Account

If you want to only remove a single account from the accounts behind a set of credentials, you can hide that account.

This will prevent it from being considered in any backend operation or frontend query except when explicitly asked.

To achieve this you can use the customizeAccount mutation and set the hidden field to true.

mutation {
  customizeAccount(accountId: "<account id>", hidden: true)
}

Removing a Bank Login

Removing a bank login (a set of credentials) will prevent these accounts from being synced and remove all their associated data.

Just use the removeBankAccount mutation to achieve this.

mutation {
  removeBankAccount(bankLoginId: "<bank login id")
}

Using Yoli without a Bank Account

Update Transactions

In order to update your contracts, smart alerts, etc. manually, simply use the updateTransactions mutation. Yoli will synchronize your user's data without saving the transactions to a bank account.

Attention: To guarantee seamless functionality of all features of the Yoli API, the accountId and transactionId fields should be unique and continous. Otherwise, you might experience faulty behaviour of the contracts feature i.e.

mutation {
  updateTransactions(defaultInterval: "MONTHLY", transactions: [
    {
      "paymentPartner": {
        "name": "Fino Digital"
      },
      "accountId": "ua4kUE8z1195",
      "amount": 210748,
      "dateOfTransaction": "2018-10-05T14:48:00.000Z",
      "purpose": "Gehalt Oktober 2018",
      "transactionCode": 999,
      "transactionId": "p4iBJ89M583afaF28rSuPJwF2"
    },
    {
      "paymentPartner": {
        "name": "Fino Digital"
      },
      "accountId": "ua4kUE8z1195",
      "amount": 210748,
      "dateOfTransaction": "2018-11-05T14:48:00.000Z",
      "purpose": "Gehalt November 2018",
      "transactionCode": 999,
      "transactionId": "eQzjT8mOWy6eEzsiajP431O7H"
    }
  ])
}