[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: docs: add nonce2ecash docs
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: docs: add nonce2ecash docs |
Date: |
Thu, 14 Mar 2024 16:26:26 +0100 |
This is an automated email from the git hooks/post-receive script.
joel-haeberli pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new e8f307fe docs: add nonce2ecash docs
e8f307fe is described below
commit e8f307fe6911fdb53793e21168618c63b88b435e
Author: Joel-Haeberli <haebu@rubigen.ch>
AuthorDate: Thu Mar 14 08:52:35 2024 +0100
docs: add nonce2ecash docs
---
core/api-nonce2ecash.rst | 163 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 163 insertions(+)
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 <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;
+ }
+
+.. 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.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: docs: add nonce2ecash docs,
gnunet <=