diff options
-rw-r--r-- | core/api-c2ec.rst (renamed from core/api-nonce2ecash.rst) | 83 |
1 files changed, 47 insertions, 36 deletions
diff --git a/core/api-nonce2ecash.rst b/core/api-c2ec.rst index ad7c4997..030b961a 100644 --- a/core/api-nonce2ecash.rst +++ b/core/api-c2ec.rst @@ -17,7 +17,7 @@ @author Joel Häberli =========================== -The nonce2ecash RESTful API +The C2EC RESTful API =========================== .. note:: @@ -33,45 +33,45 @@ withdrawals through indirect payment channels like credit cards or ATM. Authentication -------------- -Terminals which authenticate against the nonce2ecash API must provide their respective +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 nonce2ecash +Configuration of C2EC ---------------------------- .. http:get:: /config - Return the protocol version and configuration information about the nonce2ecash API. + Return the protocol version and configuration information about the C2EC API. **Response:** :http:statuscode:`200 OK`: - The exchange responds with a `Nonce2ecashConfig` object. This request should + The exchange responds with a `C2ECConfig` object. This request should virtually always be successful. **Details:** - .. ts:def:: Nonce2ecashConfig + .. ts:def:: C2ECConfig - interface Nonce2ecashConfig { + interface C2ECConfig { // Name of the API. - name: "taler-nonce2ecash"; + name: "taler-c2ec"; - // libtool-style representation of the nonce2ecash protocol version, see + // 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 nonce2ecash +Withdrawing using C2EC ----------------------------- -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 +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 @@ -80,7 +80,7 @@ operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and **Request:** - .. ts:def:: WithdrawRegistration + .. ts:def:: C2ECWithdrawalOperationPostRequest interface WithdrawRegistration { // Maps a nonce generated by the provider to a reserve public key generated by the wallet. @@ -114,37 +114,48 @@ operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and **Response:** :http:statuscode:`200 Ok`: - The withdrawal was found and is returned in the response body as ``Withdrawal``. + The withdrawal was found and is returned in the response body as ``C2ECWithdrawalStatus``. :http:statuscode:`404 Not found`: - nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``. + C2EC 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; + .. 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 nonce2ecash about an executed payment for a specific withdrawal. + Notifies C2EC about an executed payment for a specific withdrawal. **Request:** - .. ts:def:: PaymentNotification + .. ts:def:: C2ECPaymentNotification - interface PaymentNotification { + interface C2ECPaymentNotification { // Unique identifier of the provider transaction. provider_transaction_id: string; @@ -160,11 +171,11 @@ operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and **Response:** :http:statuscode:`204 No content`: - nonce2ecash received the ``PaymentNotification`` successfully and will further process + C2EC received the ``C2ECPaymentNotification`` successfully and will further process the withdrawal. :http:statuscode:`400 Bad request`: - The ``PaymentNotification`` request was malformed or contained invalid parameters. + The ``C2ECPaymentNotification`` request was malformed or contained invalid parameters. :http:statuscode:`404 Not found`: - nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``. + C2EC 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. + The ``C2ECPaymentNotification`` could not be processed due to server side issues. |