..
  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 Joel Häberli

===========================
The nonce2ecash RESTful API
===========================

.. note::
  
  **This API is experimental and not yet implemented**

This chapter describe the APIs that third party providers need to integrate to allow 
withdrawals through indirect payment channels like credit cards or ATM.

.. contents:: Table of Contents

--------------
Authentication
--------------

Terminals which authenticate against the nonce2ecash API must provide their respective 
access token. Therefore they provide a ``Authorization: Bearer $ACCESS_TOKEN`` header, 
where `$ACCESS_TOKEN`` is a secret authentication token configured by the exchange and
must begin with the RFC 8959 prefix.

----------------------------
Configuration of nonce2ecash
----------------------------

.. http:get:: /config

  Return the protocol version and configuration information about the nonce2ecash API.

  **Response:**

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

  **Details:**

  .. ts:def:: Nonce2ecashConfig

    interface Nonce2ecashConfig {
      // Name of the API.
      name: "taler-nonce2ecash";

      // libtool-style representation of the nonce2ecash protocol version, see
      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
      // The format is "current:revision:age".
      version: string;
    }

-----------------------------
Withdrawing using nonce2ecash
-----------------------------

Withdrawals with a nonce2ecash are based on withdrawal operations which register a withdrawal identifier
(nonce) at the nonce2ecash component. The provider must first create a unique identifier for the withdrawal 
operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and eventually withdraw using the wallet.

.. http:post:: /withdrawal-operation

  Initiate the withdrawal operation, identified by the ``WITHDRAWAL_ID``.

  **Request:**

  .. ts:def:: WithdrawRegistration

    interface WithdrawRegistration {
      // Maps a nonce generated by the provider to a reserve public key generated by the wallet.
      withdrawal_id: ShortHashCode;

      // Reserve public key generated by the wallet.
      // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives)
      reserve_pub_key: EddsaPublicKey;

      // Optional amount for the withdrawal.
      amount?: Amount;

      // Id of the terminal of the provider requesting a withdrawal by nonce.
      // Assigned by the exchange.
      provider_terminal_id: SafeUint64;
    }

  **Response:**

  :http:statuscode:`204 No content`:
    The withdrawal was successfully registered.
  :http:statuscode:`400 Bad request`:
    The ``WithdrawRegistration`` request was malformed or contained invalid parameters.
  :http:statuscode:`500 Internal Server error`:
    The registration of the withdrawal failed due to server side issues.

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

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

  **Response:**

  :http:statuscode:`200 Ok`:
    The withdrawal was found and is returned in the response body as ``Withdrawal``.
  :http:statuscode:`404 Not found`:
    nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.

  **Details**

    .. ts:def:: Withdrawal

      interface Withdrawal {

        // Reserve public key generated by the wallet.
        // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives)
        reserve_pub_key: EddsaPublicKey;

        // Status of the withdrawal
        //  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
        withdrawal_status: EddsaPublicKey;
      }

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

    Notifies nonce2ecash about an executed payment for a specific withdrawal.

  **Request:**

  .. ts:def:: PaymentNotification

    interface PaymentNotification {

      // Unique identifier of the provider transaction.
      provider_transaction_id: string;

      // Specifies the amount which was payed to the provider (without fees).
      // This amount shall be put into the reserve linked to by the withdrawal id. 
      amount: Amount;

      // Fees associated with the payment.
      fees: Amount;
    }

  **Response:**

  :http:statuscode:`204 No content`:
    nonce2ecash received the ``PaymentNotification`` successfully and will further process
    the withdrawal.
  :http:statuscode:`400 Bad request`:
    The ``PaymentNotification`` request was malformed or contained invalid parameters.
  :http:statuscode:`404 Not found`:
    nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.
  :http:statuscode:`500 Internal Server error`:
    The ``PaymentNotification`` could not be processed due to server side issues.