From 393758005dcdc2ff95ffc654d43719da3370fae5 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Thu, 28 Jan 2016 15:19:06 +0100 Subject: fixing administrative bank API --- api-bank.rst | 35 +++++++++++++++-------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/api-bank.rst b/api-bank.rst index ea07e3a8..0c1002fd 100644 --- a/api-bank.rst +++ b/api-bank.rst @@ -1,5 +1,5 @@ ========= -Banks API +Bank API ========= The following APIs are served from banks, in order to allow mints to @@ -7,12 +7,12 @@ deposit funds to money recipients. A typical scenario for calling this APIs is after a merchant has deposited coins to the mint, and the mint needs to give real money to the merchant. --------- -Test API --------- +------------------ +Administrative API +------------------ -This API is useful for testing purposes, as no real money will be -involved. +This is `local` API, meant to make the bank communicate with trusted entities, +namely mints. .. _bank-deposit: .. http:post:: /admin/add/incoming @@ -21,7 +21,8 @@ involved. **Response:** -:status 200: The request has been correctly handled, so the funds have been transferred to the merchant's account +:status 200 OK: The request has been correctly handled, so the funds have been transferred to +the recipient's account **Details:** .. _BankDepositRequest: @@ -31,18 +32,12 @@ involved. // JSON 'amount' object. The amount the caller wants to transfer // to the recipient's count - f: Amount; - - // The transaction id (meant as in 'Taler transaction id') according - // to which the caller is now giving money to the recipient. That way, - // the recipient can link inwards money to commercial activity. - tid: number; - - // The recipient's account identificator. For this testing purpose, the - // account format will the normal IBAN format having the token "TEST" - // in place of the country code and having the check digit removed. For instance, - // if "SA03 8000 0000 6080 1016 7519" were a valid Saudi Arabian IBAN, then - // "TEST 8000 0000 6080 1016 7519" would be a correct test account number as well. - account: string; + amount: Amount; + + // The id of this wire transfer + wid: base32; + + // The recipient's account identificator + account: number; } -- cgit v1.2.3 From 48d7b73e77f4567ce9dba6ee1f2024e9c001d4c8 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Mon, 1 Feb 2016 20:04:41 +0100 Subject: bank: specing errors --- api-bank.rst | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/api-bank.rst b/api-bank.rst index 0c1002fd..d59cfd54 100644 --- a/api-bank.rst +++ b/api-bank.rst @@ -23,21 +23,34 @@ namely mints. :status 200 OK: The request has been correctly handled, so the funds have been transferred to the recipient's account + +:status 400 Bad Request: The bank replies a `BankIncomingError`_ object **Details:** - .. _BankDepositRequest: - .. code-block:: tsref +.. _BankDepositRequest: +.. code-block:: tsref - interface BankDepositRequest { - - // JSON 'amount' object. The amount the caller wants to transfer - // to the recipient's count - amount: Amount; + interface BankDepositRequest { + + // JSON 'amount' object. The amount the caller wants to transfer + // to the recipient's count + amount: Amount; - // The id of this wire transfer - wid: base32; + // The id of this wire transfer + wid: base32; - // The recipient's account identificator - account: number; + // The recipient's account identificator + account: number; - } + } + +.. _BankIncomingError: +.. code-block:: tsref + + interface BankIncomingError { + + // The reason which made this request fail. Typically due to malfomation + // of the POST's body + reason: string + + } -- cgit v1.2.3 From 40cc23265e7e01d2024c7dead5ee1d7b5730a7d4 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Fri, 5 Feb 2016 22:22:47 +0100 Subject: documenting PIN/TAN aware reserve creation --- integration-bank.rst | 61 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 37 insertions(+), 24 deletions(-) diff --git a/integration-bank.rst b/integration-bank.rst index c90bf042..d8e17a9f 100644 --- a/integration-bank.rst +++ b/integration-bank.rst @@ -17,36 +17,49 @@ For JavaScript code examples, see :ref:`communication`. Reserve Creation Request ------------------------- -The bank website can request the creation of a :term:`reserve`. Note that the -user will always be prompted by the wallet before a reserve is created in the -wallet. +The bank website can request the creation of a :term:`reserve`. This operation +will require the user to specify the mint where he wants to create the reserve +and the resolution of a CAPTCHA, before any action will be taken. -As a result of the reserve creation request, the following steps will happen insequence: - 1. The wallet will prompt the user for the *mint base URL* and ask the user to - confirm creating the reserve. +As a result of the reserve creation request, the following steps will happen in sequence: + 1. The user chooses the desired amount from the bank's form + 2. Upon confirmation, the wallet fetches the desired amount from the user-filled form and + prompts the user for the *mint base URL*. Then ask the user to confirm creating the + reserve. 2. The wallet will create a key pair for the reserve. - 3. The wallet will make a request to the bank, containing - the reserve's public key and the mint base URL chosen by the user + 3. The wallet will request the CAPTCHA page to the bank. In that request's parameters it + communicates the desired amount, the reserve's public key and the mint base URL to the + bank + 4. Upon successful resolution of the CAPTCHA by the user, the bank initiates the reserve + creation according to the gotten parameters. -The bank should then take steps that will establish the reserve at the -customer's requested mint. This could, depending on the bank and mint, either -be a SEPA wire transfer or some other means. + +Note that the reserve creation can be done by a SEPA wire transfer or some other means, +depending on the user's bank and chosen mint. In response to the reserve creation request, the Taler wallet MAY cause the current document location to be changed, in order to navigate to a wallet-internal confirmation page. The bank requests reserve creation with the ``taler-create-reserve`` event. -The event data must be a JavaScript ``object`` with the following fields: - - * ``form_id``: The ``id`` of the ``form`` HTML element that contains data for the HTTP POST request - that confirms reserve creation with the bank. - * ``input_amount``: Amount of the reserve in the format ``N.C CUR``, where ``CUR`` is the - currency code. - * ``mint_rcv``: The ``id`` of the ``input`` HTML element in the reserve creation form - that will contain mint base URL for the reserve - * ``input_pub``: The ``id`` of the ``input`` HTML element in the reserve creation form - that will contain the reserve's public key. - -Note that the bank website MUST contain an HTML form with the data required for the request and -input fields for receiving data from the mint. +The event data must be a `CreateReserveDetail`_: + + +.. _CreateReserveDetail: +.. code-block:: tsref + + interface CreateReserveDetail { + + // JSON 'amount' object. The amount the caller wants to transfer + // to the recipient's count + amount: Amount; + + // CAPTCHA's page URL which needs the following parameters + // query parameters: + // amount_value + // amount_fraction + // amount_currency + // reserve_pub + // mint + callback_url: string; + } -- cgit v1.2.3 From d7b13177d5b73c9bad90fc2828ae4ee1da788f77 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 6 Feb 2016 19:46:01 +0100 Subject: document test wireformat --- wireformats.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/wireformats.rst b/wireformats.rst index f759bf62..be090596 100644 --- a/wireformats.rst +++ b/wireformats.rst @@ -12,6 +12,26 @@ The information required for wire transfer depends on the type of wire transfer used. Since the wire transfers differ for each region, we document here the ones currently supported by the mint. +TEST +---- + +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 +format for "TEST" is very simple, in that it only specifies an account +number in a field "account_number". The account number given must be +a positive 53-bit integer. Additional fields may be present, but are +not required. + +For the merchant or mint to receive deposits through TEST, the deposit +request must thus contain a JSON object with the following fields: + + * `type`: the string constant `"TEST"` + * `account_number`: the account number of the merchant at the bank + + SEPA ---- -- cgit v1.2.3 From 98e3d9107e8292d406b01cac364fb282b096f6a1 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Tue, 9 Feb 2016 15:03:50 +0100 Subject: what bank replies upon succesful reserve creation --- integration-bank.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/integration-bank.rst b/integration-bank.rst index d8e17a9f..4ebf2f11 100644 --- a/integration-bank.rst +++ b/integration-bank.rst @@ -31,8 +31,8 @@ As a result of the reserve creation request, the following steps will happen in communicates the desired amount, the reserve's public key and the mint base URL to the bank 4. Upon successful resolution of the CAPTCHA by the user, the bank initiates the reserve - creation according to the gotten parameters. - + creation according to the gotten parameters. Together with `200 OK` status code sent back + to the wallet, it gets also a `ReserveCreated`_ object. Note that the reserve creation can be done by a SEPA wire transfer or some other means, depending on the user's bank and chosen mint. @@ -63,3 +63,14 @@ The event data must be a `CreateReserveDetail`_: // mint callback_url: string; } + +.. _ReserveCreated: +.. code-block:: tsref + + interface ReserveCreated { + + // A URL informing the user about the succesfull outcome + // of his operation + redirect_url: string; + + } -- cgit v1.2.3 From 05c91fd72aac7edfff45b286ade2be3c747583bc Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 10 Feb 2016 14:32:27 +0100 Subject: addressing 4134 --- integration-bank.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/integration-bank.rst b/integration-bank.rst index 4ebf2f11..348f70ae 100644 --- a/integration-bank.rst +++ b/integration-bank.rst @@ -62,6 +62,10 @@ The event data must be a `CreateReserveDetail`_: // reserve_pub // mint callback_url: string; + + // list of wire transfer types supported by the bank + // e.g. "SEPA", "test" + wt_types: Array } .. _ReserveCreated: -- cgit v1.2.3 From 4479b49bda602a73f6e1c24fdfb68dfbbf15b069 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Mon, 15 Feb 2016 19:15:11 +0100 Subject: /hash-contract in backend --- impl-merchant.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/impl-merchant.rst b/impl-merchant.rst index 0b5d1975..505376d0 100644 --- a/impl-merchant.rst +++ b/impl-merchant.rst @@ -50,6 +50,22 @@ The Merchant Backend HTTP API The following API are made available by the merchant's `backend` to the merchant's `frontend`. +.. http:post:: /hash-contract + + Ask the backend to compute the hash of the `contract` given in the POST's body. This feature + allows frontends to verify that names of resources which are going to be sold are actually `in` + the paid cotnract. Without this feature, a malicious wallet can request resource A and pay for + resource B without the frontend being aware of that. + + **Response** + + :status 200 OK: + hash succesfully computed. The returned value is a JSON having one field called `hash` containing + the hashed contract + :status 400 Bad Request: + Request not understood. The JSON was invalid. Possibly due to some error in + formatting the JSON by the `frontend`. + .. http:post:: /contract Ask the backend to add some missing (mostly related to cryptography) information to the contract. -- cgit v1.2.3 From b909ded00c717c575b8110a689e7b7d2e1d582ac Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Tue, 16 Feb 2016 20:16:54 +0100 Subject: minor --- impl-merchant.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/impl-merchant.rst b/impl-merchant.rst index 505376d0..28bfc76b 100644 --- a/impl-merchant.rst +++ b/impl-merchant.rst @@ -52,10 +52,11 @@ The following API are made available by the merchant's `backend` to the merchant .. http:post:: /hash-contract - Ask the backend to compute the hash of the `contract` given in the POST's body. This feature - allows frontends to verify that names of resources which are going to be sold are actually `in` - the paid cotnract. Without this feature, a malicious wallet can request resource A and pay for - resource B without the frontend being aware of that. + Ask the backend to compute the hash of the `contract` given in the POST's body (the full contract + should be the value of a JSON field named `contract`). This feature allows frontends to verify + that names of resources which are going to be sold are actually `in` the paid cotnract. Without + this feature, a malicious wallet can request resource A and pay for resource B without the frontend + being aware of that. **Response** -- cgit v1.2.3 From 632e8a36eec408935e965c528196e28bff1f394a Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 17 Feb 2016 04:28:38 +0100 Subject: rough essay store description --- example-essay-store.rst | 40 ++++++++++++++++++++++++++++++++++++++++ index.rst | 1 + 2 files changed, 41 insertions(+) create mode 100644 example-essay-store.rst diff --git a/example-essay-store.rst b/example-essay-store.rst new file mode 100644 index 00000000..4b1eeeae --- /dev/null +++ b/example-essay-store.rst @@ -0,0 +1,40 @@ +================================== +Example: Essay Store +================================== + +The main page of the essay store shows links to essays of the form `/essay?name=:essayname`. + +The `/essay` URL takes the following query parameters: + * `name`: mandatory, name of the essay + * `tid`: optional, transaction ID generated by the merchant for the + contract that was used to purchase an instance of the article + +These are the steps for showing `/essay`. Note that checks for wallet presence are omitted, +it the wallet is not present in steps 2 and 3, the user agent should be redirected +to a mock credit card payment page. + +1. The server checks the status of the the essay with the name `name` in the server-side + session state + + * If the essay is marked as payed for the client, display the essay. + * Otherwise proceed with step 2 + +2. The server checks if the `tid` parameter is present + + * If `tid` is present, restore the contract to pay for the essay and + emit the `taler-execute-contract` DOM event in the user agent. + * Otherwise proceed with step 3 + +3. The server generates a new contract and emits the `taler-confirm-contract` DOM event in the user agent, + with the essay name as repurchase correlation identifier and `/essay?name=:name?tid=:tid` as fulfillment url. + + +In step 2, the `taler-execute-contract` event has the following parameters: + +* `H_contract`: hash of the contract that was restored +* `payment_url`: The internal URL `/pay?H_contract=...` of the essay store, will set the server-side session state + for the article associated with the contract hash on successful coin deposit +* `offer_url`: Link to a teaser page (`/teaser?name=...`), which also contains a link to the article + page, without the `tid` parameter. + + diff --git a/index.rst b/index.rst index deca474c..f8b938e1 100644 --- a/index.rst +++ b/index.rst @@ -50,6 +50,7 @@ the material covered in the *Operator Handbook*. integration-general integration-bank integration-merchant + example-essay-store -------------------------------------- -- cgit v1.2.3 From 793c30b6e2457877c47f4bacbcfdf0c061fba6d4 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 17 Feb 2016 04:55:02 +0100 Subject: improve essay steps --- example-essay-store.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/example-essay-store.rst b/example-essay-store.rst index 4b1eeeae..3629bc21 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -2,16 +2,18 @@ Example: Essay Store ================================== -The main page of the essay store shows links to essays of the form `/essay?name=:essayname`. +The main page of the essay store shows links to essays of the form `/essay?name=:name`. The `/essay` URL takes the following query parameters: * `name`: mandatory, name of the essay * `tid`: optional, transaction ID generated by the merchant for the contract that was used to purchase an instance of the article + * `timestamp`, optional, timestamp for the contract that was used to purchase + the essay with the given `tid`. -These are the steps for showing `/essay`. Note that checks for wallet presence are omitted, -it the wallet is not present in steps 2 and 3, the user agent should be redirected -to a mock credit card payment page. +These are the steps for showing `/essay`. If the wallet is not present in +steps 2 and 3, the user agent is be redirected to a mock credit card +payment page. 1. The server checks the status of the the essay with the name `name` in the server-side session state @@ -19,10 +21,11 @@ to a mock credit card payment page. * If the essay is marked as payed for the client, display the essay. * Otherwise proceed with step 2 -2. The server checks if the `tid` parameter is present +2. The server checks if the `tid` query parameter is present - * If `tid` is present, restore the contract to pay for the essay and - emit the `taler-execute-contract` DOM event in the user agent. + * If `tid` and `timestamp` are present, restore the contract for the essay (using `tid` as + transaction id in the contract and `timestamp` as timestamp) and emit the `taler-execute-contract` DOM + event in the user agent. * Otherwise proceed with step 3 3. The server generates a new contract and emits the `taler-confirm-contract` DOM event in the user agent, -- cgit v1.2.3 From 49274bc65acdb9feb4e611ff6bc7464a5f6fcbe8 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 17 Feb 2016 04:56:09 +0100 Subject: grammar --- example-essay-store.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/example-essay-store.rst b/example-essay-store.rst index 3629bc21..5526faef 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -12,7 +12,7 @@ The `/essay` URL takes the following query parameters: the essay with the given `tid`. These are the steps for showing `/essay`. If the wallet is not present in -steps 2 and 3, the user agent is be redirected to a mock credit card +steps 2 and 3, the user agent is redirected to a mock credit card payment page. 1. The server checks the status of the the essay with the name `name` in the server-side -- cgit v1.2.3 From 3ec1729010fa03051f303d957297d7d7e0b03eba Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 17 Feb 2016 04:58:20 +0100 Subject: remark --- example-essay-store.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/example-essay-store.rst b/example-essay-store.rst index 5526faef..585ca22a 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -36,7 +36,8 @@ In step 2, the `taler-execute-contract` event has the following parameters: * `H_contract`: hash of the contract that was restored * `payment_url`: The internal URL `/pay?H_contract=...` of the essay store, will set the server-side session state - for the article associated with the contract hash on successful coin deposit + for the article associated with the contract hash on successful coin deposit. When the contract is + fetched, the contract hash is associated with the article name in the server-side session state. * `offer_url`: Link to a teaser page (`/teaser?name=...`), which also contains a link to the article page, without the `tid` parameter. -- cgit v1.2.3 From 524387973f4aae3ee4cf5813131b504b039622a9 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 17 Feb 2016 05:01:41 +0100 Subject: grammar/precision --- example-essay-store.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/example-essay-store.rst b/example-essay-store.rst index 585ca22a..1da9eb62 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -18,10 +18,10 @@ payment page. 1. The server checks the status of the the essay with the name `name` in the server-side session state - * If the essay is marked as payed for the client, display the essay. + * If the essay is marked as payed, display the essay. * Otherwise proceed with step 2 -2. The server checks if the `tid` query parameter is present +2. The server checks if the `tid` and `timestamp` query parameters are present * If `tid` and `timestamp` are present, restore the contract for the essay (using `tid` as transaction id in the contract and `timestamp` as timestamp) and emit the `taler-execute-contract` DOM @@ -35,9 +35,10 @@ payment page. In step 2, the `taler-execute-contract` event has the following parameters: * `H_contract`: hash of the contract that was restored -* `payment_url`: The internal URL `/pay?H_contract=...` of the essay store, will set the server-side session state - for the article associated with the contract hash on successful coin deposit. When the contract is - fetched, the contract hash is associated with the article name in the server-side session state. +* `payment_url`: The internal URL `/pay?H_contract=...` of the essay store, + will set the server-side session state for the article associated with the + contract hash on successful coin deposit. The contract hash is associated + with the article name in the server-side session state when the contract is restored. * `offer_url`: Link to a teaser page (`/teaser?name=...`), which also contains a link to the article page, without the `tid` parameter. -- cgit v1.2.3 From c85c9893e9c958e22dbb5d80f8d85bc686fc0f29 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 17 Feb 2016 05:09:46 +0100 Subject: note --- example-essay-store.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/example-essay-store.rst b/example-essay-store.rst index 1da9eb62..74a25990 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -23,9 +23,10 @@ payment page. 2. The server checks if the `tid` and `timestamp` query parameters are present - * If `tid` and `timestamp` are present, restore the contract for the essay (using `tid` as - transaction id in the contract and `timestamp` as timestamp) and emit the `taler-execute-contract` DOM - event in the user agent. + * If `tid` and `timestamp` are present, restore the contract for the essay + (using `tid` as transaction id in the contract, `timestamp` as timestamp + and `timestamp+REFUND_DELTA` as refund deadline) and emit the + `taler-execute-contract` DOM event in the user agent. * Otherwise proceed with step 3 3. The server generates a new contract and emits the `taler-confirm-contract` DOM event in the user agent, @@ -43,3 +44,6 @@ In step 2, the `taler-execute-contract` event has the following parameters: page, without the `tid` parameter. +Note that we assume that all essays cost the same (otherwise the amount would have to be included in +the restoration information in the /essay fulfillment URL). The refund deadline is computed +by adding the merchant-specific constant `REFUND_DELTA` to the contract's timestamp. -- cgit v1.2.3 From 9daf17404255125dbcdf0f37a045cbd671bdbba3 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 17 Feb 2016 17:40:34 +0100 Subject: document fulfillment URL, remove old mechanism --- api-merchant.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/api-merchant.rst b/api-merchant.rst index 46c9cee1..2dd9695f 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -48,15 +48,6 @@ that is legally non-binding: // Signature over the contract made by the merchant. // Must confirm to the `Signature specification`_ below. sig: EddsaSignature; - - // URL where the customer's wallet - // must send the payment for the contract. - // May be relative to the URL of the page that - // delivered the contract. - pay_url: string; - - // URL to the `execution page`_. - exec_url: string; } The contract must have the following structure: @@ -76,6 +67,15 @@ The contract must have the following structure: // product instance. repurchase_correlation_id?: string; + // URL that the wallet will navigate to after the customer + // confirmed purchasing the contract. Responsible for + // doing the actual payment and making available the product (if digital) + // or displaying a confirmation. + // The placeholder ${H_contract} will be replaced + // with the contract hash by wallets before navigating + // to the fulfillment URL. + fulfillment_url: string; + // Maximum total deposit fee accepted by the merchant for this contract max_fee: Amount; -- cgit v1.2.3 From 682b6d7eb0bfbb753245161172bd9f5a732b32f5 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 18 Feb 2016 15:50:15 +0100 Subject: remove duplicate value in struct --- api-mint.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/api-mint.rst b/api-mint.rst index c9f6e2ff..2b438dfa 100644 --- a/api-mint.rst +++ b/api-mint.rst @@ -80,10 +80,6 @@ possibly by using HTTPS. // When does the denomination key become valid? stamp_start: Timestamp; - // When is it no longer possible to withdraw fresh coins - // of this denomination? - stamp_expire_withdraw: Timestamp; - // When is it no longer possible to deposit coins // of this denomination? stamp_expire_withdraw: Timestamp; -- cgit v1.2.3