1.7. 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 a configuration information about the bank.

Request:

Response:

Status Codes
  • 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;

}

1.7.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_msOptional. 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

Status Codes
export class BankWithdrawalOperationStatus {
  // 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

Status Codes

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.
  exchange_wire_details: 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;
}