From 6066a955caab2a21db17d400a450ad8d4459dca6 Mon Sep 17 00:00:00 2001 From: MS Date: Mon, 12 Dec 2022 17:45:16 +0100 Subject: circuit API: first pass after review --- libeufin/api-sandbox.rst | 132 +++++++++++++++++++++++++++-------------------- 1 file changed, 75 insertions(+), 57 deletions(-) (limited to 'libeufin') diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst index f4fbb3a2..1bbbec35 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -52,43 +52,54 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. // Password. password: string; - // E-Mail address - email: string; - - // Phone number. - phone: string; + // Addresses where to send the TAN. If + // this field is missing, then the cashout + // won't succeed. + contact_data?: CircuitContactData; // Legal subject owning the account. name: string; // 'payto' address pointing the bank account // where to send payments, in case the user - // wants to convert the local currency back to - // fiat. - cashoutAddress: string; + // wants to convert the local currency back + // to fiat. + cashout_address: string; + + // IBAN of this bank account, which is therefore + // internal to the circuit. Randomly generated, + // when it is not given. + internal_iban?: string; + } + + .. ts:def:: CircuitContactData - // IBAN of this bank account. Randomly - // generated, when it is not given. - iban?: string; + interface CircuitContactData { + + // E-Mail address + email?: string; + + // Phone number. + phone?: string; } + **Response:** :http:statuscode:`204 No content`: The account was successfully created. - :http:statuscode:`409 Conflict`: - At least one registration detail was not available, - the error message should inform about it. + :http:statuscode:`400 Bad request`: + Input data was invalid. For example, the client specified a invalid + phone number or e-mail address. :http:statuscode:`403 Forbidden`: The response should indicate one of the following reasons. - * A istitutional username was attempted, like ``admin`` or ``bank``. + * A institutional username was attempted, like ``admin`` or ``bank``. * A non admin user tried the operation. - :http:statuscode:`404 Bad request`: - Input data was invalid. For example, the client specified a invalid - phone number or e-mail address. - + :http:statuscode:`409 Conflict`: + At least one registration detail was not available, + the error message should inform about it. .. http:delete:: /accounts/$username @@ -100,17 +111,17 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. :http:statuscode:`204 No content`: The account was successfully deleted. - :http:statuscode:`404 Not found`: - The username was not found. :http:statuscode:`403 Forbidden`: - The administrator specified a istitutional username, like + The administrator specified a institutional username, like ``admin`` or ``bank``. + :http:statuscode:`404 Not found`: + The username was not found. :http:statuscode:`412 Precondition failed`: The balance was not zero. .. _customer-password-modification: -.. http:patch:: /accounts/$username +.. http:patch:: /accounts/$username/auth Allows administrators *and* ordinary users to change the account's password. @@ -122,7 +133,7 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. interface AccountPasswordChange { // New password. - newPassword: string; + new_password: string; } **Response:** @@ -171,7 +182,7 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. // 'payto' address pointing the bank account // where to send cashouts. - cashoutAddress: string; + cashout_address: string; } @@ -219,14 +230,31 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. interface CashoutRequest { - // Amount in the $currency:$value format. - amount: string; + // Optional subject to associate to the + // cashout operation. This data will appear + // as the incoming wire transfer subject in + // the user's external bank account. + subject?: string; + + // That is the amount that the user specified + // to cashout. It is therefore NOT affected by + // the exchange rate. + amount_before_conversion: string; + + // That is the amount that will effectively be + // transferred by the bank to the user's bank + // account external to the circuit. It therefore + // must be affected by the exchange rate. The + // reason to have it here is to force the UI to + // calculate this value and show it to the user + // before creating the cashout operation. + amount_after_conversion: string; // Which channel the TAN should be sent to. If // this field is missing, it defaults to SMS. // The default choice prefers to change the communication // channel respect to the one used to issue this request. - tanChannel?: TanChannel; + tan_channel?: TanChannel; } **Response:** @@ -242,10 +270,16 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. :http:statuscode:`202 Accepted`: The cashout request was correctly created and the TAN authentication now is pending. + :http:statuscode:`400 Bad request`: + The exchange rate was incorrectly applied. + :http:statuscode:`403 Forbidden`: + A institutional user (``admin`` or ``bank``) tried the operation. + :http:statuscode:`409 Forbidden`: + The user did not share any contact data where to send the TAN. :http:statuscode:`412 Precondition failed`: The account does not have sufficient funds. - :http:statuscode:`409 Conflict`: - A istitutional user (``admin`` or ``bank``) tried the operation. + :http:statuscode:`503 Service unavailable`: + The bank does not support the TAN channel for this operation. .. http:post:: /cashouts/$cashoutId/abort @@ -260,24 +294,6 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. :http:statuscode:`412 Precondition failed`: ``$cashoutId`` was already confirmed or aborted. -.. http:post:: /cashouts/$cashoutId/refresh-tan - - Invalidates the current TAN of ``$cashoutId`` and - send another TAN via the same channel of the previous - one. Only the original author is allowed. - - **Response:** - - :http:statuscode:`204 No content`: - ``$cashoutId`` was found in the *pending* state, - and a new TAN has been sent via the expected channel. - :http:statuscode:`412 Precondition failed`: - ``$cashoutId`` was already confirmed or aborted. - :http:statuscode:`404 Not found`: - ``$cashoutId`` not found. - :http:statuscode:`403 Forbidden`: - A user other than the original author made the request. - .. http:post:: /cashouts/$cashoutId/confirm Confirms the ``$cashoutId`` operation by accepting its @@ -299,15 +315,12 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. :http:statuscode:`204 No content`: ``$cashoutId`` was found in the *pending* state and got successfully confirmed. - :http:statuscode:`412 Precondition failed`: - ``$cashoutId`` was already confirmed or aborted. - .. - 412 on a presumably pending operation is a proof - of a compromised TAN. - :http:statuscode:`401 Unauthorized`: + :http:statuscode:`403 Forbidden`: wrong TAN. :http:statuscode:`409 Conflict`: - A istitutional user (``admin`` or ``bank``) tried the operation. + A institutional user (``admin`` or ``bank``) tried the operation. + :http:statuscode:`412 Precondition failed`: + ``$cashoutId`` was already confirmed or aborted. .. http:get:: /cashouts/$cashoutId @@ -344,6 +357,13 @@ The following endpoints are served under ``/demobanks/default/circuit-api``. ABORTED = "aborted" } + **Response:** + + :http:statuscode:`404 Not found`: + The cashout operation was not found. That is + *also* the case of ``$cashoutId`` being an aborted + operation. + Access API ^^^^^^^^^^ @@ -779,5 +799,3 @@ The JSON type coming along a non 2xx response is the following: */ UtilError = "util-error" } - - -- cgit v1.2.3