1.11. Taler Bank Integration API

This chapter describe the APIs that banks need to offer towards Taler wallets to tightly integrate with GNU Taler.

GET /config

Get configuration information about the bank.

Request:

Response:

200 OK:
The exchange responds with a BankVersion object. This request should virtually always be successful.

Details:

interface BankVersion {
  // 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 bank.
  currency: string;

  // Name of the API.
  name: "taler-bank-integration";
}

1.11.1. Withdrawing

Withdrawals with a Taler-integrated bank are based on withdrawal operations. Some user interaction (on the bank’s website or a Taler-enabled ATM) creates a withdrawal operation record in the bank’s database. The wallet can use a unique identifier for the withdrawal operation (the wopid) to interact with the withdrawal operation.

GET ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}

Query information about a withdrawal operation, identified by the wopid.

Request

Query Parameters
  • long_poll_ms – Optional. If specified, the bank will wait up to long_poll_ms milliseconds for completion of the transfer before sending the HTTP response. A client must never rely on this behavior, as the bank may return a response immediately.

Response

200 OK:
The withdrawal operation is known to the bank, and details are given in the BankWithdrawalOperationStatus response body.
export class BankWithdrawalOperationStatus {
  // Indicates whether the withdrawal was aborted.
  aborted: boolean;

  // Has the wallet selected parameters for the withdrawal operation
  // (exchange and reserve public key) and successfully sent it
  // to the bank?
  selection_done: boolean;

  // The transfer has been confirmed and registered by the bank.
  // Does not guarantee that the funds have arrived at the exchange already.
  transfer_done: boolean;

  // Amount that will be withdrawn with this operation
  // (raw amount without fee considerations).
  amount: Amount;

  // Bank account of the customer that is withdrawing, as a
  // payto URI.
  sender_wire?: string;

  // Suggestion for an exchange given by the bank.
  suggested_exchange?: string;

  // URL that the user needs to navigate to in order to
  // complete some final confirmation (e.g. 2FA).
  confirm_transfer_url?: string;

  // Wire transfer types supported by the bank.
  wire_types: string[];
}
POST ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}

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

Response

200 OK:
The bank has accepted the withdrawal operation parameters chosen by the wallet. The response is a BankWithdrawalOperationPostResponse.
404 Not found:
The bank does not know about a withdrawal operation with the specified wopid.
409 Conflict (New):
The wallet selected a different exchange or reserve public key under the same withdrawal ID.

Details

interface BankWithdrawalOperationPostRequest {

  // 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.
  selected_exchange: string;
}

interface BankWithdrawalOperationPostResponse {

  // The transfer has been confirmed and registered by the bank.
  // Does not guarantee that the funds have arrived at the exchange already.
  transfer_done: boolean;

  // URL that the user needs to navigate to in order to
  // complete some final confirmation (e.g. 2FA).
  //
  // Only applicable when transfer_done is false.
  confirm_transfer_url?: string;
}