Taler Bank Integration API

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

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 websitei) 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:

  • timeout_ms – Optional. Timeout in milliseconds, for long-polling, to wait for operation state to be different from old_state. Since protocol v3.

  • old_state – Optional. Defaults to “pending”.

  • long_poll_ms – Optional. Deprecated in protocol v3. Use timeout_ms instead.

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:

interface 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 **v1**
  status: "pending" | "selected" | "aborted" | "confirmed";

  // Currency used for the withdrawal.
  // MUST be present when amount is absent.
  // @since **v2**, may become mandatory in the future.
  currency?: string;

  // Amount that will be withdrawn with this operation
  // (raw amount without fee considerations).  Only
  // given once the amount is fixed and cannot be changed.
  // Optional since **v4**.
  amount?: Amount;

  // Suggestion for the amount to be withdrawn with this
  // operation.  Given if a suggestion was made but the
  // user may still change the amount.
  // Optional since **v4**.
  suggested_amount?: Amount;

  // Minimum amount that the wallet can choose to withdraw.
  // Only applicable when the amount is not fixed.
  // @since **v4**.
  min_amount?: Amount;

  // Maximum amount that the wallet can choose to withdraw.
  // Only applicable when the amount is not fixed.
  // @since **v4**.
  max_amount?: Amount;

  // The non-Taler card fees the customer will have
  // to pay to the bank / payment service provider
  // they are using to make the withdrawal in addition
  // to the amount.
  // @since **v4**
  card_fees?: Amount;

  // Bank account of the customer that is debiting, as a
  // full RFC 8905 payto URI.
  sender_wire?: string;

  // Base URL of the suggested exchange.  The bank may have
  // neither a suggestion nor a requirement for the exchange.
  // This value is typically set in the bank's configuration.
  suggested_exchange?: string;

  // Base URL of an exchange that must be used.  Optional,
  // not given *unless* a particular exchange is mandatory.
  // This value is typically set in the bank's configuration.
  // @since **v4**
  required_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 the 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 **v1**
  selected_reserve_pub?: EddsaPublicKey;

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

  // If true, tells the wallet not to allow the user to
  // specify an amount to withdraw and to not provide
  // any amount when registering with the withdrawal
  // operation. The amount to withdraw will be set
  // by the final /withdrawals/$WITHDRAWAL_ID/confirm step.
  // @since **v5**
  no_amount_to_wallet?: boolean;

  // @deprecated since **v1**, use status instead
  // Indicates whether the withdrawal was aborted.
  aborted: boolean;

  // @deprecated since **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 since **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#

This endpoint is used by the GNU Taler wallet to supply additional details needed to complete a withdraw operation.

Request:

interface BankWithdrawalOperationPostRequest {

  // Reserve public key that should become the wire transfer
  // subject to fund the withdrawal.
  reserve_pub: EddsaPublicKey;

  // Full RFC 8905 (payto) address of the exchange account to be
  // credited for the withdrawal.
  selected_exchange: string;

  // Selected amount to be transferred. Optional if the
  // backend already knows the amount.
  // @since **v4**
  amount?: Amount;
}

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_UPDATE_ABORT_CONFLICT : the withdrawal has been aborted previously and can’t be modified.

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

  • TALER_EC_BANK_AMOUNT_DIFFERS : the specified amount will not work for this withdrawal (since v4).

  • TALER_EC_BANK_UNALLOWED_DEBIT : the account does not have sufficient funds or the amount is too low or too high (since v4).

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 since **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/abort#

Aborts WITHDRAWAL_ID operation. Has no effect on an already aborted operation. This endpoint can be used by the wallet if the user aborts the transaction, ensuring that the operation is also aborted at the bank.

Since protocol v2.

Request:

The request body is empty.

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.