Client Accounts
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 labeling 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"). Please be aware there is a 30 character limit on alias length.
Connect Method
The connect method of an account is optional and set at creation. The default method value is "built-in" which means the integration to service provider is managed by the IF platform. Also, there is another method value called "plug-in". The plug-in method is used when the integration to service provider is not managed by the IF platform. Using this method, accounts on IF platform are used as ledgers. If a connect method is not set when creating an account, it defaults to "built-in".
Create an Account
POST /accounts
There is a single workflow to create an account.
Connect Type
Connect type "explicit" means the service provider was given in the request while account creation and "implicit" means determining the appropriate service provider by the IF system. If the connect method is "plug-in" then connect type must be "explicit" and if the connect method is "built-in" then connect type can be "implicit" or "explicit".
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":{
"method":"built-in",
"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",
"connection":{
"id":null,
"method":"built-in",
"serviceProvider":"railsbank",
"reference":null,
"state":"creation-in-progress",
"status":null,
"error":null
}
}
},
"connect":{
"method":"built-in",
"type":"explicit",
"serviceProvider":"railsbank"
},
"metadata":{}
}
{
"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",
"connection":{
"id":null,
"method":"built-in",
"serviceProvider":"railsbank",
"reference":null,
"state":"creation-in-progress",
"status":null,
"error":null
}
}
},
"connect":{
"method":"built-in",
"type":"explicit",
"serviceProvider":"railsbank"
},
"metadata":{
}
}
{
"workflow":{
"code":"client.issuing"
},
"data":{
"account":{
"clientId":"00000000-0000-0000-0000-000000000000",
"country":"GB",
"currency":"EUR",
"alias":"EUR Account"
}
},
"connect":{
"method":"plug-in",
"type": "explicit",
"serviceProvider":"revolut"
},
"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":null,
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection": {
"id":null,
"method":"plug-in",
"serviceProvider":"revolut",
"reference":null,
"state":"creation-in-progress",
"status":null,
"error":null
}
}
},
"connect":{
"method":"plug-in",
"type": "explicit",
"serviceProvider":"revolut",
},
"metadata":{}
}
- Migration: You can migrate an existing account to 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",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"built-in",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
}
},
"connect":{
"method":"built-in",
"type":"explicit",
"serviceProvider":"railsbank"
},
"metadata":{}
}
{
"workflow":{
"code":"client.migration"
},
"data":{
"account":{
"clientId":"00000000-0000-0000-0000-000000000000",
"currency":"EUR",
"alias":"EUR Account"
},
"sourceId":"00000000-0000-0000-0000-000000000000"
},
"connect":{
"method":"built-in",
"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",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"built-in",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
}
},
"connect":{
"method":"built-in",
"type":"explicit",
"serviceProvider":"railsbank"
},
"metadata":{
}
}
- Sub-account: You can create sub-accounts linked to a main account. There can only be a single layer of sub-accounts, nested sub-accounts linked to another sub-account are not supported. Please contact your solution consultant to use sub-accounts in your 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
-
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, the status should also 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 as per diagram below.
{
"workflow":{
"code":"client.direct"
},
"data":{
"account":{
"alias":"EUR Account 2",
"status":"closed"
}
},
"connect": {},
"metadata":{}
}
{
"workflow": {
"code": "client.direct"
},
"data": {
"account": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"status": "closed",
"country": "GB",
"currency": "EUR",
"alias": "EUR Account 2",
"routingCodes": {},
"iban": null,
"accountNumber": null,
"ledgerNumber": "12345678",
"availableBalance": 0,
"receivableBalance": 0.00,
"mainAccountId": null,
"serviceProvider": "railsbank",
"accountHolderName": "Sherlock Holmes",
"accountHolderIdentityType": "individual",
"connection": {
"id":"00000000-0000-0000-0000-000000000000",
"method": "built-in",
"serviceProvider": "railsbank",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
}
},
"connect": {
},
"metadata": {}
}
{
"workflow":{
"code":"client.direct"
},
"data":{
"account":{
"accountNumber":"12345678",
"iban":"GB85LOYD77913045276224",
"routingCodes":{
"sort-code":"123456"
},
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date"
},
"status":"active"
}
},
"connect":{
},
"metadata":{
}
}
{
"workflow":{
"code":"client.direct"
},
"data":{
"account":{
"id":"00000000-0000-0000-0000-000000000000",
"clientId":"00000000-0000-0000-0000-000000000000",
"status":"active",
"country":"GB",
"currency":"EUR",
"alias":"EUR Account",
"accountNumber":"12345678",
"iban":"GB85LOYD77913045276224",
"routingCodes":{
"sort-code":"123456"
},
"ledgerNumber":"12345678",
"availableBalance":0,
"serviceProvider":null,
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"plug-in",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
}
},
"connect":{
},
"metadata":{
}
}
{
"workflow":{
"code":"client.direct"
},
"data":{
"account": {
"connection":{
"state":"creation-failed",
"error":{
"category": "functional/technical",
"origin": "customer/platform/provider",
"code":"..free text..",
"message":"..free text..",
"attributes":{
"key01": "value01",
"key02": "value02"
}
}
}
}
},
"connect":{
},
"metadata":{
}
}
{
"workflow":{
"code":"client.direct"
},
"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":null,
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":null,
"method":"plug-in",
"serviceProvider":"revolut",
"reference":null,
"state":"creation-failed",
"status":null,
"error":{
"category": "functional/technical",
"origin": "customer/platform/provider",
"code":"..free text..",
"message":"..free text..",
"attributes":{
"key01": "value01",
"key02": "value02"
}
}
}
}
},
"connect":{
},
"metadata":{}
}
{
"workflow":{
"code":"client.direct"
},
"data":{
"account":{
"status":"declined",
"connection":{
"state":"creation-failed",
"error":{
"category": "functional/technical",
"origin": "customer/platform/provider",
"code":"..free text..",
"message":"..free text..",
"attributes":{
"key01": "value01",
"key02": "value02"
}
}
}
}
},
"connect":{
},
"metadata":{
}
}
{
"workflow":{
"code":"client.direct"
},
"data":{
"account":{
"id":"00000000-0000-0000-0000-000000000000",
"clientId":"00000000-0000-0000-0000-000000000000",
"status":"declined",
"country":"GB",
"currency":"EUR",
"alias":"EUR Account",
"routingCodes":{
},
"iban":null,
"accountNumber":null,
"ledgerNumber":"12345678",
"availableBalance":0,
"serviceProvider":null,
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":null,
"method":"plug-in",
"serviceProvider":"revolut",
"reference":null,
"state":"creation-failed",
"status":null,
"error":{
"category": "functional/technical",
"origin": "customer/platform/provider",
"code":"..free text..",
"message":"..free text..",
"attributes":{
"key01": "value01",
"key02": "value02"
}
}
}
}
},
"connect":{
},
"metadata":{
}
}
Get an Account
Endpoints with GET do not include workflows, however, you can use metadata parameters to shape the response. "connect.connection" object is DEPRECATED and will be removed on 31/05/2024 because the connection object is added to "data.account" object.
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",
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"method": "built-in",
"serviceProvider": "railsbank",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
}
},
"connect": {
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "railsbank",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
},
"metadata": {
"include": [
"connect.connection"
]
}
}
{
"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":{
}
}
{
"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": "revolut",
"accountHolderName": "Sherlock Holmes",
"accountHolderIdentityType": "individual",
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"method": "plug-in",
"serviceProvider": "revolut",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
}
},
"connect": {
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "revolut",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
},
"metadata": {
"include": [
"connect.connection"
]
}
}
{
"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":"revolut",
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual"
}
},
"connect":{
},
"metadata":{
}
}
You can find a list of valid metadata.include parameters below
| Key | Description |
|---|---|
| connect.connection | Includes 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": "GBP",
"alias": "test 1",
"routingCodes": {},
"iban": null,
"accountNumber": null,
"ledgerNumber": "43611883",
"availableBalance": 0.00,
"receivableBalance": 0.00,
"accountHolderIdentityType": "individual",
"accountHolderName": "car keyboard",
"mainAccountId": null,
"serviceProvider": "nium",
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"method": "built-in",
"serviceProvider": "railsbank",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
},
"client": {
"id": "00000000-0000-0000-0000-000000000000",
"clientNumber": "23050065",
"fullName": "car keyboard",
"status": "active",
"identity": {
"type": "individual",
"country": "GB",
"identifications": [
{
"type": "identity-card",
"identificationNumber": "12345677",
"issuingCountry": "GB",
"issueDate": "2022-01-01",
"expirationDate": "2032-01-01"
}
],
"givenName": "car",
"familyName": "keyboard",
"birthDate": "1953-01-06"
}
}
},
"connect": {},
"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": "GBP",
"alias": "test 1",
"routingCodes": {},
"iban": null,
"accountNumber": null,
"ledgerNumber": "43611883",
"availableBalance": 0.00,
"receivableBalance": 0.00,
"accountHolderIdentityType": "individual",
"accountHolderName": "car keyboard",
"mainAccountId": null,
"serviceProvider": "nium",
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"method": "plug-in",
"serviceProvider": "revolut",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
},
"client": {
"id": "00000000-0000-0000-0000-000000000000",
"clientNumber": "23050065",
"fullName": "car keyboard",
"status": "active",
"identity": {
"type": "individual",
"country": "GB",
"identifications": [
{
"type": "identity-card",
"identificationNumber": "12345677",
"issuingCountry": "GB",
"issueDate": "2022-01-01",
"expirationDate": "2032-01-01"
}
],
"givenName": "car",
"familyName": "keyboard",
"birthDate": "1953-01-06"
}
}
},
"connect": {},
"metadata": {
"include": [
"data.account.clientId"
]
}
}
You can find a list of valid matadata.expand parameters below
| Key | Description |
|---|---|
| data.account.clientId | Expands client information of the account. |
List Accounts
GET /accounts
Supported query parameters:
| parameter | description |
|---|---|
| metadata.page.number | 0-indexed, default=0 |
| metadata.page.size | default=10 |
| data.account.clientId | UUID of client |
| data.account.status | one of pending, active, inactive, suspended, closed, declined |
| data.account.currency | ISO 4217 currency code |
| data.account.alias | Free 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.mainAccountId | main 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,
"receivableBalance": 0.00,
"serviceProvider": "railsbank",
"accountHolderName": "Sherlock Holmes",
"accountHolderIdentityType": "individual",
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"method": "built-in",
"serviceProvider": "railsbank",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
},
{
"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,
"receivableBalance": 0.00,
"serviceProvider": "revolut",
"accountHolderName": "Sherlock Holmes",
"accountHolderIdentityType": "individual",
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"method": "plug-in",
"serviceProvider": "revolut",
"reference": "00000000-0000-0000-0000-000000000000",
"state": "completed-up-to-date",
"status": "active",
"error": null
}
}
]
},
"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.
-
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.
-
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.
-
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 the 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": {}
}
- 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.
| parameter | description |
|---|---|
| metadata.page.number | Requested page number: 0-indexed, default=0 |
| metadata.page.size | Number of entries for each page: default=10 |
| data.accountStatement.transactionNumber | Transaction number for a specific statement record. format: 20201231-QWERTY |
| data.accountStatement.entryDateTimeFrom | Transaction entry in range from date. format: 2020-12-31T00:00:00.000 |
| data.accountStatement.entryDateTimeTo | Transaction entry in range to date. format: 2020-12-31T00:00:00.000 |
- The default date range is the current month's from the first day to the 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 Code | Possible Values |
|---|---|
| direction | debit, credit |
| transactionType | incoming-transfer, outgoing-transfer, exchange-transaction, balance-adjustment |
| entryType | incoming-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: 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 the type of webhook is either account-activated or account-information-updated:- country
- routingCodes (and content of it)
- iban
- accountNumber
- "connect.connection" object is DEPRECATED and will be removed on 31/05/2024 because the connection object is added to "data.account" object.
{
"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",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"built-in",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
},
"metadata":{
}
}
{
"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":"revolut",
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"plug-in",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
},
"metadata":{
}
}
{
"webhook":{
"module":"accounts",
"type":"account-inactivated"
},
"data":{
"account":{
"id":"00000000-0000-0000-0000-000000000000",
"clientId":"00000000-0000-0000-0000-000000000000",
"status":"inactive",
"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",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"built-in",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
},
"metadata":{
}
}
{
"webhook":{
"module":"accounts",
"type":"account-inactivated"
},
"data":{
"account":{
"id":"00000000-0000-0000-0000-000000000000",
"clientId":"00000000-0000-0000-0000-000000000000",
"status":"inactive",
"country":"GB",
"currency":"GBP",
"alias":"GBP Account",
"routingCodes":{
"sort-code":"123456"
},
"iban":null,
"accountNumber":"12345678",
"ledgerNumber":"12345678",
"availableBalance":0,
"serviceProvider":"revolut",
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"plug-in",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"inactive",
"error":null
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"inactive",
"error":null
}
},
"metadata":{
}
}
-
Account Connection Webhooks: Account connection webhooks have "accounts" in the module field in the webhook container object. Also, there is a "connection" object in the account object.
There are 6 types of webhooks sent for accounts:- connection-creation-instructed
- connection-created
- connection-creation-failed
- connection-update-instructed
- connection-updated
- connection-update-failed
These types are exposed in the webhook.type field. - "connect.connection" object is DEPRECATED and will be removed on 31/05/2024 because the connection object is added to "data.account" JSON object.
{
"webhook":{
"module":"accounts",
"type":"connection-created"
},
"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",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"built-in",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
},
"metadata":{
}
}
{
"webhook":{
"module":"accounts",
"type":"connection-updated"
},
"data":{
"account":{
"id":"00000000-0000-0000-0000-000000000000",
"clientId":"00000000-0000-0000-0000-000000000000",
"status":"closed",
"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",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"built-in",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"closed",
"error":null
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"railsbank",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"closed",
"error":null
}
},
"metadata":{
}
}
{
"webhook":{
"module":"accounts",
"type":"connection-created"
},
"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":"revolut",
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"plug-in",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"active",
"error":null
}
},
"metadata":{
}
}
{
"webhook":{
"module":"accounts",
"type":"connection-updated"
},
"data":{
"account":{
"id":"00000000-0000-0000-0000-000000000000",
"clientId":"00000000-0000-0000-0000-000000000000",
"status":"closed",
"country":"GB",
"currency":"GBP",
"alias":"GBP Account",
"routingCodes":{
"sort-code":"123456"
},
"iban":null,
"accountNumber":"12345678",
"ledgerNumber":"12345678",
"availableBalance":0,
"serviceProvider":"revolut",
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"plug-in",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"closed",
"error":null
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"revolut",
"reference":"00000000-0000-0000-0000-000000000000",
"state":"completed-up-to-date",
"status":"closed",
"error":null
}
},
"metadata":{
}
}
{
"webhook":{
"module":"accounts",
"type":"connection-creation-failed"
},
"data":{
"account":{
"id":"00000000-0000-0000-0000-000000000000",
"clientId":"00000000-0000-0000-0000-000000000000",
"status":"pending",
"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",
"connection":{
"id":null,
"method":"built-in",
"serviceProvider":"railsbank",
"reference":null,
"state":"creation-failed",
"status":"null",
"error":{
"category":"technical",
"origin":"platform",
"code":"unknown_error",
"message":"Unknown Error",
"attributes":{
"key":"value"
}
}
}
}
},
"connect":{
"connection":{
"id":null,
"serviceProvider":"railsbank",
"reference":null,
"state":"creation-failed",
"status":"null",
"error":{
"category":"technical",
"origin":"platform",
"code":"unknown_error",
"message":"Unknown Error",
"attributes":{
"key":"value"
}
}
}
},
"metadata":{
}
}
{
"webhook":{
"module":"accounts",
"type":"connection-update-failed"
},
"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",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"built-in",
"serviceProvider":"railsbank",
"reference":"reference",
"state":"completed-outdated",
"status":"active",
"error":{
"category":"functional",
"origin":"platform",
"code":"invalid_account_number",
"message":"Account Number is Invalid",
"attributes":{
"account_number":"Account Number length is too long."
}
}
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"railsbank",
"reference":"reference",
"state":"completed-outdated",
"status":"active",
"error":{
"category":"functional",
"origin":"platform",
"code":"invalid_account_number",
"message":"Account Number is Invalid",
"attributes":{
"account_number_error":"Account Number length is too long."
}
}
},
"metadata":{
}
}
}
{
"webhook":{
"module":"accounts",
"type":"connection-creation-failed"
},
"data":{
"account":{
"id":"00000000-0000-0000-0000-000000000000",
"clientId":"00000000-0000-0000-0000-000000000000",
"status":"pending",
"country":"GB",
"currency":"GBP",
"alias":"GBP Account",
"routingCodes":{
"sort-code":"123456"
},
"iban":null,
"accountNumber":"12345678",
"ledgerNumber":"12345678",
"availableBalance":0,
"serviceProvider":"revolut",
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":null,
"method":"plug-in",
"serviceProvider":"revolut",
"reference":null,
"state":"creation-failed",
"status":"null",
"error":{
"category":"functional",
"origin":"platform",
"code":"invalid_iban",
"message":"IBAN is invalid",
"attributes":{
"iban_error":"IBAN is invalid."
}
}
}
}
},
"connect":{
"connection":{
"id":null,
"serviceProvider":"revolut",
"reference":null,
"state":"creation-failed",
"status":"null",
"error":{
"category":"functional",
"origin":"platform",
"code":"invalid_iban",
"message":"IBAN is invalid",
"attributes":{
"iban_error":"IBAN is invalid."
}
}
}
},
"metadata":{
}
}
{
"webhook":{
"module":"accounts",
"type":"connection-update-failed"
},
"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":"revolut",
"accountHolderName":"Sherlock Holmes",
"accountHolderIdentityType":"individual",
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"method":"plug-in",
"serviceProvider":"revolut",
"reference":"reference",
"state":"completed-outdated",
"status":"active",
"error":{
"category":"functional",
"origin":"provider",
"code":"invalid_account_number",
"message":"Account Number is Invalid",
"attributes":{
"key":"value"
}
}
}
}
},
"connect":{
"connection":{
"id":"00000000-0000-0000-0000-000000000000",
"serviceProvider":"revolut",
"reference":"reference",
"state":"completed-outdated",
"status":"active",
"error":{
"category":"functional",
"origin":"provider",
"code":"invalid_account_number",
"message":"Account Number is Invalid",
"attributes":{
"key":"value"
}
}
},
"metadata":{
}
}
}
Updated 10 days ago