From e8f307fe6911fdb53793e21168618c63b88b435e Mon Sep 17 00:00:00 2001 From: Joel-Haeberli Date: Thu, 14 Mar 2024 08:52:35 +0100 Subject: docs: add nonce2ecash docs --- core/api-nonce2ecash.rst | 163 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 core/api-nonce2ecash.rst diff --git a/core/api-nonce2ecash.rst b/core/api-nonce2ecash.rst new file mode 100644 index 00000000..9e69e954 --- /dev/null +++ b/core/api-nonce2ecash.rst @@ -0,0 +1,163 @@ +.. + 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 + + @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; + } + +.. 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. -- cgit v1.2.3