15.4. Current Sandbox API

15.4.1. EBICS.


POST /admin/ebics/hosts

Creates a new Ebics host.


interface EbicsHostRequest {

  // Ebics version.
  hostID: string;

  // Name of the host.
  ebicsVersion: string;
GET /admin/ebics/hosts

Shows the list of all the hosts in the system.


interface EbicsHostResponse {

  // shows the host IDs that are active in the system.
  // The Ebics version *is* missing, but it's still available
  // via the HEV message.
  ebicsHosts: string[];
POST /admin/ebics/hosts/$hostID/rotate-keys

Overwrite the bank’s Ebics keys with random ones. This is entirely meant for tests (as the Sandbox itself is) and no backup will be produced along this operation.


POST /admin/ebics/bank-accounts

Associates a new bank account to an existing subscriber.


interface BankAccountRequest {

  // Ebics subscriber
  subscriber: string;

  // IBAN
  iban: string;

  // BIC
  bic: string;

  // human name
  name: string;

  // bank account label
  label: string;

POST /admin/ebics/subscribers

Creates a new Ebics subscriber.


interface SubscriberRequest {

  // hostID
  hostID: string;

  // userID
  userID: string;

  // partnerID
  partnerID: string;

  // systemID, optional.
  systemID: string;

  // Label of the bank account to associate with
  // this subscriber.  Note: the demobank name is
  // omitted because every creation should happen
  // under the /demobanks trunk.
  demobankAccountLabel: string;
GET /admin/ebics/subscribers

Shows the list of all the subscribers in the system.


interface SubscribersResponse {

  subscribers: Subscriber[]
interface Subscriber {

  // userID
  userID: string;

  // partnerID
  partnerID: string;

  // hostID
  hostID: string;

  // Label of the bank account
  // associated with this Ebics subscriber.
  demobankAccountLabel: string;

15.4.2. Bank accounts.

GET /admin/bank-accounts

Give summary of all the bank accounts.

GET /admin/bank-accounts/$accountLabel

Give information about a bank account.

DELETE /demobanks/$demobankId/$accountLabel

Delete the bank account (and the customer entry) from the database. Note, customer usernames and bank accounts have the same value.

15.4.3. Main EBICS service.

POST /ebicsweb

Serves all the Ebics requests.

15.4.4. Transactions.


GET /admin/bank-accounts/$accountLabel/transactions

Inform about all the transactions of one bank account.

POST /admin/bank-accounts/$accountLabel/generate-transactions

Generate one incoming and one outgoing transaction for one bank account.

POST /admin/bank-accounts/$accountLabel/simulate-incoming-transaction

Book one incoming transaction for $accountLabel. The debtor (not required to be in the same bank) information is taken from the request.


POST /admin/payments/camt

Return the last statement of the requesting account.


interface CamtParams {

  // label of the bank account being queried.
  bankaccount: string;

  // The Camt type to return.  Only '53' is allowed
  // at this moment.
  type: number;


The expected Camt.053 document.

15.5. Future Sandbox API

15.5.1. Resources.

Sandbox serves the following resources:

  • Demobanks.
  • Bank accounts.
  • Subscribers.
  • Transactions.
  • Customers.
  • Reports.

The resources are subject to all CRUD operations, via by two types of users: the ‘admin’ and the customers. The admin has rights on all of them.

One of the main differences with the previous versions is the removal of the “/admin” initial component. If the administrator authenticates for one operation, then this one is of type admin: no need for a dedicated and extra URI path component.

For example, mocking transactions in the system was a typical /admin-operation, but since transactions themselves are resources and any resource is subject to CRUD operations, then mocking one becomes just a C operation on the ‘transactions’ resources. If a test case wants to simplify the authentication - by hard-coding the credentials, for example - before mocking one transaction, then it can impersonate the administrator.


POSTing to an endpoint with a trailing $id means modification of an existing resource.

15.5.2. Demobanks

Demobanks are the main containers of all the other resources. They take configuration values, like the currency for example.

GET /admin/demobanks
GET /admin/demobanks/$id
POST /admin/demobanks
POST /admin/demobanks/$id
DELETE /admin/demobanks/$id

15.5.3. Bank accounts.

Bank accounts collect money of customers and participate in transactions.

The $base is one demobank, in the form /demobanks/$id. That is due because a bank account must inherit some defaults from the demobank, like the currency.

GET $base/bankaccounts
GET $base/bankaccounts/$id
POST $base/bankaccounts
POST $base/bankaccounts/$id
DELETE $base/bankaccounts/$id

15.5.4. Subscribers.

Subscribers are (optional) customers identities for protocols other than the native one.

A subscriber is not required to have a bank account “soon”. Therefore, it can be created, and later be linked to one bank account. For this reason, the $base should not mention one bank account.


Creating a subscriber is a time-consuming operation that goes often through slow channels, therefore it should basically never be done more than once.

GET $base/subscribers
GET $base/subscribers/$id
POST $base/subscribers
POST $base/subscribers/$id
DELETE $base/subscribers/$id

15.5.5. Transactions.

Transactions are money movements between bank accounts.

For convenience, $base could mention one bank account to let customers see their transactions without defining “history” query parameters: like $demobank/bankaccounts/$bankaccountId/transactions.

At the same time, transactions should be easy to query regardless of whose bank account they involve – for administrative reasons, for example. Hence, a “global” URI scheme like $demobank/transactions?param=XXX should be offered as well.

GET $base/transactions
GET $base/transactions/$id
POST $base/transactions
POST $base/transactions/$id
DELETE $base/transactions/$id

15.5.6. Customers.

Customers are persons that can have one bank account. As with subscribers, $base should not mention any bank account so as to leave more flexibility to assign new bank accounts to the same customer.

GET $base/customers
GET $base/customers/$id
POST $base/customers
POST $base/customers/$id
DELETE $base/customers/$id

15.5.7. Reports.

Reports are persistent documents witnessing transactions. A typical example is a Camt.053 statement. A report lives even after a bank account gets deleted or a customer leaves the bank, therefore $base should only mention a demobank instance.

GET $base/reports
GET $base/reports/$id
POST $base/reports
POST $base/reports/$id
DELETE $base/reports/$id