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

..
  This file is part of GNU TALER.

  Copyright (C) 2014-2023 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 version **2**.

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

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

  **Request:**

  .. ts:def:: BankWithdrawalOperationPostRequest

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

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

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

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

  Since protocol vC2EC

  Allows a provider to notify the Bank about the payment. This will trigger a payment
  attestation at the provider, which eventually confirms the payment and allows the
  withdrawal. The API is idempotent, meaning sending a payment 
  notification for the same ``WITHDRAWAL_ID`` return successfuly but not change anything.

  Attention: A bank shall **never** just accept the payment directly but instead attest
  the payment using provider specific attestation logic!

  **Request:**
  
  .. 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.
      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 payed at the providers facility.
      card_fees: Amount;
    }

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


.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort

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

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