diff options
Diffstat (limited to 'core/api-c2ec.rst')
| -rw-r--r-- | core/api-c2ec.rst | 181 |
1 files changed, 181 insertions, 0 deletions
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 <http://www.gnu.org/licenses/> + + @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. |