path: root/core/api-bank-integration.rst

..
  This file is part of GNU TALER.

  Copyright (C) 2014-2024 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Marcello Stanisci
  @author Christian Grothoff

==========================
Taler Bank Integration API
==========================

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

.. contents:: Table of Contents

.. http:get:: /config

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

  **Response:**

  :http:statuscode:`200 OK`:
    The exchange responds with a `IntegrationConfig` object. This request should
    virtually always be successful.

  **Details:**

  .. ts:def:: IntegrationConfig

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


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

.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID

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

  **Request:**

  :query 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.
  :query old_state:
    *Optional.* Default to "pending".

  **Response:**

  :http:statuscode:`200 OK`:
    The withdrawal operation is known to the bank, and details are given
    in the `BankWithdrawalOperationStatus` response body.
  :http:statuscode:`404 Not found`:
    The operation was not found.

  **Details:**

  .. ts:def:: BankWithdrawalOperationStatus

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


.. http: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:**

  .. ts:def:: BankWithdrawalOperationPostRequest

    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:**

  :http:statuscode:`200 OK`:
    The bank has accepted the withdrawal operation parameters chosen by the wallet.
    The response is a `BankWithdrawalOperationPostResponse`.
  :http:statuscode:`404 Not found`:
    The bank does not know about a withdrawal operation with the specified ``WITHDRAWAL_ID``.
  :http:statuscode:`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:**

  .. ts:def:: BankWithdrawalOperationPostResponse

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


.. http: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:**

  :http:statuscode:`204 No content`:
    The withdrawal operation has been aborted.
  :http:statuscode:`404 Not found`:
    The withdrawal operation was not found.
  :http:statuscode:`409 Conflict`:
    The withdrawal operation has been confirmed previously and
    can't be aborted.