diff options
| -rw-r--r-- | api-overview.rst | 186 | ||||
| -rw-r--r-- | core/api-common.rst | 95 | ||||
| -rw-r--r-- | core/api-exchange.rst | 19 | ||||
| -rw-r--r-- | core/api-merchant.rst | 10 | ||||
| -rw-r--r-- | core/api-taldir.rst | 6 | ||||
| -rw-r--r-- | core/errors.rst | 79 | ||||
| -rw-r--r-- | core/index.rst | 228 | ||||
| -rw-r--r-- | core/taler-uri.rst | 163 | ||||
| -rw-r--r-- | core/wireformats.rst | 62 | ||||
| -rw-r--r-- | index.rst | 1 | ||||
| -rw-r--r-- | libeufin/api-sandbox.rst | 4 | ||||
| -rw-r--r-- | libeufin/index.rst | 1 | ||||
| -rw-r--r-- | taler-nfc-guide.rst | 2 |
13 files changed, 340 insertions, 516 deletions
diff --git a/api-overview.rst b/api-overview.rst deleted file mode 100644 index 281591f6..00000000 --- a/api-overview.rst +++ /dev/null @@ -1,186 +0,0 @@ -=========================== -Taler Project API Ecosystem -=========================== - -This page describes the APIs used in the GNU Taler project. -It includes both APIs that are pre-existing as well as APIs specific -to the project. - -Taler Exchange Public API -========================= - -**Summary**: Public API for the payment service provider component of GNU Taler. - -**Providers**: GNU Taler Exchange - -**Consumers**: Wallet, Merchant - -:doc:`Docs <core/api-exchange>` - -Taler Exchange Management API -============================= - -**Summary**: Management API for the payment service provider component of GNU Taler. - -**Providers**: GNU Taler Exchange - -**Consumers**: Exchange tooling (``taler-exchange-offline``), Auditor - -:doc:`Docs <core/api-exchange>` - -Taler Merchant Backend Public API -================================= - -**Summary**: Allows communication between merchants and users' wallets. - -**Providers**: GNU Taler Merchant backend - -**Consumers**: Wallet - -:doc:`Docs <core/api-merchant>` - -Taler Merchant Backend Private API -================================== - -**Summary**: Allows the merchant to manage Taler-based payments and related functionality. - -**Providers**: GNU Taler Merchant backend - -**Consumers**: Merchant's shop Website backend, Merchant PoS app, Merchant -Backoffice UI - -:doc:`Docs <core/api-merchant>` - -Taler Wallet Core API -===================== - -**Summary**: API to access functionality of the Taler Wallet service running -locally on user's devices. - -**Providers**: wallet-core - -**Consumers**: UIs for the GNU Taler wallet - -Taler Bank Integration API -========================== - -**Summary**: Offered by banks to provide the wallet/user with more information -about ongoing withdrawals of Taler digital cash. - -**Providers**: Taler Exchange fakebank, LibEuFin demobank, Banks (that provide extra Taler support) - -**Consumers**: Taler Wallet - -Taler Bank Access API -===================== - -**Summary**: Protocol to manage access to a bank account by the owner of the account. -Allows access to account balance, transaction list, payment initiation. - -**Providers**: LibEuFin demobank - -**Consumers**: Cashier App, demobank-ui - -Taler Bank Circuits API -======================= - -**Summary**: Allows management of bank user accounts in a regional -currency bank deployment. - -**Providers**: LibEuFin Sandbox demobank - -**Consumers**: demobank-ui - -Taler Wire Gateway API -====================== - -**Summary**: Allows the Taler Exchange to query incoming transactions -and initiate payments with a protocol that abstracts away details of the underlying -banking system. - -**Providers**: Taler Exchange fakebank, LibEuFin Nexus, (deprecated) PyBank - -**Consumers**: GNU Taler Exchange, Wire Auditor (?) - -x-taler-bank API -================ - -**Summary**: Protocol for testing/examples to access a bank account (transactions, payment initiation) - -**Providers**: Taler Fakebank (?) - -**Consumers**: ?? - -Taler Sync API -============== - -**Summary**: Encrypted Data blob storage and retrieval API with payments for -storage handled by GNU Taler payments. - -**Providers**: GNU Taler Sync service - -**Consumers**: Taler Wallet - -Taler Auditor API -================= - -TBD. - -Taldir API -========== - -TBD. - -Taler Mailbox API -================= - -TBD. - -Anastasis Provider Public API -============================= - -**Summary**: Backup for secret splitting backup and recovery with GNU Anastasis providers. - -**Providers**: GNU Anastasis providers - -**Consumers**: Anastasis core client implementations (C implementation, TypeScript implementation) - -Anastasis Reducer API -===================== - -**Summary**: API used to step through the backup and recovery process of GNU Anastasis. - -**Providers**: Anastasis core client implementations (C implementation, TypeScript implementation) - -**Consumers**: Anastasis UIs (CLI, GTK, anastasis-webui) - -LibEuFin Nexus API -================== - -**Summary**: API used to configure and access LibEuFin nexus, a generic server -that supports multiple protocols to access a bank account. - -**Providers**: LibEuFin Nexus service - -**Consumers**: ``libeufin-cli``, (future) LibEuFin Web UI - -LibEuFin Sandbox API -==================== - -**Summary** API used to configure the LibEuFin sandbox, a simulator -for various protocols related to core banking that would typically offered -by banks. - -**Providers**: LibEuFin Sandbox service - -**Consumers**: ``libeufin-cli``, (future) LibEuFin Web UI - -EBICS -===== - -**Summary**: Allows businesses/banks/consumers to exchange data with a bank's -core banking system. - -**Consumers**: LibEuFin Nexus - -**Providers**: LibEuFin Sandbox, Banks diff --git a/core/api-common.rst b/core/api-common.rst index 9d123978..b91a8a6d 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -695,13 +695,23 @@ uses 512-bit hash codes (64 bytes). }; -.. _officer-pub: +.. _AmlDecisionState: +.. sourcecode:: c + + enum TALER_AmlDecisionState { + NORMAL, PENDING, FROZEN + }; + +.. _AmlOfficerPublicKeyP: .. sourcecode:: c struct TALER_AmlOfficerPublicKeyP { uint8_t eddsa_pub[32]; }; +.. _AmlOfficerPrivateKeyP: +.. sourcecode:: c + struct TALER_AmlOfficerPrivateKeyP { uint8_t eddsa_priv[32]; }; @@ -1663,3 +1673,86 @@ within the struct GNUNET_TIME_AbsoluteNBO end_date; struct TALER_PaytoHash h_wire; }; + + +.. _TALER_MasterAmlOfficerStatusPS: +.. sourcecode:: c + + struct TALER_MasterAmlOfficerStatusPS { + /** + * purpose.purpose = TALER_SIGNATURE_MASTER_AML_KEY + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_TimestampNBO change_date; + struct TALER_AmlOfficerPublicKeyP officer_pub; + struct GNUNET_HashCode h_officer_name GNUNET_PACKED; + uint32_t is_active GNUNET_PACKED; + }; + +.. _TALER_PartnerConfigurationPS: +.. sourcecode:: c + + struct TALER_PartnerConfigurationPS { + /** + * purpose.purpose = TALER_SIGNATURE_MASTER_PARNTER_DETAILS + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_MasterPublicKeyP partner_pub; + struct GNUNET_TIME_TimestampNBO start_date; + struct GNUNET_TIME_TimestampNBO end_date; + struct GNUNET_TIME_RelativeNBO wad_frequency; + struct TALER_AmountNBO wad_fee; + struct GNUNET_HashCode h_url; + }; + +.. _TALER_ReserveOpenPS: +.. sourcecode:: c + + struct TALER_ReserveOpenPS { + /** + * Purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_OPEN + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_AmountNBO reserve_payment; + struct GNUNET_TIME_TimestampNBO request_timestamp; + struct GNUNET_TIME_TimestampNBO reserve_expiration; + uint32_t purse_limit; + }; + +.. _TALER_ReserveClosePS: +.. sourcecode:: c + + struct TALER_ReserveClosePS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_CLOSE + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_TimestampNBO request_timestamp; + struct TALER_PaytoHashP target_account_h_payto; + }; + +.. _TALER_WalletReserveAttestRequestSignaturePS: +.. sourcecode:: c + + struct TALER_ReserveAttestRequestPS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_ATTEST_REQUEST + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_TimestampNBO request_timestamp; + struct GNUNET_HashCode h_details; + }; + +.. _TALER_ExchangeAttestPS: +.. sourcecode:: c + + struct TALER_ExchangeAttestPS { + /** + * purpose.purpose = TALER_SIGNATURE_EXCHANGE_RESERVE_ATTEST_DETAILS + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_TimestampNBO attest_timestamp; + struct GNUNET_TIME_TimestampNBO expiration_time; + struct TALER_ReservePublicKeyP reserve_pub; + struct GNUNET_HashCode h_attributes; + }; diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 6628e8ba..dbceb41e 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1316,7 +1316,7 @@ and freeze or unfreeze accounts suspected of money laundering. new_threshold: Amount; // Who made the decision? - decider_pub: TALER_AmlOfficerPublicKeyP; + decider_pub: AmlOfficerPublicKeyP; } @@ -1382,7 +1382,7 @@ and freeze or unfreeze accounts suspected of money laundering. h_payto: PaytoHash; // What is the new AML state (e.g. frozen, unfrozen, etc.) - // Numerical values are defined in `enum TALER_AmlDecisionState`. + // Numerical values are defined in `AmlDecisionState`. new_state: Integer; // Signature by the AML officer over a @@ -4797,8 +4797,9 @@ Wallet-to-wallet transfers .. _exchange_wads: +---- Wads -^^^^ +---- .. note:: @@ -4984,7 +4985,7 @@ KYC status updates :http:statuscode:`202 Accepted`: The user should be redirected to the provided location to perform the required KYC checks to open the account. Afterwards, the - ``/kyc/`` request should be repeated. + ``/kyc-check/`` request should be repeated. The response will be an `AccountKycRedirect` object. :http:statuscode:`204 No content`: The exchange is not configured to perform KYC and thus @@ -5053,10 +5054,10 @@ KYC status updates Details on the request depend on the specific KYC logic that was used. - If $LOGIC is "oauth2.0", the query parameters are: + If the KYC plugin logic is OAuth 2.0, the query parameters are: - :query code=CODE: OAuth 2.0 code argument. - :query state=CODE: OAuth 2.0 state argument with the H_PAYTO. + :query code=CODE : OAuth 2.0 code argument. + :query state=STATE: OAuth 2.0 state argument with the H_PAYTO. .. note:: @@ -5165,7 +5166,7 @@ naturally expire and possibly (5) wire the funds to a designated account. interface ReserveOpenRequest { // Signature of purpose // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN`` over - // a `TALER_ReserveOpenRequestSignaturePS`. + // a `TALER_ReserveOpenPS`. reserve_sig: EddsaSignature; // Array of payments made towards the cost of the @@ -5323,7 +5324,7 @@ naturally expire and possibly (5) wire the funds to a designated account. interface ReserveAttestResponse { // Signature of purpose // ``TALER_SIGNATURE_EXCHANGE_RESERVE_ATTEST_DETAILS`` over - // a `TALER_ExchangeReserveAttestDetailsSignaturePS`. + // a `TALER_ExchangeAttestPS`. exchange_sig: EddsaSignature; // Exchange public key used to create the diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 1ff0df22..493de49a 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3000,7 +3000,7 @@ while the template provides all of the other contract details. The typical user-experience with templatates is that the user first scans a QR code or clicks on a taler://-URI which contains a ``pay-template`` (see `LSD -0006 <https://lsd.gnunet.org/lsd0006/>`). The URI specifies which values the +0006 <https://lsd.gnunet.org/lsd0006/>`__). The URI specifies which values the user should supply, currently either nothing, the amount, the order summary or both. The URI may also specify defaults or partial defaults for those values. After the user has supplied those values, the wallet will use the @@ -3156,7 +3156,7 @@ Inspecting template templates_list: TemplateEntry[]; } - The `TemplatesEntry` object describes a template. It has the following structure: + The `TemplateEntry` object describes a template. It has the following structure: .. ts:def:: TemplateEntry @@ -3369,11 +3369,11 @@ Inspecting webhook } - The WebhookEntry object describes a webhook. It has the following structure: + The `WebhookEntry` object describes a webhook. It has the following structure: - .. ts:def:: WebhookSummaryResponse + .. ts:def:: WebhookEntry - interface Webhook { + interface WebhookEntry { // Webhook identifier, as found in the webhook. webhook_id: string; diff --git a/core/api-taldir.rst b/core/api-taldir.rst index 88fe5ce1..1639e36d 100644 --- a/core/api-taldir.rst +++ b/core/api-taldir.rst @@ -63,14 +63,16 @@ Configuration information name: "taler-directory"; // Supported registration methods - methods: Method[]; + methods: TaldirMethod[]; // fee for one month of registration monthly_fee: Amount; } - interface Method { + .. ts:def:: TaldirMethod + + interface TaldirMethod { // Name of the method, e.g. "email" or "sms". name: string; diff --git a/core/errors.rst b/core/errors.rst deleted file mode 100644 index f7b490da..00000000 --- a/core/errors.rst +++ /dev/null @@ -1,79 +0,0 @@ -Errors and Testing -################## - -This page lists errors that occur during the operation of GNU Taler. - - -Error Conditions -================ - -``EXCHANGE_KEYS_INFO_UNAVAILABLE`` - An exchange does not return an HTTP 200 response for the ``/keys`` request. - -``EXCHANGE_KEYS_INFO_MALFORMED`` - The exchange returned an HTTP 200 response, but the body - did not confirm the schema for ``/keys``. - -``EXCHANGE_KEYS_INFO_OUTDATED`` - The exchange returned a response for ``/keys`` with an issuing date - earlier than the previous one. - - **Type**: Warning. - **Handling**: The wallet should ignore the response and try again later. - -``EXCHANGE_WIRE_INFO_UNAVAILABLE`` - An exchange does not return an HTTP 200 response for the ``/wire`` request. - -``EXCHANGE_WIRE_INFO_MALFORMED`` - The exchange returned an HTTP 200 response, but the body - did not confirm the schema for ``/wire``. - -``EXCHANGE_PROTOCOL_VERSION_UNSUPPORTED`` - An exchange's ``/keys`` response indicates a version number that - is not compatible with the client. - -``EXCHANGE_MASTER_PUB_CHANGED`` - An exchange returns a ``/keys`` response with a master public key that differs - from a previous response. - -``EXCHANGE_DENOM_MISSING`` - A denomination that has been previously offered by the exchange is not offered anymore, - even though it hasn't expired yet. - -``EXCHANGE_DENOM_SIGNATURE_INVALID`` - The signature by the exchange's master key on a denomination is invalid. - -``EXCHANGE_DENOM_CHANGED`` - A denomination offered by the exchange is valid (syntax, content, signature), - but has different information (fees, expiry) for the same public key compared - to a previous keys response. - -``EXCHANGE_DENOM_CONTENT_INVALID`` - A denomination offered by the exchange is syntactically correct, but - semantically malformed. For example, the expiration dates are not in the - correct temporal order or the denomination public key can't be decoded. - -``EXCHANGE_WIRE_FEE_SIGNATURE_INVALID`` - The signature by the exchange's master key on a wire fee is invalid. - -``EXCHANGE_DENOMS_INADEQUATE`` - The denominations currently offered are inadequate for withdrawing digital cash. - This can happen when all offered denominations are past their withdrawal expiry date. - -``EXCHANGE_RESERVE_STATUS_UNAVAILABLE`` - -``WALLET_BUG`` - The wallet encountered a programming bug that should be reported to the developers. - - **Handling**: The wallet should allow the user to report this bug to the wallet developers. - - -End-To-End Testing Scenarios -============================ - -This section describes some advanced end-to-end testing scenarios that should -eventually be covered by our tests. - -* Reserve is created, closed, and then money is sent again to the reserve. - -* Amount from recoup should end up in customer's account again. diff --git a/core/index.rst b/core/index.rst index f44bc247..4f52c9da 100644 --- a/core/index.rst +++ b/core/index.rst @@ -23,9 +23,13 @@ Core Protocol Specification --------------------------- -The *Protocol Specification* defines the HTTP-based, predominantly RESTful +This chapter describes the APIs used in the GNU Taler project. It includes +both APIs that are pre-existing as well as APIs specific to the project. + +These *protocol specification* defines the HTTP-based, predominantly RESTful interfaces between the core components of Taler. + .. toctree:: :maxdepth: 2 @@ -41,6 +45,222 @@ interfaces between the core components of Taler. api-bank-merchant api-bank-integration api-bank-access - wireformats - taler-uri - errors + + + +Taler Exchange Public API +========================= + +**Summary**: Public API for the payment service provider component of GNU Taler. + +**Providers**: GNU Taler Exchange + +**Consumers**: Wallet, Merchant + +:doc:`Docs <api-exchange>` + + +Taler Exchange Management API +============================= + +**Summary**: Management API for the payment service provider component of GNU Taler. + +**Providers**: GNU Taler Exchange + +**Consumers**: Exchange tooling (``taler-exchange-offline``), Auditor + +:doc:`Docs <api-exchange>` + + +Taler Merchant Backend Public API +================================= + +**Summary**: Allows communication between merchants and users' wallets. + +**Providers**: GNU Taler Merchant backend + +**Consumers**: Wallet + +:doc:`Docs <api-merchant>` + + +Taler Merchant Backend Private API +================================== + +**Summary**: Allows the merchant to manage Taler-based payments and related functionality. + +**Providers**: GNU Taler Merchant backend + +**Consumers**: Merchant's shop Website backend, Merchant PoS app, Merchant +Backoffice UI + +:doc:`Docs <api-merchant>` + + +Taler Wallet Core API +===================== + +**Summary**: API to access functionality of the Taler Wallet service running +locally on user's devices. + +**Providers**: wallet-core + +**Consumers**: UIs for the GNU Taler wallet + + +Taler Bank Integration API +========================== + +**Summary**: Offered by banks to provide the wallet/user with more information +about ongoing withdrawals of Taler digital cash. + +**Providers**: Taler fakebank, LibEuFin demobank, Banks (that provide extra Taler support) + +**Consumers**: Taler Wallet + +:doc:`Docs <api-bank-integration>` + + +Taler Bank Access API +===================== + +**Summary**: Protocol to manage access to a bank account by the owner of the account. +Allows access to account balance, transaction list, payment initiation. + +**Providers**: LibEuFin demobank, Taler Fakebank (partial) + +**Consumers**: Cashier App, demobank-ui + +:doc:`Docs <api-bank-access>` + + +Taler Bank Circuits API +======================= + +**Summary**: Allows management of bank user accounts in a regional +currency bank deployment. + +**Providers**: LibEuFin Sandbox demobank + +**Consumers**: demobank-ui + + +Taler Wire Gateway API +====================== + +**Summary**: Allows the Taler Exchange to query incoming transactions +and initiate payments with a protocol that abstracts away details of the underlying +banking system. + +**Providers**: Taler fakebank, LibEuFin Nexus, Depoloymerization wire gateway + +**Consumers**: GNU Taler Exchange, Wire Auditor + +:doc:`Docs <api-wire>` + + +Taler Sync API +============== + +**Summary**: Encrypted Data blob storage and retrieval API with payments for +storage handled by GNU Taler payments. + +**Providers**: GNU Taler Sync service + +**Consumers**: Taler Wallet + +:doc:`Docs <api-sync>` + + + +Taler Auditor API +================= + +**Summary**: Reporting of certain transactions or potential problems directly to the auditor. + +**Providers**: GNU Taler Auditor service + +**Consumers**: GNU Taler Merchant, eventually Taler Wallet + +:doc:`Docs <api-auditor>` + + + +Taldir API +========== + +**Summary**: Looking up of Taler mailboxes associated with particular Internet service addresses. + +**Providers**: GNU TalDir service + +**Consumers**: GNU Taler Wallet + +:doc:`Docs <api-taldir>` + + +Taler Mailbox API +================= + +**Summary**: Tansmission of encrypted payment messages between Taler wallets. + +**Providers**: GNU Taler Mailbox service + +**Consumers**: GNU Taler Wallet + +:doc:`Docs <api-mailbox>` + + +Anastasis Provider Public API +============================= + +**Summary**: Backup for secret splitting backup and recovery with GNU Anastasis providers. + +**Providers**: GNU Anastasis providers + +**Consumers**: Anastasis core client implementations (C implementation, TypeScript implementation) + + +Anastasis Reducer API +===================== + +**Summary**: API used to step through the backup and recovery process of GNU Anastasis. + +**Providers**: Anastasis core client implementations (C implementation, TypeScript implementation) + +**Consumers**: Anastasis UIs (CLI, GTK, anastasis-webui) + + +LibEuFin Nexus API +================== + +**Summary**: API used to configure and access LibEuFin nexus, a generic server +that supports multiple protocols to access a bank account. + +**Providers**: LibEuFin Nexus service + +**Consumers**: ``libeufin-cli``, (future) LibEuFin Web UI + + +LibEuFin Sandbox API +==================== + +**Summary** API used to configure the LibEuFin sandbox, a simulator +for various protocols related to core banking that would typically offered +by banks. + +**Providers**: LibEuFin Sandbox service + +**Consumers**: ``libeufin-cli``, (future) LibEuFin Web UI + + +EBICS +===== + +**Summary**: Allows businesses/banks/consumers to exchange data with a bank's +core banking system. + +**Consumers**: LibEuFin Nexus + +**Providers**: LibEuFin Sandbox, Banks + + diff --git a/core/taler-uri.rst b/core/taler-uri.rst deleted file mode 100644 index 7b897ba1..00000000 --- a/core/taler-uri.rst +++ /dev/null @@ -1,163 +0,0 @@ -.. _taler-uri-scheme: - -======================= -The taler:// URI scheme -======================= - -The ``taler`` URI scheme represents actions that are processed by a Taler -wallet. This document uses `RFC 6570 URI templates -<https://tools.ietf.org/html/rfc6570>`__ to describe the syntax. - -The basic syntax is as follows: - -.. code:: none - - taler://{action}/{+rest} - -The alternative scheme name ``taler+http`` indicates that the referenced resource is to be accessed -via plain HTTP instead of HTTPS. This **should** only be used for testing. A production -version of the wallet **may** reject such URIs. - --------------------- -Requesting a Payment --------------------- - -Payments are requested with the ``pay`` action. The parameters are a hierarchical identifier for the requested payment: - -.. code:: none - - taler://pay/{merchant_host}{/merchant_prefix_path*}/{order_id}/{session_id}{?c}{#ssid} - -* ``merchant_host`` is the hostname (and optionally port) of the merchant. -* ``merchant_prefix_path`` is an optional list of path components that identifies the path prefix of the merchant base URL. -* ``order_id`` is the order ID that the customer is asked to pay for. -* ``session_id`` is the optional session ID under which the payment takes place. -* ``c`` is the optional high-entropy order `ClaimToken`. -* ``ssid`` is the optional WLAN SSID that the merchant can offer the wallet to connect to for Internet connectivity. - -Examples: - -.. code:: none - - # Example 1: - # Order ID "ORD123", no session ID. - # Merchant backend base URL https://backend.test.taler.net/ - taler://pay/test.taler.net/ORD123/ - - # Example 2: - # Order ID "ORD123", no session ID. - # Merchant backend base URL https://backend.test.taler.net/instances/x1/ - taler://pay/test.taler.net/instances/x1/ORD123/ - - # Example 3: - # Order ID "ORD123", session ID "ABC123". - # Merchant backend base URL https://backend.test.taler.net/ - taler://pay/test.taler.net/ORD123/ABC123 - - # INVALID Example 1: - # When no session ID is given, the slash must still be present. - taler://pay/test.taler.net/ORD123 - ------------------------- -Withdrawing (Initiation) ------------------------- - -The action ``withdraw`` is used to trigger a bank-integrated withdrawal operation. - -.. code:: none - - taler://withdraw/{bank_host}{/bank_prefix_path*}/{withdrawal_uid}{#ssid} - -* ``bank_host`` is the hostname of the bank. -* ``bank_prefix_path`` is an optional list of path components that identifies the path prefix of the bank integration API base URL. -* ``withdrawal_uid`` is the unique ID of the withdrawal operation. -* ``ssid`` is the optional WLAN SSID that the bank (typically in an ATM scenario) can offer the wallet - to connect to for Internet connectivity. - --------------------------- -Withdrawing (Confirmation) --------------------------- - -.. code:: none - - taler://notify-reserve/{reserve_pub} - -This action notifies the wallet that the status of a reserve has changed. It is used -by the bank to indicate that the withdrawal has been confirmed by the user (e.g. via 2FA / mTAN / ...). -The wallet then re-checks the status of all unconfirmed reserves. - -Optionally, ``reserve_pub`` can be specified to also indicate the reserve that -has been updated. - - ---------- -Refunding ---------- - -A ``taler://refund`` URI instructs the wallet to download and apply available refunds for an already paid order. - -.. code:: none - - taler://refund/{merchant_host}{/merchant_prefix_path*}/{order_id}/{#ssid} - taler+http://refund/{merchant_host}{/merchant_prefix_path*}/{order_id}/{#ssid} - -* ``merchant_host`` is the hostname of the merchant. -* ``merchant_prefix_path`` is an optional list of path components that identifies the path prefix of the merchant base URL. -* ``order_id`` is the order ID to check for refunds. -* ``ssid`` is the optional WLAN SSID that the merchant can offer the wallet to connect to for Internet connectivity. - - -------- -Tipping -------- - -A tipping URI instructs the wallet to download information about a tip from -a merchant and ask the user to accept/decline it. - -.. code:: none - - taler://tip/{merchant_host}{/merchant_prefix_path*}/{tip_id}/{#ssid} - -* ``merchant_host`` is the hostname of the merchant. -* ``merchant_prefix_path`` is an optional list of path components that identifies the path prefix of the merchant base URL. -* ``tip_id`` uniquely identifies the tip. -* ``ssid`` is the optional WLAN SSID that the merchant can offer the wallet to connect to for Internet connectivity. - - ---------------------- -Peer-to-peer payments ---------------------- - -A pay-push URI instructs the wallet to accept a P2P push payment. - -.. code:: none - - taler://pay-push/{exchange_host}{/exchange_prefix_path*}/{contract_priv} - -* ``exchange_host`` is the hostname of the exchange. -* ``exchange_prefix_path`` is an optional list of path components that identifies the path prefix of the exchange base URL. -* ``contract_priv`` is the private key of the peer push payment contract stored at the exchange - -FIXME: pay-pull URIs missing! - ----------------- -Adding exchanges ----------------- - -A ``taler://exchange/`` URI instructs the wallet to display a prompt to the user, asking -the user to confirm/decline adding the exchange to the list of trusted exchanges. - -.. code:: none - - taler://exchange/{exchange_host}{/exchange_prefix_path*}/ - ---------------- -Adding auditors ---------------- - -A ``taler://auditor/`` URI instructs the wallet to display a prompt to the user, asking -the user to confirm/decline adding the auditor to the list of trusted auditors. - -.. code:: none - - taler://auditor/{auditor_host}{/auditor_prefix_path*}/ diff --git a/core/wireformats.rst b/core/wireformats.rst deleted file mode 100644 index 591f1ce8..00000000 --- a/core/wireformats.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _wireformats: - -Wire Transfer Methods -===================== - -A wire transfer is essential for the exchange to transfer funds into a merchant's -account upon a successful deposit (see :ref:`deposit request <deposit>`). The -merchant has to include the necessary information for the exchange to initiate the -wire transfer. - -The information required for a wire transfer depends on the method of wire transfer -used. Since the wire transfers differ for each region, we document here the -ones currently supported by the exchange. - -X-TALER-BANK ------------- - -The ``x-taler-bank`` wire format is used for testing and for integration with Taler's -simple "bank" system which in the future might be useful to set up a bank -for a local / regional currency or accounting system. Using the ``x-taler-bank`` -wire method in combination with the Taler's bank, it is thus possible to -fully test the Taler system without using "real" currencies. The URL -format for ``x-taler-bank`` is simple, in that it only specifies an account -number and the origin (domain and optionally a port) of the bank: - -.. code-block:: none - - payto://x-taler-bank/BANK_URI/ACCOUNT_IDENTIFIER - -The account identifier given must be a non-empty alphanumeric ASCII string. As with -any ``payto://`` URI, additional fields may be present (after a ``?``), but -are not required. The ``BANK_URI`` may include a port number. If none is -given, ``https`` over port 443 is assumed. If a port number is -given, ``http`` over the given port is to be used. Note that this -means that you cannot run an ``x-taler-bank`` over ``https`` on a -non-canonical port. - -Note that a particular exchange is usually only supporting one particular bank -with the ``x-taler-bank`` wire format, so it is not possible for a merchant with -an account at a different bank to use ``x-taler-bank`` to transfer funds across -banks. After all, this is for testing and not for real banking. - -SEPA ----- - -The Single Euro Payments Area (SEPA) [#sepa]_ is a regulation for electronic -payments. Since its adoption in 2012, all of the banks in the Eurozone and some -banks in other countries adhere to this standard for sending and receiving -payments. Note that the currency of the transfer will (currently) always be ``EUR``. In -case the receiving account is in a currency other than ``EUR``, the receiving bank -may convert the amount into that currency; currency exchange charges may be -levied by the receiving bank. - -For the merchant to receive deposits through SEPA, the deposit request must -follow the ``payto://`` specification for SEPA: - -.. code-block:: none - - payto://iban/IBAN - -.. [#sepa] SEPA - Single Euro Payments Area: - http://www.ecb.europa.eu/paym/sepa/html/index.en.html @@ -60,7 +60,6 @@ Documentation Overview taler-exchange-setup-guide taler-merchant-manual taler-wallet-cli-manual - taler-nfc-guide.rst taler-merchant-api-tutorial taler-merchant-pos-terminal taler-auditor-manual diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst index 71be7cb6..ee9111d4 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -407,8 +407,8 @@ Cashouts :http:statuscode:`404 Not found`: ``$cashoutId`` is not found. Note: that happens also when ``$cashoutId`` got aborted before this request. - :http:statuscode:`409 Conflict`: - At least the following two cases are possible + :http:statuscode:`409 Conflict`: + At least the following two cases are possible * an institutional user (``admin`` or ``bank``) tried the operation * the user changed their cash-out address between the creation and the confirmation of ``$cashoutId``. diff --git a/libeufin/index.rst b/libeufin/index.rst index 1fab9915..dd879e52 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -19,5 +19,4 @@ LibEuFin is a project providing free software tooling for European FinTech. frontend nexus-tutorial local-currencies-tutorial - demo-deployment-gv int-deployment-gv diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst index fbc7a9e7..f456f6fd 100644 --- a/taler-nfc-guide.rst +++ b/taler-nfc-guide.rst @@ -93,7 +93,7 @@ and :http:get:`[/instances/$INSTANCE]/private/orders` endpoints. * by manually entering it in the command-line wallet * **via NFC** (explained in this guide) - The details of ``taler://`` URIs are specified :ref:`here <taler-uri-scheme>`. + The details of ``taler://`` URIs are specified in :ref:`LSD 0006 <https://lsd.gnunet.org/lsd0006/>`_. 3. The wallet processes the ``taler://pay/`` URI. In this example, we use the command-line wallet: |