1.11.4. Taler Bank Access API

This chapter describes the API that the GNU Taler demonstrator bank offers to access accounts.

This API differs from the “Bank Integration API” in that it provides advanced API access to accounts, as opposed to enabling wallets to withdraw with a better user experience (“tight integration”).

Accounts and Withdrawals

GET ${BANK_API_BASE_URL}/public-accounts

Show those accounts whose histories are publicly visible. For example, accounts from donation receivers. As such, this request is unauthenticated.

Response

Details

interface PublicAccountsResponse {
  publicAccounts: PublicAccount[]
}
interface PublicAccount {
  iban: string;
  balance: string;
  // The account name _and_ the username of the
  // Sandbox customer that owns such a bank account.
  accountLabel: string;
}

The following endpoints require HTTP “Basic” authentication with the account name and account password, at least in the GNU Taler demo bank implementation.

GET ${BANK_API_BASE_URL}/accounts/${account_name}

Request the current balance of an account. (New: ) In case of a public bank account, no authentication is required.

Response

Details

interface Balance {
  amount: Amount;
  credit_debit_indicator: "credit" | "debit";
}
interface BankAccountBalanceResponse {
  // Available balance on the account.
  balance: Balance;

  // payto://-URI of the account. (New)
  paytoUri: string;

  // Number indicating the max debit allowed for the requesting user.
  debitThreshold: string;
}
POST ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals

Create a withdrawal operation, resulting in a taler://withdraw URI.

Request

interface BankAccountCreateWithdrawalRequest {
  // Amount to withdraw.
  amount: Amount;
}

Response

interface BankAccountCreateWithdrawalResponse {
  // ID of the withdrawal, can be used to view/modify the withdrawal operation.
  withdrawal_id: string;

  // URI that can be passed to the wallet to initiate the withdrawal.
  taler_withdraw_uri: string;
}
403 Forbidden:
The operation was rejected due to insufficient funds.
GET ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}

Query the status of a withdrawal operation.

Response

Details

interface BankAccountGetWithdrawalResponse {
  // Amount that will be withdrawn with this withdrawal operation.
  amount: Amount;

  // Was the withdrawal aborted?
  aborted: boolean;

  // Has the withdrawal been confirmed by the bank?
  // The wire transfer for a withdrawal is only executed once
  // both confirmation_done is true and selection_done is true.
  confirmation_done: boolean;

  // Did the wallet select reserve details?
  selection_done: boolean;

  // Reserve public key selected by the exchange,
  // only non-null if selection_done is true.
  selected_reserve_pub: string | null;

  // Exchange account selected by the wallet, or by the bank
  // (with the default exchange) in case the wallet did not provide one
  // through the Integration API.
  selected_exchange_account: string | null;
}
POST ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort

Abort a withdrawal operation. Has no effect on an already aborted withdrawal operation.

200 OK: The withdrawal operation has been aborted. The response is an empty JSON object. 409 Conflict: The reserve operation has been confirmed previously and can’t be aborted.

POST ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm

Confirm a withdrawal operation. Has no effect on an already confirmed withdrawal operation. This call is responsible of wiring the funds to the exchange.

Response

200 OK:
The withdrawal operation has been confirmed. The response is an empty JSON object.
409 Conflict:
The withdrawal has been aborted previously and can’t be confirmed.
422 Unprocessable Entity (New):
The withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.

Transactions

GET ${BANK_API_BASE_URL}/accounts/${account_name}/transactions

Retrieve a subset of transactions related to $account_name. Without query parameters, it returns the last 5 transactions.

Request

Query Parameters
  • long_poll_ms – Optional number to express how many milliseconds the server should wait for at least one result to be shown. If not given, the server responds immediately, regardless of the result.
  • page – page number starting from 1. Page 1 has the latest transactions and 1 is the default value.
  • size – how many transactions per page. It must be at least 1 and defaults to 5.
  • from_ms – Optional. Filters the results to transactions from (inclusively) this timestamp in milliseconds
  • until_ms – Optional. Filters the results to transactions until (inclusively) this timestamp in milliseconds

Response

interface BankAccountTransactionsResponse {
  transactions: BankAccountTransactionInfo[];
}
GET ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}

Response

Retrieve the transaction whose identifier is transaction_id, in the following format:

interface BankAccountTransactionInfo {

  creditorIban: string;
  creditorBic: string; // Optional
  creditorName: string;

  debtorIban: string;
  debtorBic: string;
  debtorName: string;

  amount: number;
  currency: string;
  subject: string;

  // Transaction unique ID.  Matches
  // $transaction_id from the URI.
  uid: string;
  direction: "DBIT" | "CRDT";
  date: string; // milliseconds since the Unix epoch
}
POST ${BANK_API_BASE_URL}/accounts/${account_name}/transactions

Create a new transaction where the bank account with the label account_name is debited.

Request

interface CreateBankAccountTransactionCreate {

  // Address in the Payto format of the wire transfer receiver.
  // It needs at least the 'message' query string parameter.
  paytoUri: string;

  // Transaction amount (in the $currency:x.y format), optional.
  // However, when not given, its value must occupy the 'amount'
  // query string parameter of the 'payto' field.  In case it
  // is given in both places, the paytoUri's takes the precedence.
  amount: string;
}

Response

200 OK:
the transaction has been created.
400 Bad Request:
the request was invalid or the payto://-URI used unacceptable features.
DELETE ${BANK_API_BASE_URL}/accounts/${account_name}

Delete the bank account (and the customer entry) from the database. Note, customer usernames and bank accounts have the same value.

Registration (Testing)

POST ${BANK_API_BASE_URL}/testing/register

Create a new bank account. This endpoint should be disabled for most deployments, but is useful for automated testing / integration tests.

Request

interface BankRegistrationRequest {
  username: string;
  password: string;
  // Let the request specify the IBAN.  In this current
  // version, the IBAN validity is NOT checked by the bank
  // backend.  When missing, the IBAN is generated by the bank.
  iban?: string;
  // Name of the person who owns the account being made.
  name?: string;
  // Indicates whether the account is public or not.  Defaults to false
  isPublic?: boolean;
}

Response

200 OK: Registration was successful.