-
Notifications
You must be signed in to change notification settings - Fork 11
FORMAT: 1A
EBICS::BOX enables high-level access to some EBCIS features and wrapps them with further functinality.
The most importtant 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.
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
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:
{
"errors": {
"<parameter|internal>": [ "some error", "another error" ]
}
}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
- Fullfillment Reports - HAC or PTK
- Credits - CCT
- Debits - CD1 and/or CDD
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.
Debits can be issued in three differnt versions, where as EBICS::BOX offeres support for CD1
and CDD at the moment. B2B which offers Business-2-Business direct debits is not yet available.
CD1 aka CORE1 and CDD aka CORE differ from each other in terms of the lead time before
the transaction is executed on the banking system.
-
CORE- 5 bank working days for one-off and first debits, 2 bank working days for recurring debits -
COR1- 1 bank working day for one-off, first and recurring debits
In case of issues please contact our support team at [email protected].
Creating a debit by parameter should be the preferred way for low-volume transactions esp.
for use cases where the PAIN XML isn't generated before. Transactions can be transmitted either
as CD1 or CDD depending on the order types your bank is offering you, the order_type
parameter lets you choose among them.
One debit can hold multiple transactions, each one consists of the following attributes:
-
name- customers name -
bic- customers BIC -
iban- customers IBAN -
amount- amount to debit (positive, charged in cents) -
eref- end to end id -
remittance_information- desctiption of the transaction (max. 140 char) -
mandate_id- ID of the SEPA mandate (max. 35 char) -
mandate_date_of_signature- when the mandate was signed by the customer -
sequence_type-
OOFF- one-off debit -
FRST- first debit -
RCUR- recurring debit -
FNAL- final debit
-
-
requested_date- execution date of the debit
Once validated, transactions are transmitted asynchronously to the banking system. Errors that happen eventually are delivered via Webhooks.
-
Request (application/json)
{ "creditor_identifier": "", "transactions": [ { "name": "Peter Pan", "bic": "COLSDE33XXX", "iban": "DE51370501981929807319", "amount": 100 "eref": "TRX-unique-end-to-end-id", "remittance_information": "", "mandate_id": "number", "mandate_date_of_signature": "", "sequence_type": "FRST", "requested_date": "2016-01-01" } ], "order_type": "CDD" } -
Response 201 (application/json)
["ok"] -
Response 422 (application/json)
{ "errors": { "requested_date": ["not in the future"], "iban": ["is not valid"] } }
This endpoint allows you to directly process a pre-compiled PAIN008 XML message. No further validation is applied, the message "as is" will be uploaded to the EBICS server. You should use this endpoint if the message was validated before. The processing will happen asyncron, any errors are delivered via Webhooks.
-
Request (application/json)
{ "document": "< a base64 encoded representation of a pain008 document >" } -
Response 201 (application/json)
["ok"]
Creating a credit by parameter should be the preferred way for low-volume transactions esp. for use cases where the PAIN XML isn't generated before.
One credit can hold multiple transactions, each one consists of the following attributes:
-
name- customers name -
bic- customers BIC -
iban- customers IBAN -
amount- amount to debit (charged in cents) -
eref- end to end id -
remittance_information- desctiption of the transaction (max. 140 char)
Once validated, transactions are transmitted asynchronously to the banking system. Errors that happen eventually are delivered via Webhooks.
-
Request (application/json)
{ "transactions": [ { "name": "Peter Pan", "bic": "COLSDE33XXX", "iban": "DE51370501981929807319", "amount": "100.00", "eref": "TRX-unique-end-to-end-id", "remittance_information": "order no 123" } ] } -
Response 201 (application/json)
["ok"] -
Response 422 (application/json)
{ "errors": { "iban": ["not valid"] } }
This endppint allows you to directly process a pre-compiled PAIN001 XML messages. No further validation is applied, the message "as is" will be uploaded to the EBICS server. You should use this endpoint if the message was validated before. The processing will happen asyncron, any errors are delivered via Webhooks.
-
Request (application/json)
{ "document": "< a base64 encoded representation of a pain008 document >" } -
Response 201 (application/json)
["ok"]
Transactions are imported on a daily basis and stored so they can be easily retrieved
and searched for a timeframe that exceeds the usual timeframe your bank will hold them
on record for you. Besides pulling plain lists it is also possible to filter by eref
or remittance_infomation
Scope transaction to a timeframe when suppling:
- from
- to
Filter transactions:
- eref
- remittance_information
-
Parameters
- from (optional, date,
2015-01-01) ... - to (optional, date,
2015-01-01) ... - eref (optional, string,
TRX-FOO-BAR) ... - remittance_information (optional, string,
order 123*) ...
- from (optional, date,
-
Response 200 (application/json)
[ { "name": "Peter Ebics", "bic": "DEUTDEFF", "iban": "DE12500105170648489890", "amount": "100.00", "eref": "TRX-unique-end-to-end-id", "remittance_information": "", "statement": { } } ]
Webhooks offer the possibility to build systems that are highly event-driven instead of having to pull for new information. Every imported transaction can trigger a webhook so dependent systems can react to changing information.
The basic structure of a webhook consists of the following elements:
{
"id": "e_4a4a74838ccfd7dadcb",
"type": "transaction.received",
"data": {
}
}Whereas the id is a globally unique identifier for each webhook played out to your system. The
data key will hold arbitrary data about the entity that happend to cause the event.
type will define which kind of callback you're receiving
-
transaction.received- a new transaction was imported, but no previous transaction relates to this one -
credit.fullfilled- happens whenever a credit was initiated by the EBICS::BOX and the money now actually left your account -
credit.failed- although all validations passed, something went wrong and the credit was not accepted by the underlying banking system -
debit.fullfilled- happens whenever a debit was initated and now the money received on your bank account -
debit.failed- although all validations passes, something went wrong and the debit was not accepted by the underlying banking system -
debit.chargebacked- your customers have the right to refuse a debit within 8 weeks after the money was taken form their accounts