Account

Accounts refer to your account provided by financial institutions. It is the very base entity for all other resources. Without an account, you cannot perform any action with the Box at all.

Accounts have various linked resources, such as bank statements, transactions, credits, debits, and events.

What can you do with Account?

The EBICS::Box API lets you perform several different actions with an Account:

GET /accounts Receive a list of all Accounts
GET /accounts/:iban Receive details for a single Account
POST /accounts Onboard an account
GET /accounts/:iban/ini_letter Fetch an account's INI letter
PUT /accounts/:iban Update an existing account

Article properties

`name` `string` `required`	Descriptive name for the account. Useful for referencing it an might appear on customer statements if no `addressor` is provided. `{ "name": "Customer payments" }`
`iban` `string` `required`	Unique identifier as provided by your financial institution… `{ "iban": "DE12345678987654345678" }`
`bic` `string` `required`	Unique identifier fr your financial institution. `{ "bic": "DEUS2149509" }`
`host` `string` `required`	EBICS HOSTID as provided by financial institution. `{ "host": "YOURBANK" }`
`partner` `string` `required`	EBICS PARTNERID as provided by financial institution `{ "partner": "MYORGA1" }`
`url` `string` `required`	EBICS server url as provided by financial institution `{ "url": "http://mybank.url/ebicshost" }`
`subscriber` `string` `required`	EBICS subscriber/user as provided by financial institution `{ "subscriber": "USER1" }`
`creditor_identifier` `string`	Creditor identifier required for direct debits `{ "creditor_identifier": "USER1" }`
`callback_url` `string`	URL to which webhooks are delivered `{ "callback_url": "USER1" }`

Endpoints

GET


        /accounts

Fetch all accounts which are currently available on your EBICS::Box.

`page`	Page to show (default: 1)
`per_page`	Amount of results (default: 10) (maximum: 100)

Fetch all accounts

GET /accounts

Response

HTTP/1.1 200 OK
[
  {
    "name": "Customer Payments",
    "iban": "DE02700205000007808005",
    "bic": "BFSWDE33MUE",
    "balance_date": "2016-05-01",
    "balance_in_cents": 100,
    "status": "activated",
    "callback_url": null,
    "_links": {
      "self": "http://sandbox.ebixsbox.com/accounts/DE02700205000007808005",
      "statements": "http://sandbox.ebixsbox.com/statements?iban=DE02700205000007808005",
      "transactions": "http://sandbox.ebixsbox.com/transactions?iban=DE02700205000007808005",
      "ini_letter": "http://sandbox.ebixsbox.com/accounts/DE02700205000007808005/ini_letter"
    }
  },
  {
    "name": "Other Payments",
    "iban": "DE02700205000007808005",
    "bic": "BFSWDE33MUE",
    "balance_date": "2016-05-01",
    "balance_in_cents": 100,
    "status": "activated",
    "callback_url": null,
    "_links": {
      "self": "http://sandbox.ebixsbox.com/accounts/DE02700205000007808005",
      "statements": "http://sandbox.ebixsbox.com/statements?iban=DE02700205000007808005",
      "transactions": "http://sandbox.ebixsbox.com/transactions?iban=DE02700205000007808005",
      "ini_letter": "http://sandbox.ebixsbox.com/accounts/DE02700205000007808005/ini_letter"
    }
  }
]

GET


        /accounts/:iban

Fetch a single account with all available attributes.

:iban

IBAN of the account you want to fetch

required

Fetch a single account

GET /accounts/DE02700205000007808005

Response

HTTP/1.1 200 OK
{
  message: "Account created successfully. Please fetch INI letter, sign it, and submit it to your bank",
  account: {
    "name": "Fake Account",
    "iban": "DE02700205000007808005",
    "bic": "BFSWDE33MUE",
    "balance_date": null,
    "balance_in_cents": null,
    "creditor_identifier": "my-identifier",
    "subscriber": "USER_ID",
    "url": "https://fakebank.url/ebics",
    "partner": "PARTNER_ID",
    "host": "HOST_ID",
    "status": "activated",
    "callback_url": null,
    "_links": {
      "self": "https://sandbox.ebixsbox.com/accounts/DE02700205000007808005",
      "statements": "https://sandbox.ebixsbox.com/statements?iban=DE02700205000007808005",
      "transactions": "https://sandbox.ebixsbox.com/transactions?iban=DE02700205000007808005",
      "ini_letter": "https://sandbox.ebixsbox.com/accounts/DE02700205000007808005/ini_letter"
    }
  }
}


        POST


        /accounts

Onboard a single account

Create a basic account

POST /accounts
{
  "name": "My first test account",
  "iban": "DE02700205000007808005",
  "bic": "BFSWDE33MUE",
  "url": "https://fakebank.url/ebics",
  "host": "FAKEHOST",
  "partner": "TESTPARTNER",
  "subscriber": "TESTUSER"
}

Response

HTTP/1.1 200 OK
{
  message: "Account created successfully. Please fetch INI letter, sign it, and submit it to your bank",
  account: {
    "name": "Fake Account",
    "iban": "DE02700205000007808005",
    "bic": "BFSWDE33MUE",
    "balance_date": null,
    "balance_in_cents": null,
    "creditor_identifier": "my-identifier",
    "subscriber": "USER_ID",
    "url": "https://fakebank.url/ebics",
    "partner": "PARTNER_ID",
    "host": "HOST_ID",
    "status": "activated",
    "callback_url": null,
    "_links": {
      "self": "https://sandbox.ebixsbox.com/accounts/DE02700205000007808005",
      "statements": "https://sandbox.ebixsbox.com/statements?iban=DE02700205000007808005",
      "transactions": "https://sandbox.ebixsbox.com/transactions?iban=DE02700205000007808005",
      "ini_letter": "https://sandbox.ebixsbox.com/accounts/DE02700205000007808005/ini_letter"
    }
  }
}

Create an account which delivers webhooks to a third party system

POST /accounts
{
  "name": "My first test account",
  "iban": "DE02700205000007808005",
  "bic": "BFSWDE33MUE",
  "url": "https://fakebank.url/ebics",
  "host": "FAKEHOST",
  "partner": "TESTPARTNER",
  "subscriber": "TESTUSER",
  "callback_url": "https://thirdparty.url/webhooks"
}

Response

HTTP/1.1 200 OK
{
  message: "Account created successfully. Please fetch INI letter, sign it, and submit it to your bank",
  account: {
    "name": "Fake Account",
    "iban": "DE02700205000007808005",
    "bic": "BFSWDE33MUE",
    "balance_date": null,
    "balance_in_cents": null,
    "creditor_identifier": "my-identifier",
    "subscriber": "USER_ID",
    "url": "https://fakebank.url/ebics",
    "partner": "PARTNER_ID",
    "host": "HOST_ID",
    "status": "activated",
    "callback_url": "https://thirdparty.url/webhooks",
    "_links": {
      "self": "https://sandbox.ebixsbox.com/accounts/DE02700205000007808005",
      "statements": "https://sandbox.ebixsbox.com/statements?iban=DE02700205000007808005",
      "transactions": "https://sandbox.ebixsbox.com/transactions?iban=DE02700205000007808005",
      "ini_letter": "https://sandbox.ebixsbox.com/accounts/DE02700205000007808005/ini_letter"
    }
  }
}

Create an account which allows to use direct debits

POST /accounts
{
  "name": "My first test account",
  "iban": "DE02700205000007808005",
  "bic": "BFSWDE33MUE",
  "url": "https://fakebank.url/ebics",
  "host": "FAKEHOST",
  "partner": "TESTPARTNER",
  "subscriber": "TESTUSER",
  "creditor_identifier": "my-identifier"
  }

Response

HTTP/1.1 200 OK
{
  message: "Account created successfully. Please fetch INI letter, sign it, and submit it to your bank",
  account: {
    "name": "Fake Account",
    "iban": "DE02700205000007808005",
    "bic": "BFSWDE33MUE",
    "balance_date": null,
    "balance_in_cents": null,
    "creditor_identifier": "my-identifier",
    "subscriber": "USER_ID",
    "url": "https://fakebank.url/ebics",
    "partner": "PARTNER_ID",
    "host": "HOST_ID",
    "status": "activated",
    "callback_url": null,
    "_links": {
      "self": "https://sandbox.ebixsbox.com/accounts/DE02700205000007808005",
      "statements": "https://sandbox.ebixsbox.com/statements?iban=DE02700205000007808005",
      "transactions": "https://sandbox.ebixsbox.com/transactions?iban=DE02700205000007808005",
      "ini_letter": "https://sandbox.ebixsbox.com/accounts/DE02700205000007808005/ini_letter"
    }
  }
}

GET


        /accounts/:iban/ini_letter

Fetch INI letter for an account. This letter should be printed, signed and sent to the financial institution to active the given account.

:iban

IBAN of the account

required

Fetch INI letter for an account

GET /accounts/DE02700205000007808005/ini_letter

Response

HTTP/1.1 200 OK
<html>
  …INI LETTER…
<html>

PUT


        /accounts/:iban/

Allows you to change an existing account's name, callback_url, and creditor_identifier. Other attributes cannot be changed once an account has been created.

:iban

IBAN of the account

required

Update account settings

PUT /accounts/DE02700205000007808005
{
  "name": "My changed test account",
  "callback_url": "https://new.url",
  "creditor_identifier": "new-creditor-identifier"
}

Response

HTTP/1.1 200 OK
{
  message: "Account updated successfully.",
  account: {
    "name": "My changed test account",
    …
    "new-creditor-identifier",
    …
    "callback_url": "https://new.url",
    …
  }
}