1.6. Bank API

This API provides programmatic user registration at the bank.

POST /register

Request The body of this request must have the format of a BankRegistrationRequest.

Response

Status Codes

Details

interface BankRegistrationRequest {

  // Username to use for registration; max length is 150 chars.
  username: string;

  // Password to associate with the username.  Any characters and
  // any length are valid; next releases will enforce a minimum length
  // and a safer characters choice.
  password: string;
}

This API provides programmatic withdrawal of cash via Taler to all the users registered at the bank. It triggers a wire transfer from the client bank account to the exchange’s.

POST /taler/withdraw

Request The body of this request must have the format of a BankTalerWithdrawRequest.

Response

status 200 OK
The withdrawal was correctly initiated, therefore the exchange received the payment. A BankTalerWithdrawResponse object is returned.
status 406 Not Acceptable
the user does not have sufficient credit to fulfill their request.
status 404 Not Found
The exchange wire details did not point to any valid bank account.

Details

interface BankTalerWithdrawRequest {

  // Authentication method used
  auth: BankAuth;

  // Amount to withdraw.
  amount: Amount;

  // Reserve public key.
  reserve_pub: string;

  // Exchange bank details specified in the 'payto'
  // format.  NOTE: this field is optional, therefore
  // the bank will initiate the withdrawal with the
  // default exchange, if not given.
  exchange_wire_details: string;
}

interface BankTalerWithdrawResponse {

  // Sender account details in 'payto' format.
  sender_wire_details: string;

  // Exchange base URL.  Optional: only returned
  // if the user used the default exchange.
  exchange_url: string;
}

This API allows one user to send money to another user, within the same “test” bank. The user calling it has to authenticate by including his credentials in the request.

POST /admin/add/incoming

Request: The body of this request must have the format of a BankDepositRequest.

Response:

Status Codes

Details:

interface BankDepositDetails {

  // Timestamp related to the transaction being made.
  timestamp: Timestamp;

  // Row id number identifying the transaction in the bank's
  // database.
  row_id: number;
}

interface BankDepositRequest {

  // Authentication method used
  auth: BankAuth;

  // JSON 'amount' object. The amount the caller wants to transfer
  // to the recipient's count
  amount: Amount;

  // Exchange base URL, used to perform tracking requests against the
  // wire transfer ID.  Note that in the actual bank wire transfer,
  // the schema may have to be encoded differently, i.e.
  // "https://exchange.com/" may become "https exchange.com" due to
  // character set restrictions.  It is the responsibility of the
  // wire transfer adapter to properly encode/decode the URL.
  // Payment service providers must ensure that their URL is short
  // enough to fit together with the wire transfer identifier into
  // the wire transfer subject of their respective banking system.
  exchange_url: string;

  // The subject of this wire transfer.
  subject: string;

  // The sender's account identificator.  NOTE, in the current stage
  // of development this field is _ignored_, as it's always the bank account
  // of the logged user that plays as the "debit account".
  // In future releases, a logged user may specify multiple bank accounts
  // of her/his as the debit account.
  debit_account: number;

  // The recipient's account identificator
  credit_account: number;

}

interface BankAuth {

  // authentication type.  At this stage of development,
  // only value "basic" is accepted in this field.
  // The credentials must be indicated in the following HTTP
  // headers: "X-Taler-Bank-Username" and "X-Taler-Bank-Password".
  type: string;
}

interface BankError {

  // Human readable explanation of the failure.
  error: string;

  // Numeric Taler error code (TALER_ErrorCode)
  ec: number;

}
PUT /reject

Rejects an inbound transaction. This can be used by the receiver of a wire transfer to cancel that transaction, nullifying its effect. This basically creates a correcting entry that voids the original transaction. Henceforth, the /history must show the original transaction as “cancelled+” or “cancelled-” for creditor and debitor respectively. This API is used when the exchange receives a wire transfer with an invalid wire transfer subject that fails to decode to a public key.

Request The body of this request must have the format of a BankCancelRequest.

Query Parameters
  • auth – authentication method used. At this stage of development, only value "basic" is accepted. Note that username and password need to be given as request’s headers. The dedicated headers are: X-Taler-Bank-Username and X-Taler-Bank-Password.
  • row_id – row identifier of the transaction that should be cancelled.
  • account_number – bank account for which the incoming transfer was made and for which auth provides the authentication data. Currently ignored, as multiple bank accounts per user are not implemented yet.
interface BankCancelRequest {

  // Authentication method used
  auth: BankAuth;

  // The row id of the wire transfer to cancel
  row_id: number;

  // The recipient's account identificator
  credit_account: number;

}

Response In case of an error, the body is a BankError object.

Status Codes
GET /history-range

Filters and returns the list of transactions in the time range specified by start and end

Request

Query Parameters
  • auth – authentication method used. At this stage of development, only value "basic" is accepted. Note that username and password need to be given as request’s headers. The dedicated headers are: X-Taler-Bank-Username and X-Taler-Bank-Password.
  • start – unix timestamp indicating the oldest transaction accepted in the result.
  • end – unix timestamp indicating the youngest transaction accepted in the result.
  • direction – argument taking values debit or credit, according to the caller willing to receive both incoming and outgoing, only outgoing, or only incoming records. Use both to return both directions.
  • cancelled – argument taking values omit or show to filter out rejected transactions
  • account_number – bank account whose history is to be returned. Currently ignored, as multiple bank accounts per user are not implemented yet.
  • ordering – can be descending or ascending and regulates whether the row are returned youger-to-older or vice versa. Defaults to descending.

Response

Status Codes
GET /history

Filters and returns the list of transactions of the customer specified in the request.

Request

Query Parameters
  • auth – authentication method used. At this stage of development, only value basic is accepted. Note that username and password need to be given as request’s headers. The dedicated headers are: X-Taler-Bank-Username and X-Taler-Bank-Password.
  • delta – returns the first N records younger (older) than start if +N (-N) is specified.
  • start – according to delta, only those records with row id strictly greater (lesser) than start will be returned. This argument is optional; if not given, it defaults to “MAX_UINT64”.
  • direction – argument taking values debit or credit, according to the caller willing to receive both incoming and outgoing, only outgoing, or only incoming records. Use both to return both directions.
  • cancelled – argument taking values omit or show to filter out rejected transactions
  • account_number – bank account whose history is to be returned. Currently ignored, as multiple bank accounts per user are not implemented yet.
  • ordering – can be descending or ascending and regulates whether the row are returned youger-to-older or vice versa. Defaults to descending.

Response

Status Codes
interface BankTransaction {

  // identification number of the record
  row_id: number;

  // Date of the transaction
  date: Timestamp;

  // Amount transferred
  amount: Amount;

  // "-" if the transfer was outgoing, "+" if it was
  // incoming; "cancel+" or "cancel-" if the transfer
  // was /reject-ed by the receiver.
  sign: string;

  // Bank account number of the other party involved in the
  // transaction.
  counterpart: number;

  // Wire transfer subject line.
  wt_subject: string;

}

1.6.1. Interactions with wallet

A bank and a wallet need to communicate for (1) make some elements visible only if the wallet is installed, (2) exchange information when the user withdraws coins.

Make elements visible.

This feature works via CSS injection from the wallet. To enable it, the page must contain the <html data-taler-nojs="true"> element, so that the wallet will do the injection.

Whenever a element <x> needs to be visualized (hidden) if the wallet is installed, the special class taler-installed-show (taler-installed-hide) must be added to x, as follows:

  • <x class="taler-installed-show">y</x> will make y visible.
  • <x class="taler-installed-hide">y</x> will make y visible.

Clearly, a fallback page must be provided, which will be useful if the wallet is not installed. This special page will hide any element of the class taler-install-show; it can be downloaded at the following URL: git://taler.net/web-common/taler-fallback.css.

Withdrawing coins

After the user confirms the withdrawal, the bank must return a 202 Accepted response, along with the following HTTP headers:

  • X-Taler-Operation: create-reserve
  • X-Taler-Callback-Url: <callback_url>; this URL will be automatically visited by the wallet after the user confirms the exchange.
  • X-Taler-Wt-Types: '["test"]'; stringified JSON list of supported wire transfer types (only ‘test’ supported so far).
  • X-Taler-Amount: <amount_string>; stringified Taler-style JSON amount.
  • X-Taler-Sender-Wire: <wire_details>; stringified WireDetails.
  • X-Taler-Suggested-Exchange: <URL>; this header is optional, and <URL> is the suggested exchange URL as given in the SUGGESTED_EXCHANGE configuration option.
interface WireDetails {
  // Only 'test' value admitted so far.
  type: string;

  // URL of the bank.
  bank_uri: string;

  // bank account number of the user attempting to withdraw.
  account_number: number;
}

After the user confirms the exchange to withdraw coins from, the wallet will visit the callback URL, in order to let the user answer some security questions and provide all relevant data to create a reserve.

Note

Currently, the bank is in charge of creating the reserve at the chosen exchange. In future, the exchange will “poll” its bank account and automatically creating a reserve whenever it receives any funds, without any bank’s intervention.

The callback URL implements the following API.

GET <callback_url>

Request

Query Parameters
  • amount_value – integer part of the amount to be withdrawn.
  • amount_fraction – fractional part of the amount to be withdrawn.
  • amount_currency – currency of the amount to be withdrawn.
  • exchange – base URL of the exchange where the reserve is to be created.
  • reserve_pub – public key of the reserve to create.
  • exchange_wire_details – stringification of the chosen exchange’s WireDetails.

Response

Because the wallet is not supposed to take action according to this response, the bank implementers are not required to return any particular status code here.

For example, our demonstrator bank always redirects the browser to the user’s profile page and let them know the outcome via a informational bar.