From 54a3a6b1f0f83e1096d7a069e7a4d9b723a50bd8 Mon Sep 17 00:00:00 2001 From: Joel Häberli Date: Wed, 20 Mar 2024 22:12:04 +0100 Subject: spec: c2ec api --- core/api-c2ec.rst | 181 +++++++++++++++++++++++++++++++++++++++++++++++ core/api-nonce2ecash.rst | 170 -------------------------------------------- 2 files changed, 181 insertions(+), 170 deletions(-) create mode 100644 core/api-c2ec.rst delete mode 100644 core/api-nonce2ecash.rst diff --git a/core/api-c2ec.rst b/core/api-c2ec.rst new file mode 100644 index 00000000..030b961a --- /dev/null +++ b/core/api-c2ec.rst @@ -0,0 +1,181 @@ +.. + 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 C2EC 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 C2EC 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 C2EC +---------------------------- + +.. http:get:: /config + + Return the protocol version and configuration information about the C2EC API. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `C2ECConfig` object. This request should + virtually always be successful. + + **Details:** + + .. ts:def:: C2ECConfig + + interface C2ECConfig { + // Name of the API. + name: "taler-c2ec"; + + // libtool-style representation of the C2EC 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 C2EC +----------------------------- + +Withdrawals with a C2EC are based on withdrawal operations which register a withdrawal identifier +(nonce) at the C2EC 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:: C2ECWithdrawalOperationPostRequest + + 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 ``C2ECWithdrawalStatus``. + :http:statuscode:`404 Not found`: + C2EC does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``. + + **Details** + + .. ts:def:: C2ECWithdrawalStatus + + interface C2ECWithdrawalStatus { + // 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 protocol v1. + status: "pending" | "selected" | "aborted" | "confirmed"; + + // Amount that will be withdrawn with this operation + // (raw amount without fee considerations). + amount: Amount; + + // A refund address as ``payto`` URI. This address shall be used + // in case a refund must be done. Only not-null if the status + // is "confirmed" or "aborted" + refund_wire?: string; + + // Reserve public key selected by the exchange, + // only non-null if ``status`` is ``selected`` or ``confirmed``. + // Since protocol v1. + selected_reserve_pub?: string; + } + + +.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID + + Notifies C2EC about an executed payment for a specific withdrawal. + + **Request:** + + .. ts:def:: C2ECPaymentNotification + + interface C2ECPaymentNotification { + + // 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`: + C2EC received the ``C2ECPaymentNotification`` successfully and will further process + the withdrawal. + :http:statuscode:`400 Bad request`: + The ``C2ECPaymentNotification`` request was malformed or contained invalid parameters. + :http:statuscode:`404 Not found`: + C2EC does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``. + :http:statuscode:`500 Internal Server error`: + The ``C2ECPaymentNotification`` could not be processed due to server side issues. diff --git a/core/api-nonce2ecash.rst b/core/api-nonce2ecash.rst deleted file mode 100644 index ad7c4997..00000000 --- a/core/api-nonce2ecash.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. - 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; - - // 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. -- cgit v1.2.3