1.11.5. 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

Return the protocol version and configuration information about the bank. This specification corresponds to current protocol being version 2.

Response:

200 OK:

The exchange responds with a IntegrationConfig object. This request should virtually always be successful.

Details:

interface IntegrationConfig {
  // Name of the API.
  name: "taler-bank-integration";

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

  // URN of the implementation (needed to interpret 'revision' in version).
  // @since v2, may become mandatory in the future.
  implementation?: string;

  // Currency used by this bank.
  currency: string;

  // How the bank SPA should render this currency.
  currency_specification: CurrencySpecification;
}

1.11.5.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 WITHDRAWAL_ID) to interact with the withdrawal operation.

GET /withdrawal-operation/$WITHDRAWAL_ID

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

Request:

Query Parameters:
  • long_poll_msOptional. If specified, the bank will wait up to long_poll_ms milliseconds for operationt state to be different from old_state before sending the HTTP response. A client must never rely on this behavior, as the bank may return a response immediately.

  • old_stateOptional. Default to “pending”.

Response:

200 OK:

The withdrawal operation is known to the bank, and details are given in the BankWithdrawalOperationStatus response body.

404 Not found:

The operation was not found

Details:

export class BankWithdrawalOperationStatus {
  // Current status of the operation
  // pending: the operation is pending parameters selection (exchange and reserve public key)
  // selected: the operations has been selected and is pending confirmation
  // aborted: the operation has been aborted
  // confirmed: the transfer has been confirmed and registered by the bank
  // Since protocol v1.
  status: "pending" | "selected" | "aborted" | "confirmed";

  // 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).
  // Only applicable when status is selected or pending.
  // It may contain withdrawal operation id
  confirm_transfer_url?: string;

  // Wire transfer types supported by the bank.
  wire_types: string[];

  // Reserve public key selected by the exchange,
  // only non-null if status is selected or confirmed.
  // Since protocol v1.
  selected_reserve_pub?: string;

  // Exchange account selected by the wallet
  // only non-null if status is selected or confirmed.
  // Since protocol v1.
  selected_exchange_account?: string;

  // Deprecated field since protocol v1 use status instead
  // Indicates whether the withdrawal was aborted.
  aborted: boolean;

  // Deprecated field since protocol v1 use status instead
  // Has the wallet selected parameters for the withdrawal operation
  // (exchange and reserve public key) and successfully sent it
  // to the bank?
  selection_done: boolean;

  // Deprecated field since protocol v1 use status instead
  // 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;
}
POST /withdrawal-operation/$WITHDRAWAL_ID

Request:

interface BankWithdrawalOperationPostRequest {
  // Reserve public key.
  reserve_pub: string;

  // Payto address of the exchange selected for the withdrawal.
  selected_exchange: string;
}

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 WITHDRAWAL_ID.

409 Conflict:
  • TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT : The wallet selected a different exchange or reserve public key under the same withdrawal ID.

  • TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT : the reserve public key is already used.

  • TALER_EC_BANK_UNKNOWN_ACCOUNT : the selected exchange account was not found.

  • TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE : the selected account is not an exchange.

Details:

interface BankWithdrawalOperationPostResponse {
  // Current status of the operation
  // pending: the operation is pending parameters selection (exchange and reserve public key)
  // selected: the operations has been selected and is pending confirmation
  // aborted: the operation has been aborted
  // confirmed: the transfer has been confirmed and registered by the bank
  status: "selected" | "aborted" | "confirmed";

  // URL that the user needs to navigate to in order to
  // complete some final confirmation (e.g. 2FA).
  //
  // Only applicable when status is selected or pending.
  // It may contain withdrawal operation id
  confirm_transfer_url?: string;

  // Deprecated field use status instead
  // 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;
}
POST /withdrawal-operation/$WITHDRAWAL_ID/abort

Aborts WITHDRAWAL_ID operation. Has no effect on an already aborted operation. Since protocol v2.

Response:

204 No content:

The withdrawal operation has been aborted.

404 Not found:

The withdrawal operation was not found.

409 Conflict:

The withdrawal operation has been confirmed previously and can’t be aborted.