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

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:

long_poll_ms – Optional. 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_state – Optional. 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:

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

  // 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 **vC2EC**.
  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 **vC2EC**.
  suggested_amount?: Amount;

  // Maximum amount that the wallet can choose to withdraw.
  // Only applicable when the amount is not fixed.
  // @since **vC2EC**.
  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.
  // @since **vC2EC**
  card_fees?: Amount;

  // Bank account of the customer that is debiting, as an
  // 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 **vC2EC**
  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;

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

  // 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 **vC2EC**
  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_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 vC2EC).
TALER_EC_BANK_AMOUNT_REQUIRED : the backend requires an amount to be specified (since vC2EC).

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;

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

1.11.4. Taler Bank Revenue HTTP API

1.11.6. Taler Conversion Info API

GNU Taler

1.11.5. Taler Bank Integration API¶

1.11.5.1. Withdrawing¶

1.11.5. Taler Bank Integration API ¶

1.11.5.1. Withdrawing ¶