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.
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
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
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
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 …
}
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.
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.
STA or C53HACCCTCD1, CDD or B2BFurthermore to process direct debits you'll have to obtain a Creditor Identification Number from the Bundesbank and sign some additional contracts with your bank.
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.
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.