Contents

1.11.4. Taler Bank Revenue HTTP API

This section describes an API offered by libeufin-nexus and libeufin-bank. The API is used by the merchant (or other parties) to query for incoming transactions to their account.

GET /config

Return the protocol version and configuration information about the bank. This specification corresponds to current protocol being version 0.

Response:

200 OK:

The exchange responds with a RevenueConfig object. This request should virtually always be successful.

Details:

interface RevenueConfig {
  // Name of the API.
  name: "taler-revenue";

  // libtool-style representation of the Bank protocol version, see
  // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
  // The format is "current:revision:age".
  version: string;

  // Currency used by this gateway.
  currency: string;

  // URN of the implementation (needed to interpret 'revision' in version).
  // @since v0, may become mandatory in the future.
  implementation?: string;
}

1.11.4.1. Authentication

The bank library authenticates requests to the bank merchant API using HTTP basic auth.

1.11.4.2. Querying the transaction history

GET /history

Return a list of transactions made to an account.

The bank account is determined via the base URL and/or the user name in the Authorization header. In fact, the transaction history might come from a “virtual” account, where multiple real bank accounts are merged into one history.

Transactions are identified by an opaque numeric identifier, referred to here as row ID. The semantics of the row ID (including its sorting order) are determined by the bank server and completely opaque to the client.

The list of returned transactions is determined by a row ID starting point and a signed non-zero integer delta:

  • If delta is positive, return a list of up to delta transactions (all matching the filter criteria) strictly after the starting point. The transactions are sorted in ascending order of the row ID.

  • If delta is negative, return a list of up to -delta transactions (all matching the filter criteria) strictly before the starting point. The transactions are sorted in descending order of the row ID.

If starting point is not explicitly given, it defaults to:

  • A value that is smaller than all other row IDs if delta is positive.

  • A value that is larger than all other row IDs if delta is negative.

Request:

Query Parameters:

  • start – Optional. Row identifier to explicitly set the starting point of the query.

  • delta – The delta value that determines the range of the query.

  • long_poll_ms – Optional. If this parameter is specified and the result of the query would be empty, the bank will wait up to long_poll_ms milliseconds for new transactions that match the query to arrive and only then send the HTTP response. A client must never rely on this behavior, as the bank may return a response immediately or after waiting only a fraction of long_poll_ms.

Response:

200 OK:

JSON object of type RevenueIncomingHistory.

400 Bad request:

Request malformed. The bank replies with an ErrorDetail object.

401 Unauthorized:

Authentication failed, likely the credentials are wrong.

404 Not found:

The endpoint is wrong or the user name is unknown. The bank replies with an ErrorDetail object.

Details:

interface RevenueIncomingHistory {
  // Array of incoming transactions.
  incoming_transactions : RevenueIncomingBankTransaction[];

  // Payto URI to identify the receiver of funds.
  // Credit account is shared by all incoming transactions
  // as per the nature of the request.
  credit_account: string;
}

interface RevenueIncomingBankTransaction {
  // Opaque identifier of the returned record.
  row_id: SafeUint64;

  // Date of the transaction.
  date: Timestamp;

  // Amount transferred.
  amount: Amount;

  // Payto URI to identify the sender of funds.
  debit_account: string;

  // The wire transfer subject.
  subject: string;
}

previous

1.11.3. Taler Wire Gateway HTTP API

next

1.11.5. Taler Bank Integration API