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 1.

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 row_id numerical identifier. Its semantics (including its sorting order) are determined by the bank server and are completely opaque to the client.

Request:

Query Parameters:

  • limit – Optional. At most return the given number of results. Negative for descending by row_id, positive for ascending by row_id. Defaults to -20. Since protocol v1.

  • offset – Optional. Starting row_id for pagination. Since protocol v1.

  • timeout_ms – Optional. Timeout in milliseconds, for long-polling, to wait for at least one element to be shown. Only useful if limit is positive. Since protocol v1.

  • delta – Optional. Deprecated in protocol v1. Use limit instead.

  • start – Optional. Deprecated in protocol v1. Use offset instead.

  • long_poll_ms – Optional. Deprecated in protocol v1. Use timeout_ms instead.

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 received before credit_fee.
  amount: Amount;

  // Fee payed by the creditor.
  // If not null, creditor actually received amount - credit_fee
  // @since **v1**
  credit_fee?: 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