From 399f546e1a12b1c6bc72a495eb59c29746c04e49 Mon Sep 17 00:00:00 2001 From: Joel Häberli Date: Sat, 23 Mar 2024 12:49:36 +0100 Subject: docs: update api spec c2ec --- core/api-c2ec.rst | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 149 insertions(+), 11 deletions(-) diff --git a/core/api-c2ec.rst b/core/api-c2ec.rst index 030b961a..297f7317 100644 --- a/core/api-c2ec.rst +++ b/core/api-c2ec.rst @@ -72,19 +72,19 @@ 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. +operation (the ``WOPID``) 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``. + Register a `WOPID` belonging to a reserve public key. **Request:** - .. ts:def:: C2ECWithdrawalOperationPostRequest + .. ts:def:: C2ECWithdrawRegistration - interface WithdrawRegistration { + interface C2ECWithdrawRegistration { // Maps a nonce generated by the provider to a reserve public key generated by the wallet. - withdrawal_id: ShortHashCode; + wopid: ShortHashCode; // Reserve public key generated by the wallet. // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives) @@ -107,16 +107,16 @@ operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and :http:statuscode:`500 Internal Server error`: The registration of the withdrawal failed due to server side issues. -.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID +.. http:get:: /withdrawal-operation/$WOPID - Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``. + Query information about a withdrawal operation, identified by the ``WOPID``. **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``. + C2EC does not have a withdrawal registered with the specified ``WOPID``. **Details** @@ -138,7 +138,7 @@ operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and // 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; + sender_wire?: string; // Reserve public key selected by the exchange, // only non-null if ``status`` is ``selected`` or ``confirmed``. @@ -147,7 +147,7 @@ operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and } -.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID +.. http:post:: /withdrawal-operation/$WOPID Notifies C2EC about an executed payment for a specific withdrawal. @@ -176,6 +176,144 @@ operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and :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``. + C2EC does not have a withdrawal registered with the specified ``WOPID``. :http:statuscode:`500 Internal Server error`: The ``C2ECPaymentNotification`` could not be processed due to server side issues. + + +-------------- +Taler Wire Gateway +-------------- + +C2EC implements the wire gateway API in order to check for incoming transactions and +let the exchange get proofs of payments. This will allow the C2EC componente to add reserves +and therefore allow the withdrawal of the money. C2EC does not entirely implement all endpoints, +because the it is not needed for the case of C2EC. The endpoints not implemented are not described +further. They will be available but respond with 418 http error code. + +.. http:get:: /config + + Return the protocol version and configuration information about the bank. + This specification corresponds to ``current`` protocol being version **0**. + + **Response:** + + :http:statuscode:`200 OK`: + The exchange responds with a `WireConfig` object. This request should + virtually always be successful. + + **Details:** + + .. ts:def:: WireConfig + + interface WireConfig { + // Name of the API. + name: "taler-wire-gateway"; + + // libtool-style representation of the Bank protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + + // Currency used by this gateway. + currency: string; + + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; + } + +.. http:post:: /transfer + + This API allows the exchange to make a transaction, typically to a merchant. The bank account + of the exchange is not included in the request, but instead derived from the user name in the + authentication header and/or the request base URL. + + To make the API idempotent, the client must include a nonce. Requests with the same nonce + are rejected unless the request is the same. + + **Request:** + + .. ts:def:: TransferRequest + + interface TransferRequest { + // Nonce to make the request idempotent. Requests with the same + // ``request_uid`` that differ in any of the other fields + // are rejected. + request_uid: HashCode; + + // Amount to transfer. + amount: Amount; + + // Base URL of the exchange. Shall be included by the bank gateway + // in the appropriate section of the wire transfer details. + exchange_base_url: string; + + // Wire transfer identifier chosen by the exchange, + // used by the merchant to identify the Taler order(s) + // associated with this wire transfer. + wtid: ShortHashCode; + + // The recipient's account identifier as a payto URI. + credit_account: string; + } + + **Response:** + + :http:statuscode:`200 OK`: + The request has been correctly handled, so the funds have been transferred to + the recipient's account. The body is a `TransferResponse`. + :http:statuscode:`400 Bad request`: + Request malformed. The bank replies with an `ErrorDetail` object. + :http:statuscode:`401 Unauthorized`: + Authentication failed, likely the credentials are wrong. + :http:statuscode:`404 Not found`: + The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. + :http:statuscode:`409 Conflict`: + A transaction with the same ``request_uid`` but different transaction details + has been submitted before. + + **Details:** + + .. ts:def:: TransferResponse + + interface TransferResponse { + // Timestamp that indicates when the wire transfer will be executed. + // In cases where the wire transfer gateway is unable to know when + // the wire transfer will be executed, the time at which the request + // has been received and stored will be returned. + // The purpose of this field is for debugging (humans trying to find + // the transaction) as well as for taxation (determining which + // time period a transaction belongs to). + timestamp: Timestamp; + + // Opaque ID of the transaction that the bank has made. + row_id: SafeUint64; + } + +.. http:post:: /history/incoming + + **Response:** + + .. ts:def:: IncomingReserveTransaction + + interface IncomingReserveTransaction { + type: "RESERVE"; + + // Opaque identifier of the returned record. + row_id: SafeUint64; + + // Date of the transaction. + date: Timestamp; + + // Amount transferred. + amount: Amount; + + // Payto URI to identify the sender of funds. + debit_account: string; + + // The reserve public key extracted from the transaction details. + reserve_pub: EddsaPublicKey; + + } + -- cgit v1.2.3