14.4. Sandbox API

14.4.1. Demobanks.

Sandbox is designed to allow multiple banks being hosted, where every demobank can have its own configuration (including a different currency). A demobank has a name, although currently only one demobank, named default, is supported. Such demobank activates the API trunk /demobanks/default, under which other APIs are then served. Those APIs include Access API, Integration API, (part of the) Wire Gateway API (the add-incoming call), and one call to create EBICS subscribers.

14.4.2. Access API.

Every endpoint is served under /demobanks/default/access-api. See Taler Bank Access API.

14.4.3. Integration API.

Every endpoint is served under /demobanks/default/integration-api. See Taler Bank Integration API.

14.4.4. Taler Wire Gateway API.

Served under /demobanks/default/taler-wire-gateway. Currently, only the admin/add-incoming endpoint is implemented. This endpoint allows testing, whereas the rest of this API does never involve the Sandbox.

14.4.5. EBICS.

HTTP Service

POST /ebicsweb

Serves all the Ebics requests.

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 /demobanks/default/ebics/subscribers

Allows (only) the admin user to associate a bank account to a EBICS subscriber. If the latter does not exist, it is created.

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.
  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;
}
POST /admin/ebics/subscribers

Create a new EBICS subscriber without associating a bank account to it. This call is deprecated. Follow this page for updates over the EBICS management REST design.

interface SubscriberRequestDeprecated {

  // hostID
  hostID: string;

  // userID
  userID: string;

  // partnerID
  partnerID: string;

  // systemID, optional.
  systemID: string;

}

14.4.6. Bank accounts.

GET /admin/bank-accounts

Give summary of all the bank accounts.

Response:

interface AdminBankAccount {

  // IBAN
  iban: string;

  // BIC
  bic: string;

  // human name
  name: string;

  // bank account label
  label: string;
}
GET /admin/bank-accounts/$accountLabel

Give information about a bank account.

Response:

interface AdminBankAccountBalance {
  // Balance in the $currency:$amount format.
  balance: string;
  // IBAN of the bank account identified by $accountLabel
  iban: string;
  // BIC of the bank account identified by $accountLabel
  bic: string;
  // Mentions $accountLabel
  label: string;
}
POST /admin/bank-accounts/$accountLabel

create bank account.

Request: AdminBankAccount

14.4.7. Transactions.

JSON.

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

Inform about all the transactions of one bank account.

Response:

interface AdminTransactions {
  payments: AdminTransaction[];
}
interface AdminTransaction {

  // Label of the bank account involved in this payment.
  accountLabel: string;

  // Creditor IBAN
  creditorIban: string;

  // Debtor IBAN
  debtorIban: string;

  // UID given by one financial institute to this payment.
  // FIXME: clarify whether that can be also assigned by
  // the other party's institution.
  accountServicerReference: string;

  // ID of the Pain.001 that initiated this payment.
  paymentInformationId: string;

  // Unstructured remittance information.
  subject: string;

  // Date of the payment in the HTTP header format.
  date: string;

  // The number amount as a string.
  amount: string;

  // BIC of the creditor IBAN.
  creditorBic: string;

  // Legal name of the creditor.
  creditorName: string;

  // BIC of the debtor IBAN.
  debtorBic: string;

  // Legal name of the debtor.
  debtorName: string;

  // Payment's currency
  currency: string;

  // Have values 'credit' or 'debit' relative
  // to the requesting user.
  creditDebitIndicator: string;
}
POST /admin/bank-accounts/$accountLabel/generate-transactions

Generate one incoming and one outgoing transaction for the bank account identified by $accountLabel.

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.

Request:

interface AdminSimulateTransaction {

  // Debtor IBAN.
  debtorIban: string;

  // Debtor BIC.
  debtorBic: string;

  // Debtor name.
  debtorName: string;

  // Amount number (without currency) as a string.
  amount: string;

  // Payment subject.
  subject: string;
}

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 last Camt.053 document related to the bank account mentioned in the request body.