diff options
| -rw-r--r-- | api-exchange.rst | 95 | ||||
| -rw-r--r-- | wireformats.rst | 16 |
2 files changed, 84 insertions, 27 deletions
diff --git a/api-exchange.rst b/api-exchange.rst index c396986a..6d94d112 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -118,6 +118,9 @@ possibly by using HTTPS. // Fee charged by the exchange for refreshing a coin of this denomination fee_refresh: Amount; + // Fee charged by the exchange for refunding a coin of this denomination + fee_refund: Amount; + // Signature with purpose // `TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY` over the expiration // dates, value and the key, created with the exchange's master key. @@ -125,7 +128,7 @@ possibly by using HTTPS. } Fees for any of the operations can be zero, but the fields must still be - present. The currency of the `fee_deposit` and `fee_refresh` must match the + present. The currency of the `fee_deposit`, `fee_refresh` and `fee_refund` must match the currency of the `value`. Theoretically, the `fee_withdraw` could be in a different currency, but this is not currently supported by the implementation. @@ -461,8 +464,8 @@ denomination. **Response:** - :status 200: - The operation succeeded, the exchange confirms that no double-spending took place. + :status 200 Ok: + The operation succeeded, the exchange confirms that no double-spending took place. The response will include a `DepositSuccess`_ object. :status 401 Unauthorized: One of the signatures is invalid. :status 403: @@ -536,7 +539,8 @@ denomination. .. code-block:: tsref - interface DepositSuccess { + .. _DepositSuccess: + interface DepositSuccess { // The string constant "DEPOSIT_OK" status: string; @@ -566,25 +570,28 @@ denomination. history: CoinSpendHistoryItem[]; } + .. _CoinSpendHistoryItem: .. code-block:: tsref interface CoinSpendHistoryItem { - // Either "deposit" or "melt" + // Either "deposit" or "melt" or "refund" type: string; - // The total amount of the coin's value absorbed by this transaction + // The total amount of the coin's value absorbed (or restored in the case of a refund) by this transaction amount: Amount; // base32 binary encoding of the transaction data as a // `TALER_DepositRequestPS` or `TALER_RefreshMeltCoinAffirmationPS` + // or `TALER_RefundRequestPS` // struct described in :ref:`Signatures`. Its `purpose` should match our // `type`, `amount_with_fee`, should match our `amount`, and its `size` - // should be consistent. + // should be consistent with the respective struct type. details: string; // the EdDSA :ref:`signature` (binary-only) made with purpose // `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` or - // `TALER_SIGNATURE_WALLET_COIN_MELT` over the transaction's details. + // `TALER_SIGNATURE_WALLET_COIN_MELT` or + // `TALER_SIGNATURE_MERCHANT_REFUND` over the transaction's details. signature: EddsaSignature; } @@ -1094,36 +1101,84 @@ typically also view the balance.) } - ------- Refunds ------- .. note:: - Refunds are currently not implemented (#3641), this documentation is thus - rather preliminary and subject to change. + Refunds are currently not implemented (#3641), this documentation is thus a bit preliminary and may still change. .. _refund: .. http:POST:: /refund Undo deposit of the given coin, restoring its value. - **Request:** + **Request:** The request body must be a `RefundRequest`_ object. + + **Response:** + + :status 200 Ok: + The operation succeeded, the exchange confirms that the coin can now be refreshed. The response will include a `RefundSuccess`_ object. + :status 401 Unauthorized: + Merchant signature is invalid. + :status 404 Not found: + The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match). + + **Details:** + .. _RefundRequest: .. code-block:: tsref - interface RefundRequest { - // If the coin was claimed as a refund, this field should contain the - // retract permission obtained from the merchant, otherwise it should not be - // present. - // TODO: document what the type - retract_perm: any; + interface RefundRequest { + + // Amount to be refunded, can be a fraction of the + // coin's total deposit value (including deposit fee); + // must be larger than the refund fee. + refund_amount: Amount; + + // Refund fee associated with the given coin. + // must be smaller than the refund amount. + refund_fee: Amount; + + // SHA-512 hash of the contact of the merchant with the customer. + H_contract: HashCode; + + // coin's public key, both ECDHE and EdDSA. + coin_pub: CoinPublicKey; + + // 64-bit transaction id of the original transaction between merchant and customer + transaction_id: number; + + // 64-bit transaction id of the refund transaction between merchant and customer + rtransaction_id: number; + + // EdDSA public key of the merchant. + merchant_pub: EddsaPublicKey; + + // EdDSA signature of the merchant affirming the refund. + merchant_sig: EddsaPublicKey; - // Value returned due to the retraction. - retract_value: string; } + .. code-block:: tsref + + .. _RefundSuccess: + interface RefundSuccess { + // The string constant "REFUND_OK" + status: string; + + // the EdDSA :ref:`signature` (binary-only) with purpose + // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the + // exchange affirming the successful refund + sig: EddsaSignature; + + // public EdDSA key of the exchange that was used to generate the signature. + // Should match one of the exchange's signing keys from /keys. It is given + // explicitly as the client might otherwise be confused by clock skew as to + // which signing key was used. + pub: EddsaPublicKey; + } ------------------------------ Administrative API: Key update diff --git a/wireformats.rst b/wireformats.rst index 175b06ea..4e154930 100644 --- a/wireformats.rst +++ b/wireformats.rst @@ -19,13 +19,13 @@ The TEST wire format is used for testing and for integration with Taler's simple "bank" system which in the future might be useful to setup a bank for a local / regional currency or accounting system. Using the TEST wire format in combination with the Taler's bank, it is thus possible to -fully test the Taler system without using real currencies. The wire +fully test the Taler system without using "real" currencies. The wire format for "TEST" is very simple, in that it only specifies an account number in a field "account_number" and the URI of the bank: - * `type`: the string constant `"TEST"` - * `bank_uri`: the URI of the bank - * `account_number`: the number of the exchange's account at the bank (for incoming transfers) + * `type`: the string constant `"test"` + * `bank_uri`: the URI of the bank (starting with `http://` or `https://`) + * `account_number`: the number of the account at the bank The account number given must be a positive 53-bit integer. Additional fields may be present, but are not required. @@ -36,8 +36,6 @@ a merchant with an account at a different bank to use "TEST" to transfer funds across banks. After all, this is for testing and not for real banking. - - SEPA ---- @@ -63,5 +61,9 @@ contain a JSON object with the following fields: The JSON object may optionally contain: * `address`: the address of the Beneficiary +The implementation of the SEPA plugin is currently incomplete. Specifically, we need a working implementation of `libebics` which is a sub-project trying to implement the EBICS [#ebics]_ standard. + .. [#sepa] SEPA - Single Euro Payments Area: - http://www.ecb.europa.eu/paym/sepa/html/index.en.html + http://www.ecb.europa.eu/paym/sepa/html/index.en.html +.. [#ebics] EBCIS - European Banking Computer Interface Standard + http://www.ebics.org/ |