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;

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

  Endpoint for providers to notify the bank about a payment having happened.
  This will cause the bank to validate the transaction and allow the
  withdrawal to proceed. The API is idempotent, meaning sending a payment
  notification for the same ``WITHDRAWAL_ID`` return successfuly but not
  change anything.  This endpoint is always *optional*, the bank, exchange and
  wallet should all eventually notice the wire transfer with or without this
  endpoint being called.  However, by calling this endpoint checks that might
  otherwise only happen periodically can be triggered immediately.

  .. note::

    A bank shall **never** just accept this claim that the payment was
    confirmed, but instead needs to internally attest that the payment was
    successful using provider-specific transaction validation logic!  The point
    of this endpoint is merely to trigger this validation **now**.

  Since protocol **vC2EC**.

  FIXME: If this is *just* a trigger, what is the point in supplying the body?
  After all, a wallet could just do the same POST and then we'd store/process
  completely bogus information!

  FIXME: why not use /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/confirm?

  **Request:**

  The body of the request must be a `BankWithdrawalConfirmationRequest`.

  **Response:**

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

  **Details:**

  .. ts:def:: BankWithdrawalConfirmationRequest

    interface WithdrawalConfirmationRequest {

      // The provider specific transaction identifier.
      // This identifier is used by the bank to attest the
      // payment at the providers backend.
      provider_transaction_id: string;

      // An identifier, which identifies the device
      // processing the payment for the withdrawal
      // triggering the confirmation (e.g. Terminal
      // or ATM). This is needed to link the withdrawal
      // to a terminal owned by a specific provider.
      // This will decide about how the withdrawal
      // is attested. The device must be known to
      // the exchange and be somehow registered.
      //
      // FIXME: probably more general to use a *string*.
      terminal_id: number;

      // The amount to withdraw. Fees are to be sent in the
      // separate field 'fees' and not included in the amount.
      amount: Amount;

      // The fees, the customer paid at the providers facility.
      card_fees: Amount;
    }


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

  **FIXME**: Should we not change this to be a **delete**?

  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.