Register a test account

Go to registration and fill out the form to register a test account for your organization. This is free of charge and should help you to get a grip on how to use the box and its features.

available

Setup a bank account

To get started, you first need to setup a bank account for your organization. On our test system, sending and collecting money for those accounts will always succeed as long as you provide valid input. Moreover, we will auto generate random transactions, so you will have some data to work with.

The following curl command should create a new account. You can change all data as long as you make sure that you use a valid IBAN and BIC. Besides a generic validation, we also check for uniqueness, so you wont be able to onboard to bank accounts with the same account number.

HOSTID, PARTNERID, EBICS_URL, and USER_ID are all provided by your bank.

      
        curl -XPOST https://sandbox.ebicsbox.com/accounts \
          -H 'Accept: application/vnd.ebicsbox-v2+json' \
          -H 'Content-Type: application/json' \
          -H 'Authorization: Bearer OAUTH_TOKEN' \
          -d '{
            "name": "My first test account",
            "iban": "DE02700205000007808005",
            "bic": "BFSWDE33MUE",
            "url": "https://fakebank.url/ebics",
            "host": "FAKEHOST",
            "partner": "TESTPARTNER",
            "subscriber": "TESTUSER"
          }'
      
    

For a real bank account, this command would initiate the setup procedure with your financial institution. The next step would be to fetch the INI letter, sign it, and submit it to your bank via snail mail:

      
        curl -XGET https://sandbox.ebicsbox.com/accounts/DE02700205000007808005/ini_letter \
          -H 'Accept: application/vnd.ebicsbox-v2+json' \
          -H 'Authorization: Bearer OAUTH_TOKEN'
      
    

The box checks on a regular basis if your account has been activated by the institution.

available

Fetch current account balance

Now that your account is activated, you can check its current balance. This balance is updated every time a new bank statement is imported. This happens on a regular basis and depending on your setup, could happend multiple times a day. Initially it is ```null``` so there wont be any confusion
The response also includes an account's current configuration. Some of this settings can be changed later on, most are fix once the account has been submitted.

Request:
      
        curl -XGET "https://sandbox.ebicsbox.com/accounts/DE02700205000007808005" \
          -H 'Accept: application/vnd.ebicsbox-v2+json' \
          -H "Authorization: Bearer OAUTH_TOKEN"
      
    
Response:
      
        {
          "name": "Fake Account",
          "iban": "DE02700205000007808005",
          "bic": "BFSWDE33MUE",
          "balance_date": null,
          "balance_in_cents": null,
          "creditor_identifier": null,
          "subscriber": "USER_ID",
          "url": "https://fakebank.url/ebics",
          "partner": "PARTNER_ID",
          "host": "HOST_ID",
          "status": "activated",
          "callback_url": null,
          "_links": {
            "self": "http://localhost:5000/accounts/DE02700205000007808005",
            "statements": "http://localhost:5000/statements?iban=DE02700205000007808005",
            "transactions": "http://localhost:5000/transactions?iban=DE02700205000007808005",
            "ini_letter": "http://localhost:5000/accounts/DE02700205000007808005/ini_letter"
          }
        }
      
    
available

Transfer money to another account

In order to transfer money from one of your accounts to another, you need to know the recipient and his account data. The reference is what's displayed on your recipient's bank statement. This is the most basic form. There are additional fields to allow you timed execution (execute_on), urgend delivery (urgent), and providing an end-to-end reference number (end_to_end_reference).

Request
      
        curl -XPOST "https://sandbox.ebicsbox.com/credit_transfers" \
          -H 'Accept: application/vnd.ebicsbox-v2+json' \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer OAUTH_TOKEN" \
          -d '{
            "account": "DE02700205000007808005",
            "name": "Max Mustermann",
            "iban": "DE69500921000000046868",
            "bic": "GENODE51BH2",
            "amount_in_cents": 10013,
            "end_to_end_reference": "eref-1"
          }'
      
    
Response
      
        {
            "message": "Credit transfer has been initiated successfully!"
        }
      
    

In addition to those required fields, it is also possible to set 3 more parameters:

  • reference text which appears on customer statement
  • execution_date custom date when to execute order
  • urgent Urgent delivery (depends on bank support)

in development

Collect money from another account

In order to collect money via direct debits, you have to fulfil a few prerequisits. First of all a creditor identifier is required. You can get one from the Deutsche Bundesbank. Moreover, each direct debit requires a unique mandate id and a valid mandate signature. If not, the box will reject your order.

Request:
      
        curl -XPOST https://sandbox.ebicsbox.com/direct_debits \
          -H 'Accept: application/vnd.ebicsbox-v2+json' \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer OAUTH_TOKEN" \
          -d '{
            "account": "DE02700205000007808005",
            "name": "Recipient name",
            "iban": "Recipient iban",
            "bic": "Recipient bic",
            "amount_in_cents": 12345,
            "reference": "Message for your customer's statement"
            "mandate_id": "unique id presented to customer",
            "mandate_signature_date": "2016-05-01"
          }'
      
    
Response:
      
        {
          "message": "Direct debit has been initiated successfully."
        }
      
    

This is the most basic direct debit. The box also supports recurring direct debits and special forms like CD1 and B2B.

available

Account transactions

This endpoint provides all transactions imported via your accounts' bank statements. It flattens all data and allows you to query across multiple bank accounts and banks. No need to check account after account.
The most basic form will return a paginated list. But you can also apply various filter criteria to limit a result set. Those criteria are:

  • Account: ?account=ACCOUNTIBAN1,ACCOUNTIBAN2
  • Time: ?from=2016–04–01&to=2016–05–01 both optional
  • Type: ?type=credit
  • Pagination: ?page=2&per_page=100 where per_page has a default value of 25

Request
      
        curl -XGET https://sandbox.ebicsbox.com/transactions \
          -H 'Accept: application/vnd.ebicsbox-v2+json' \
          -H "Authorization: Bearer OAUTH_TOKEN"
      
    
Response
      
        [
          {
            "id": "514fbec4-2335-11e6-b67b-9e71128cae77",
            "account": "DE02700205000007808005",
            "name": "Max Mustermann",
            "iban": "MUSTERMANNIBAN",
            "bic": "MUSTERMANNBIC",
            "type": "credit",
            "amount_in_cents": 34299,
            "executed_on": "2016-05-02",
            "reference": "Text on bank statement",
            "end_to_end_reference": "some-unique-ref-1",
            "_links": {
              "self": "https://box.url/transactions/514fbec4-2335-11e6-b67b-9e71128cae77",
              "account": "https://box.url/accounts/DE02700205000007808005"
            }
          },
          …
        ]
      
    
available

Get notified by webhooks

EBICS is asynchronous in nature as many bank servers are still handle their order in large batches. Therefore, we cannot expect that credits and direct debits will be executed immediately. In order to keep things easy for developers, we use the common webhook pattern. Whenever something noteworthy happens, the box will notify a remote system about it. This could be failed or succeeded direct debits or newly fetched transactions. No need to pull data, we will push it to your app.

Before you get started, the box needs to know where to push those notifications (You can set basic auth data via http://user:password@host/).

      
        curl -XPUT https://sandbox.ebicsbox.com/accounts/DE02700205000007808005 \
          -H 'Accept: application/vnd.ebicsbox-v2+json' \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer OAUTH_TOKEN" \
          -d '{"callback_url": "https://your_app.url/callback"}'
      
    

Whenever you change the callback url, we will send a test notification to the url. A webhook for a new statement would look like this:

      
        {
          "id": "3e977891-2785-4c2c-9d01-6e68eb2a3421",
          "account_id": 1,
          "statement": {
            "id": "3e977891-2785-4c2c-9d01-6e68eb2a3421",
            "account": "DE00000000000000000001",
            "name": "NAME",
            "bic": "YOURBIC",
            "iban": "DE00000000000000000002",
            "type": "debit",
            "amount": 1000,
            "date": "2017-01-01",
            "remittance_information": "XYZ SAGT DANKE",
            "eref": "some-eref",
            "mref": "some-mref",
            "reference": "NONREF",
            "bank_reference": "bank-ref",
            "creditor_identifier": "DExxxxxxxxxxxyz",
            "transaction_type": "NDDT",
            "_links": {
              "self": "https://box.url/DE00000000000000000001/statements/1",
              "account": "https://box.url/DE00000000000000000001/",
              "transaction": null
            }
          },
          "action": "statement_created",
          "triggered_at": "2016-06-20T09:50:36.946+02:00"
        }