EBICS::Box

A modern API for bank accounts. Fully automatize processing of incoming and outgoing money transactions. It enables high-level access to some EBCIS features and wrapps them with further functinality.

API usage

Media Types

All actions require and return JSON formatted data. Timestamps are always formatted using ISO 8601. All data is UTF-8 encoded.

Content-Type: application/json

Authentication

In order to access an EBICS::Box's API you need a valid access token. In case of sandbox environment, this token is available in your account overview and can be revoked and regenerated whenever and as often as you want.

In order to authenticate, you need to set the Authentication http header:

Authentication: Bearer YOUR_ACCESS_TOKEN

Versioning

If not specified otherwise, the API will always use the most recent version available. In order to use a specific version, clients need to request it via header:

Accept: application/vnd.ebicsbox-v2+json

Generic responses

You can expect any response to be a valid json document (except for INI letters). For POST / PUT / DELETE messages, responses contain a message attribute which should contain a human message to describe the response.

{
  "message": "Human readable description of what happened",
  … more attributes …
}

Errors

Due to its REST nature, the API returns proper http error codes. Usually status codes in the 2xx range indicate a successful operation, 4xx indicates an error resulting from the provided attributes. And errors in the 5xx range indicate a problem in the EBICS::BOX. The JSON object returned looks like the following:

{
  "message": "Human readable description of the error",
  "errors": {
    "<field>": ["some error", "another error"]
  }
}

Please note that we expect applications to be flexible enought to accept additional fields without a major version change. Breaking changes, like changed behaviour and removal or renaming of fields will always result in a version number bump.

Prerequisites

To use every feature that is offered by the EBICS::BOX you should make sure that your bank supports and offers the respective order types.

  • Transaction Import - STA or C53
  • Usage protocols - HAC
  • Credits - CCT
  • Debits - CD1, CDD or B2B

Furthermore to process direct debits you'll have to obtain a Creditor Identification Number from the Bundesbank and sign some additional contracts with your bank.

Clarification of terms

EREF

The most important building block of the EBICS::BOX is the EREF aka "End to End ID" or "End to End Reference". It is a universal identifier that will be used to recognize transactions throughout their whole lifecycle. The maximum length is 35 characters.

Matchmaking

Every time a new "outgoing" transaction is created (debit or credit) the EREF will be stored on the internal watchlist, whenever we're seeing these IDs in new transactions you'll get notified via Webhooks. The most used use case will be to identify chargebacks or detect that the money was actullay transfered from your bank account.