Accounts

Suggest Edits

Accounts are the entities that hold the balances of your clients. Each account is connected to a single service provider. A unique identifier, called the Ledger Number, is assigned to each account regardless of the provider or type of account.

Account Alias

The alias of an account is optional and can be set at creation. It's there for labelling and differentiation between more than one account in the same currency. For example, one use case might be setting the alias of the first EUR account as "Salary Account" and setting the second one as "Investment Funds". Note: Aliases do not have to be unique. If an alias is not set when creating an account it is set to default to "{currency} Account" (e.g. "EUR Account").

Create an Account

POST /accounts
There is a single workflow to create an account.

1. Issuing: You can ask for an account to be opened at a specific service provider of your choice. If this is the first account created for this client at the selected service provider, the client might be required to be created at the service provider first depending on the service provider’s workflows.

{
  "workflow": {
    "code": "client.issuing"
  },
  "data": {
    "account": {
      "clientId": "00000000-0000-0000-0000-000000000000",
      "currency": "EUR",
      "alias": "EUR Account"
    }
  },
  "connect": {
    "type": "explicit",
    "serviceProvider": "railsbank"
  },
  "metadata": {}
}

{
  "workflow": {
    "code": "client.issuing"
  },
  "data": {
    "account": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "status": "pending",
      "country": "GB",
      "currency": "EUR",
      "alias": "EUR Account",
      "routingCodes": {},
      "iban": null,
      "accountNumber": null,
      "ledgerNumber": "12345678",
      "availableBalance": 0,
      "serviceProvider": "railsbank",
      "accountHolderName": "Sherlock Holmes",
      "accountHolderIdentityType": "individual"
    }
  },
  "connect": {
    "type": "explicit",
    "serviceProvider": "railsbank"
  },
  "metadata": {}
}
  1. Migration: You can migrate an existing account at a service provider. To migrate an account, the client must be migrated first and then the account must be created in an active state. If the service provider has an equivalent resource to the client, the account is validated if it's owned by the client in the migration request. The migration endpoint also asks for the currency of the account to validate it against the currency available at the service provider.
{
  "workflow": {
    "code": "client.migration"
  },
  "data": {
    "account": {
      "clientId": "00000000-0000-0000-0000-000000000000",
      "currency": "EUR",
      "alias": "EUR Account"
    },
    "sourceId": "00000000-0000-0000-0000-000000000000"
  },
  "connect": {
    "type": "explicit",
    "serviceProvider": "railsbank"
  },
  "metadata": {}
}

{
  "workflow": {
    "code": "client.migration"
  },
  "data": {
    "account": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "status": "active",
      "country": "GB",
      "currency": "EUR",
      "alias": "EUR Account",
      "routingCodes": {},
      "iban": null,
      "accountNumber": null,
      "ledgerNumber": "12345678",
      "availableBalance": 0,
      "serviceProvider": "railsbank",
      "accountHolderName": "Sherlock Holmes",
      "accountHolderIdentityType": "individual"
    }
  },
  "connect": {
    "type": "explicit",
    "serviceProvider": "railsbank"
  },
  "metadata": {}
}
  1. Sub-account: You can create sub-accounts linked to a main account. There can only be a single layer of sub-accounts, nested subaccounts linked to another sub-account are not supported. Please contact your solution consultant to use subaccounts in you financial flows.
{
  "workflow": {
    "code": "client.sub-account"
  },
  "data": {
    "account": {
        "clientId": "00000000-0000-0000-0000-000000000000",
        "currency": "EUR",
        "alias": "EUR Account",
        "mainAccountId": "00000000-0000-0000-0000-000000000000"
    }
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "client.sub-account"
  },
  "data": {
    "account": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "status": "pending",
      "country": "GB",
      "currency": "EUR",
      "alias": "EUR Account",
      "ledgerNumber": "12345678",
      "availableBalance": 0,
      "serviceProvider": null,
      "mainAccountId": "00000000-0000-0000-0000-000000000000",
      "accountHolderName": "Sherlock Holmes",
      "accountHolderIdentityType": "individual"
    }
  },
  "connect": {},
  "metadata": {}
}

Update an Account

PATCH /accounts/{accountId}
There is a single workflow to update an account

  1. Direct: These fields can be updated using the direct workflow.
    • alias
    • iban
    • accountNumber
    • status **
    • routingCodes *
      Fields other than alias can only be updated if the account is not integrated by IF. Once wanted to update iban / accountNumber / routingCodes, also status should be updated. Once the status is already "active", then no need to send the status field again.
      * Details on routing codes: https://developer.integrated.finance/docs/beneficiary-bank-accounts#routing-code-types
      ** Status can be changed to active just from pending.
{
  "workflow": {
    "code": "client.direct"
  },
  "data": {
    "account": {
        "alias": "EUR Account"
    }
  },
  "connect": {},
  "metadata": {}
}

{
    "workflow": {
        "code": "client.direct"
    },
    "data": {
        "account": {
            "alias": "EUR Account",
            "accountNumber": "12345678",
            "iban": "GB85LOYD77913045276224",
            "routingCodes": {
                "sort-code": "123456"
            },
            "status": "active"
        }
    },
    "connect": {},
    "metadata": {}
}

Get an Account

Endpoints with GET do not include workflows, however you can use metadata parameters to shape the response.

GET /accounts/{accountId}?metadata.include=connect.connection 

{
  "workflow": {},
  "data": {
    "account": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "status": "active",
      "country": "GB",
      "currency": "EUR",
      "alias": "EUR Account",
      "routingCodes": {},
      "iban": null,
      "accountNumber": null,
      "ledgerNumber": "12345678",
      "availableBalance": 0,
      "serviceProvider": "railsbank",
      "accountHolderName": "Sherlock Holmes",
      "accountHolderIdentityType": "individual"
    }
  },
  "connect": {
    "connection": {
      "id": "5ffc8b9c-3073-4625-a55b-4ae69d657cc3",
      "serviceProvider": "railsbank"
    }
  },
  "metadata": {}
}

{
  "workflow": {},
  "data": {
    "account": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "mainAccountId": "00000000-0000-0000-0000-000000000000",
      "status": "active",
      "country": "GB",
      "currency": "EUR",
      "alias": "EUR Account",
      "routingCodes": {},
      "iban": null,
      "accountNumber": null,
      "ledgerNumber": "12345678",
      "availableBalance": 0,
      "serviceProvider": "railsbank",
      "accountHolderName": "Sherlock Holmes",
      "accountHolderIdentityType": "individual"
    }
  },
  "connect": {},
  "metadata": {}
}

You can find a list of valid metadata.include parameters below

KeyDescription
connect.connectionIncludes information about provider connection of the account.

GET /accounts/{accountId}?metadata.expand=data.account.clientId 

{
  "workflow": {},
  "data": {
    "account": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "status": "active",
      "country": "GB",
      "currency": "EUR",
      "alias": "EUR Account",
      "routingCodes": {},
      "iban": null,
      "accountNumber": null,
      "ledgerNumber": "12345678",
      "availableBalance": 0,
      "serviceProvider": "railsbank",
      "accountHolderName": "Sherlock Holmes",
      "accountHolderIdentityType": "individual"
    },
    "client": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientNumber": "00000000",
      "status": "active",
      "identity": {
        "type": "individual",
        "country": "GB",
        "identificationNumbers": {
          "passport": "",
          "identity-card": "",
          "driving-licence": ""
        },
        "identifications": null,
        "givenName": "Sherlock",
        "familyName": "Holmes",
        "birthDate": "1987-01-01"
      },
      "fullName": "Sherlock Holmes"
    }
  },
  "connect": {},
  "metadata": {}
}

You can find a list of valid matadata.expand parameters below

KeyDescription
data.account.clientIdExpands client information of the account.

List Accounts

GET /accounts

Supported query parameters:

parameterdescription
metadata.page.number0-indexed, default=0
metadata.page.sizedefault=10
data.account.clientIdUUID of client
data.account.statusone of pending, active, inactive, suspended, closed, declined
data.account.currencyISO 4217 currency code
data.account.aliasFree text account alias
data.account.routingCodeKey
data.account.routingCodeValue
data.account.iban
data.account.accountNumber
data.account.ledgerNumber
data.account.availableBalanceFrom
data.account.availableBalanceTo
data.account.serviceProvider
data.account.accountHolderName
data.account.mainAccountIdmain account id as UUID
{
  "workflow": {},
  "data": {
    "accounts": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "clientId": "00000000-0000-0000-0000-000000000000",
        "status": "pending",
        "country": "GB",
        "currency": "EUR",
        "alias": "EUR Account",
        "routingCodes": {},
        "iban": null,
        "accountNumber": null,
        "ledgerNumber": "12345678",
        "availableBalance": 0,
        "serviceProvider": "railsbank",
        "accountHolderName": "Sherlock Holmes",
        "accountHolderIdentityType": "individual"
      },
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "clientId": "00000000-0000-0000-0000-000000000000",
        "mainAccountId": "00000000-0000-0000-0000-000000000000",
        "status": "pending",
        "country": "GB",
        "currency": "EUR",
        "alias": "EUR Account",
        "routingCodes": {},
        "iban": null,
        "accountNumber": null,
        "ledgerNumber": "12345678",
        "availableBalance": 0,
        "serviceProvider": "railsbank",
        "accountHolderName": "Sherlock Holmes",
        "accountHolderIdentityType": "individual"
      }
    ]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 10,
      "totalElements": 100,
      "totalPages": 10,
      "number": 0
    }
  }
}

Get Account Deposit Information

GET /accounts/{id}/deposit-information

Details of deposit information might be different from the information provided in the account itself. This usually occurs when the account is a pooled account and a reference is required for inbound transfers. The account itself doesn't show all the data from the pooled account since not all the information belongs to the client's accounts. To get that information for deposits, this endpoint needs to be queried.

IF accounts can be funded by using the deposit information provided for each scheme (defined below). The deposit information returns a JSON map where scheme codes are used as keys.

  1. SWIFT: Accounts can be funded using international transfers if the underlying service provider of the account supports inbound SWIFT transfers. The BIC (which is available in routing codes) and IBAN/Account Number (depending on the country) should be provided for international transfers.

  2. Local Transfer Schemes: Accounts can be funded using a local transfer method if the underlying service provider of the account supports inbound local transfers in the currency of the account. A local routing code (e.g. Sort-Code for UK, ABA for US) and IBAN/Account Number (depending on the country) should be provided for local transfers.

  3. Internal: Accounts can be funded using the IF internal transfers feature using the unique ledger number generated by the IF Platform.

{
  "workflow": {},
  "data": {
    "depositInformation": {
      "chaps": {
        "accountHolderName": "",
        "country": "GB",
        "currency": "GBP",
        "routingCodes": {
          "sort-code": "000000"
        },
        "accountNumber": "00000000",
        "iban": "GB99AAAA01234567890123",
        "ledgerNumber": null,
        "reference": null,
        "bankName": null,
        "bankAddress": null,
        "intermediaryAccount": null
      },
      "faster-payments": {
        "accountHolderName": "",
        "country": "GB",
        "currency": "GBP",
        "routingCodes": {
          "sort-code": "000000"
        },
        "accountNumber": "00000000",
        "iban": "GB99AAAA01234567890123",
        "ledgerNumber": null,
        "reference": null,
        "bankName": null,
        "bankAddress": null,
        "intermediaryAccount": null
      },
      "swift": {
        "accountHolderName": "",
        "country": "GB",
        "currency": "GBP",
        "routingCodes": {
          "bic": "AAAAGB20XXX"
        },
        "accountNumber": "00000000",
        "iban": "GB99AAAA01234567890123",
        "ledgerNumber": null,
        "reference": null,
        "bankName": "Payrnet",
        "bankAddress": null,
        "intermediaryAccount": {
          "accountHolderName": null,
          "country": "GB",
          "currency": "EUR",
          "routingCodes": {
            "bic": "AAAAGB22"
          },
          "accountNumber": null,
          "iban": null,
          "ledgerNumber": null,
          "reference": null,
          "bankName": "Example Bank",
          "bankAddress": null,
          "intermediaryAccount": null
        }
      },
      "internal": {
        "accountHolderName": "",
        "country": "GB",
        "currency": "GBP",
        "routingCodes": {},
        "accountNumber": null,
        "iban": null,
        "ledgerNumber": "12345678",
        "reference": null,
        "bankName": null,
        "bankAddress": null,
        "intermediaryAccount": null
      }
    }
  },
  "connect": {},
  "metadata": {}
}

Create Account Balance Adjustment

POST /accounts/{id}/balance-adjustments - This endpoint is DEPRECATED, please refer to Generic Transactions

Account balance adjustments update the account balance directly. There are various circumstances in which a Balance Adjustment may need to be created. It might be needed for example, to fix a system error or a user mistake (e.g a mistake in pricing definition) or to synchronize a transaction that has occurred outside of the IF Platform (e.g a non-integrated bank). Balance adjustments do not have different statuses. On creation of a balance adjustment the only status can be ‘Completed’.

There are two independent workflows of account balance adjustments:
1. Correction: There are two types of corrections; fee and unknown.
Fee corrections are treated as revenues of other transactions. If there is an automation to sweep the fees periodically, these corrections are included in those sweeps.
Unknown corrections are not reflected to underlying service provider.

{
  "workflow": {
    "code": "correction",
    "type": "fee",
    "transactionType": "incoming-transfer"
  },
  "data": {
    "balanceAdjustment": {
      "accountId": "00000000-0000-0000-0000-000000000000",
      "direction": "debit",
      "amount": 10,
      "currency": "GBP",
      "description": "free text"
    }
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "correction",
    "type": "fee",
    "transactionType": "incoming-transfer"
  },
  "data": {
    "balanceAdjustment": {
      "id": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "direction": "debit",
      "transactionNumber": "20210414-ABCDEF",
      "amount": 10,
      "currency": "GBP",
      "description": "fee reversal"
    }
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "correction",
    "type": "fee",
    "transactionType": "unconnected-service-provider"
  },
  "data": {
    "balanceAdjustment": {
      "accountId": "00000000-0000-0000-0000-000000000000",
      "direction": "debit",
      "amount": 10,
      "currency": "GBP",
      "description": "free text",
      "unconnectedServiceProvider": "gps"
    }
  },
  "connect": {},
  "metadata": {}
}
  1. Synchronization: This workflow reflects a transaction that physically occurred but wasn’t recorded on the IF Platform. type can only be unconnected-service-provider and code of unconnected service provider must be included in data section.
{
  "workflow": {
    "code": "synchronization",
    "type": "unconnected-service-provider"
  },
  "data": {
    "balanceAdjustment": {
      "accountId": "00000000-0000-0000-0000-000000000000",
      "direction": "debit",
      "amount": 10,
      "currency": "GBP",
      "description": "card payment",
      "unconnectedServiceProvider": "gps"
    }
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "synchronization",
    "type": "unconnected-service-provider"
  },
  "data": {
    "balanceAdjustment": {
      "id": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "direction": "debit",
      "transactionNumber": "20210414-ABCDEF",
      "amount": 10,
      "currency": "GBP",
      "description": "card payment",
      "unconnectedServiceProvider": "gps"
    }
  },
  "connect": {},
  "metadata": {}
}

Get Account Statements

GET /accounts/{accountId}/account-statements

Listing account statement with request filter parameters.

parameterdescription
metadata.page.numberRequested page number: 0-indexed, default=0
metadata.page.sizeNumber of entries for each page: default=10
data.accountStatement.transactionNumberTransaction number for a specific statement record.
format: 20201231-QWERTY
data.accountStatement.entryDateTimeFromTransaction entry in range from date.
format: 2020-12-31T00:00:00.000
data.accountStatement.entryDateTimeToTransaction entry in range to date.
format: 2020-12-31T00:00:00.000
  • Default date range is the current month's from first day to last day.
  • If fromDate is given and toDate is empty, then default toDate is the last day of the fromDate's month.
  • If toDate is given and fromDate is empty, then default fromDate is the first day of the toDate's month.
{
  "workflow": {},
  "data": {
    "accountStatements": [
      {
        "accountId": "00000000-0000-0000-0000-000000000000",
        "transactionNumber": "20210101-ABC123",
        "entryDateTime": "2021-09-13T11:13:19.168",
        "direction": "debit",
        "amount": 10.00,
        "transactionType": "incoming",
        "entryType": "fee",
        "balance": 100.00,
        "currency": "TRY",
        "narrative": "Transfer fee for 20210101-ABC123"
      }
    ]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 20,
      "number": 0,
      "totalElements": 200,
      "totalPages": 10
    }
  }
}

Enum values of Account Statements:

Field CodePossible Values
directiondebit, credit
transactionTypeincoming-transfer, outgoing-transfer, exchange-transaction, balance-adjustment
entryTypeincoming-transfer: principal, fee

outgoing-transfer: principal, fee

exchange-transaction: principal-sell, principal-buy, fee, cancellation-fee

balance-adjustment: principal

Accounts statements are ordered by entryDateTime in ascending order.

Webhooks

Account webhooks have "accounts" in the module field in the webhook container object.

There are 6 types of webhooks sent for accounts:

  • account-activated
  • account-inactivated
  • account-suspended
  • account-closed
  • account-declined
  • account-information-updated

These types are exposed in the webhook.type field.

The connection section is optional, it will be available if an account is created at a Service Provider successfully.

Fields listed below can only be updated if type of webhook is either account-activated or account-information-updated:

  • country
  • routingCodes (and content of it)
  • iban
  • accountNumber
{
  "webhook": {
    "module": "accounts",
    "type": "account-activated"
  },
  "data": {
    "account": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "status": "active",
      "country": "GB",
      "currency": "GBP",
      "alias": "GBP Account",
      "routingCodes": {
        "sort-code": "123456"
      },
      "iban": null,
      "accountNumber": "12345678",
      "ledgerNumber": "12345678",
      "availableBalance": 0,
      "serviceProvider": "railsbank",
      "accountHolderName": "Sherlock Holmes",
      "accountHolderIdentityType": "individual"
    }
  },
  "connect": {
    "connection": {
      "id": "5ffc8b9c-3073-4625-a55b-4ae69d657cc3",
      "serviceProvider": "railsbank"
    }
  },
  "metadata": {}
}

Updated about 2 months ago