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:

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",
    …
  }
}