diff options
author | MS <ms@taler.net> | 2022-12-06 17:21:11 +0100 |
---|---|---|
committer | MS <ms@taler.net> | 2022-12-06 17:21:35 +0100 |
commit | 5cc3fce8075c4666f271611a3988392a14731d92 (patch) | |
tree | a4a131c71ba787a998e568fef7595da6d19c76de /libeufin | |
parent | 3036b21e51fb494886acf903e135d2115340bd35 (diff) | |
download | docs-5cc3fce8075c4666f271611a3988392a14731d92.tar.gz docs-5cc3fce8075c4666f271611a3988392a14731d92.tar.bz2 docs-5cc3fce8075c4666f271611a3988392a14731d92.zip |
Customer API draft.
Diffstat (limited to 'libeufin')
-rw-r--r-- | libeufin/api-sandbox.rst | 183 |
1 files changed, 182 insertions, 1 deletions
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst index 1f58a7db..0633165a 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -15,11 +15,192 @@ only one demobank, named ``default``, is supported. Such demobank activates the API segment ``/demobanks/default``, under which several APIs are then served. The following sections describe all such APIs. +Customer API. +^^^^^^^^^^^^^ + +This API allows CRUD operations on the bank's customers (also referred +as 'users'). All the calls are allowed for the administrator, whereas +**only** the `password change <customer-password-modification>`_ is allowed +for ordinary customers. + +The following endpoints are served under ``/demobanks/default/customer-api``. + +.. http:post:: /customers + + Create a new customer, including their bank account. + + **Request:** + + .. ts:def:: CustomerRequest + + interface CustomerRequest { + // Username + username: string; + + // Password. + password: string; + + // E-Mail address + email: string; + + // Phone number. + phone: string; + + // Name denoting the legal subject being the customer. + name: string; + + // 'payto' address pointing the bank account + // where to send payments, in case the customer + // wants to convert the local currency back to + // fiat. + payoutAddress: string; + + // IBAN to assign to this bank account. Randomly + // generated, when it is not given. + iban?: string; + } + + **Response:** + + :http:statuscode:`204 No content`: + The customer was successfully created. + :http:statuscode:`409 Conflict`: + One information was not available, the error message should inform + about it. + :http:statuscode:`403 Forbidden`: + A istitutional username was attempted, like ``admin`` or ``bank``. + +.. http:delete:: /customers + + Delete a customer *with a zero balance* from the bank. + + **Request:** + + :query username: the username of the customer account to delete. + + **Response:** + + :http:statuscode:`204 No content`: + The customer account was successfully deleted. + :http:statuscode:`404 Not found`: + The customer specified along the parameters was not found. + :http:statuscode:`403 Forbidden`: + The administrator specified a istitutional username, like + ``admin`` or ``bank``. + :http:statuscode:`412 Precondition failed`: + The balance of the customer to delete was not zero. + +.. _customer-password-modification: + +.. http:patch:: /customers + + Allows administrators *and* ordinary customers to + change customer password. + + **Request:** + + .. ts:def:: CustomerPasswordChange + + interface Customer { + // Username of the customer whose password is + // to be changed. It is optional in case the + // customer issues the request, because such information + // can be retrieved from the authentication credentials. + username?: string; + + // New password. + newPassword: string; + } + + **Response:** + + :http:statuscode:`204 No content`: + Operation successful. + :http:statuscode:`403 Forbidden`: + A ordinary customer tried to change someone else's password. + This error should happen *before* checking whether the target + username exists, not to leak which usernames are already registered. + :http:statuscode:`404 Not found`: + The username whose password should be changed was not found. + +.. http:get:: /customers + + Allows the administrator to obtain a list of all the + customers registered at the bank. It returns only the + customer data (without any business information), because + :doc:`Access API </core/api-bank-access>` may already + be used for that. + + **Response:** + + .. ts:def:: Customers + + interfaces Customers { + customers: CustomerData[]; + } + + .. ts:def:: CustomerData + + interface CustomerData { + // Username + username: string; + + // IBAN hosted at Libeufin Sandbox + iban: string; + + // E-Mail address + email: string; + + // Phone number. + phone: string; + + // Name denoting the legal subject being the customer. + name: string; + + // 'payto' address pointing the bank account + // where to send payments, in case the customer + // wants to convert the local currency back to + // fiat. + cashoutAddress: string; + } + + +.. http:post:: /cashout + + Lets the user specify an amount to be converted back + to fiat currency. The target account is the one specified + at registration time. The account to be debited is extracted + from the authentication credentials. The bank sends a TAN + to the customer, to let them confirm the operation. + + .. + FIXME: TAN first per e-mail, or phone? + + **Request:** + + .. ts:def:: CashoutRequest + + interface CashoutRequest { + // Amount in the $currency:$value format. + amount: string; + } + + **Response:** + + :http:statuscode:`202 Accepted`: + The cashout request was correctly created and + the TAN authentication now is pending. + :http:statuscode:`412 Precondition failed`: + Customer does not have sufficient funds. + :http:statuscode:`409 Conflict`: + A istitutional user (``admin`` or ``bank``) tried the operation. + Access API. ^^^^^^^^^^^ Every endpoint is served under ``/demobanks/default/access-api``. -See :doc:`/core/api-bank-access`. This API offers *users management*. +See :doc:`/core/api-bank-access`. This API allows users to access +their bank accounts and trigger Taler withdrawals. Integration API. ^^^^^^^^^^^^^^^^ |