15.4. Current Sandbox API

15.4.1. EBICS.

Hosts.

POST /admin/ebics/hosts

Creates a new Ebics host.

Request:

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.

Response:

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.

Subscribers.

POST /admin/ebics/bank-accounts

Associates a new bank account to an existing subscriber.

Request:

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.

Request:

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.

Response:

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.

15.4.3. Main EBICS service.

POST /ebicsweb

Serves all the Ebics requests.

15.4.4. Transactions.

JSON.

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.

Camt.

POST /admin/payments/camt

Return the last statement of the requesting account.

Request

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;
}

Response

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 dedicate and extra URI part.

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.

Note

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.

Note

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