1.8. Taler Bank Merchant HTTP API

This section describes an API offered by the Taler wire gateway. The API is used by the merchant to query for incoming transactions.

This API is TO BE implemented by the Taler Demo Bank, as well as by LibEuFin (work in progress).

1.8.1. Authentication

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

1.8.2. Querying the transaction history

GET ${BASE_URL}/history

Return a list of transactions made from an exchange to the merchant.

Incoming transactions must contain a valid wire transfer identifier and exchange base URL. If a bank transaction does not conform to the right syntax, the wire gateway must not report it to the merchant via this endpoint.

The bank account of the merchant 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
  • startOptional. Row identifier to explicitly set the starting point of the query.
  • delta – The delta value that determines the range of the query.
  • long_poll_msOptional. 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 MerchantIncomingHistory. 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.

interface MerchantIncomingHistory {

  // Array of incoming transactions.
  incoming_transactions : MerchantIncomingBankTransaction[];

}
interface MerchantIncomingBankTransaction {

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

  // Base URL of the exchange where the transfer originated form.
  exchange_url: string;

  // The wire transfer identifier.
  wtid: WireTransferIdentifierRawP;
}