diff options
Diffstat (limited to 'core/api-corebank.rst')
| -rw-r--r-- | core/api-corebank.rst | 228 |
1 files changed, 187 insertions, 41 deletions
diff --git a/core/api-corebank.rst b/core/api-corebank.rst index 680b2724..e3029100 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -49,8 +49,110 @@ client to authenticate as the admin. .. http:post:: /accounts/$USERNAME/token - See :ref:`DD 48 token endpoint <dd48-token>`. + Create or refresh an authentification token. + **Request:** + + .. ts:def:: TokenRequest + + interface TokenRequest { + // Scope for the token. + scope: "readonly" | "readwrite" | "revenue"; + + // Custom token validity duration + duration?: RelativeTime; + + // Is the token refreshable into a new token during its + // validity? + // Refreshable tokens effectively provide indefinite + // access if they are refreshed in time. + refreshable?: boolean; + + // Token description + // @since v4 + description?: string; + } + + **Response:** + + :http:statuscode:`200 Ok`: + The response is a `TokenSuccessResponse` + + **Details:** + + .. ts:def:: TokenSuccessResponse + + interface TokenSuccessResponse { + // Expiration determined by the server. + // Can be based on the token_duration + // from the request, but ultimately the + // server decides the expiration. + expiration: Timestamp; + + // Opque access token. + access_token: string; + } + +.. http:delete:: /accounts/$USERNAME/token + + Invalidate the access token that is being used to make the request. + + **Authentication:** The client must authenticate with a valid access token. + +.. http:get:: /accounts/$USERNAME/tokens + + Retrieve a subset of tokens related to $USERNAME. + @since v4 + + **Request:** + + :query delta: *Optional.* + Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries. + :query start: *Optional.* + Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign. + + **Response:** + + :http:statuscode:`200 OK`: + Response is a `TokenInfos`. + :http:statuscode:`204 No content`: + No tokens. + + **Details:** + + .. ts:def:: TokenInfos + + interface TokenInfos { + tokens: TokenInfo[]; + } + + .. ts:def:: TokenInfo + + interface TokenInfo { + // Time when the token was created. + creation_time: Timestamp; + + // Expiration determined by the server. + // Can be based on the token_duration + // from the request, but ultimately the + // server decides the expiration. + expiration: Timestamp; + + // Scope for the token. + scope: "readonly" | "readwrite" | "revenue"; + + // Is the token refreshable into a new token during its + // validity? + // Refreshable tokens effectively provide indefinite + // access if they are refreshed in time. + refreshable: boolean; + + // Token description + description?: string; + + // Time when the token was last used. + last_access: Timestamp; + } Bank Web UI ----------- @@ -88,7 +190,7 @@ Config // @since v4, will become mandatory in the next version. bank_name?: string; - // Advertised base URL to use when you sharing an URL with another + // Advertised base URL to use when you sharing an URL with another // program. // @since v4. base_url?: string; @@ -129,6 +231,10 @@ Config // Default to 'iban' is missing // @since v4, will become mandatory in the next version. wire_type?: string; + + // Wire transfer execution fees. + // @since v4, will become mandatory in the next version. + wire_transfer_fees?: Amount; } @@ -188,6 +294,11 @@ Account Management // Only admin can set this property. debit_threshold?: Amount; + // If present, set a custom minimum cashout amount for this account. + // Only admin can set this property + // @since v4 + min_cashout?: Amount; + // If present, enables 2FA and set the TAN channel used for challenges // Only admin can set this property, other user can reconfig their account // after creation. @@ -220,6 +331,7 @@ Account Management * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : admin account does not have sufficient funds to grant bonus. * ``TALER_EC_BANK_RESERVED_USERNAME_CONFLICT`` : a reserved username was attempted, like ``admin`` or ``bank`` * ``TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT`` : a non-admin user has tried to create an account with a customer debt limit. + * ``TALER_EC_BANK_NON_ADMIN_SET_MIN_CASHOUT`` : a non-admin user has tried to create an account with a custom min cashout amount. * ``TALER_EC_BANK_NON_ADMIN_SET_TAN_CHANNEL`` : a non-admin user has tried to create an account with 2fa. * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED``: ``tan_channel`` is not supported, check bank config to find supported ones. * ``TALER_EC_BANK_MISSING_TAN_INFO``: the user did not share any contact data where to send the TAN via ``tan_channel``. @@ -233,28 +345,6 @@ Account Management internal_payto_uri: string; } -.. _delete-account: - -.. http:delete:: /accounts/$USERNAME - - Delete the account whose username is ``$USERNAME``. The deletion - succeeds only if the balance is *zero*. Typically only available to - the administrator, but can be configured to allow ordinary users too. - - **Response:** - - :http:statuscode:`202 Accepted`: - 2FA is required for this operation. This returns the `Challenge` response. - :http:statuscode:`204 No content`: - The account was successfully deleted. - :http:statuscode:`401 Unauthorized`: - Invalid credentials or missing rights. - :http:statuscode:`404 Not found`: - The account pointed by ``$USERNAME`` was not found. - :http:statuscode:`409 Conflict`: - * ``TALER_EC_BANK_RESERVED_USERNAME_CONFLICT`` : a reserved username was attempted, like ``admin`` or ``bank``. - * ``TALER_EC_BANK_ACCOUNT_BALANCE_NOT_ZERO``: the account balance was not zero. - .. _account-reconfig: .. http:patch:: /accounts/$USERNAME @@ -288,6 +378,11 @@ Account Management // Only admin can change this property. debit_threshold?: Amount; + // If present, change the custom minimum cashout amount for this account. + // Only admin can set this property + // @since v4 + min_cashout?: Amount; + // If present, enables 2FA and set the TAN channel used for challenges tan_channel?: TanChannel; } @@ -306,6 +401,7 @@ Account Management * ``TALER_EC_BANK_NON_ADMIN_PATCH_LEGAL_NAME`` : a non-admin user has tried to change their legal name. * ``TALER_EC_BANK_NON_ADMIN_PATCH_CASHOUT`` : a non-admin user has tried to change their cashout account. * ``TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT`` : a non-admin user has tried to change their debt limit. + * ``TALER_EC_BANK_NON_ADMIN_SET_MIN_CASHOUT`` : a non-admin user has tried to change their custom min cashout amount. * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED`` : ``tan_channel`` is not supported, check bank config to find supported ones. * ``TALER_EC_BANK_MISSING_TAN_INFO`` : the user did not share any contact data where to send the TAN via ``tan_channel``. @@ -343,6 +439,29 @@ Account Management * ``TALER_EC_BANK_NON_ADMIN_PATCH_MISSING_OLD_PASSWORD``: a non-admin user has tried to change their password whihout providing the current one. * ``TALER_EC_BANK_PATCH_BAD_OLD_PASSWORD`` : provided old password does not match current password. + +.. _delete-account: + +.. http:delete:: /accounts/$USERNAME + + Delete the account whose username is ``$USERNAME``. The deletion + succeeds only if the balance is *zero*. Typically only available to + the administrator, but can be configured to allow ordinary users too. + + **Response:** + + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. + :http:statuscode:`204 No content`: + The account was successfully deleted. + :http:statuscode:`401 Unauthorized`: + Invalid credentials or missing rights. + :http:statuscode:`404 Not found`: + The account pointed by ``$USERNAME`` was not found. + :http:statuscode:`409 Conflict`: + * ``TALER_EC_BANK_RESERVED_USERNAME_CONFLICT`` : a reserved username was attempted, like ``admin`` or ``bank``. + * ``TALER_EC_BANK_ACCOUNT_BALANCE_NOT_ZERO``: the account balance was not zero. + .. _account-list: .. http:get:: /public-accounts @@ -350,7 +469,6 @@ Account Management Show those accounts whose histories are publicly visible. For example, accounts from donation receivers. As such, this request is unauthenticated. - **Request:** :query delta: *Optional.* @@ -431,7 +549,7 @@ Account Management .. ts:def:: ListBankAccountsResponse - interfaces ListBankAccountsResponse { + interface ListBankAccountsResponse { accounts: AccountMinimalData[]; } @@ -460,6 +578,11 @@ Account Management // Number indicating the max debit allowed for the requesting user. debit_threshold: Amount; + // Custom minimum cashout amount for this account. + // If null or absent, the global conversion fee is used. + // @since v4 + min_cashout?: Amount; + // Is this account visible to anyone? is_public: boolean; @@ -472,7 +595,7 @@ Account Management // Current status of the account // active: the account can be used - // deleted: the account has been deleted but is retained for compliance + // deleted: the account has been deleted but is retained for compliance // reasons, only the administrator can access it // Default to 'active' is missing // @since v4, will become mandatory in the next version. @@ -513,6 +636,11 @@ Account Management // Number indicating the max debit allowed for the requesting user. debit_threshold: Amount; + // Custom minimum cashout amount for this account. + // If null or absent, the global conversion fee is used. + // @since v4 + min_cashout?: Amount; + // Addresses where to send the TAN for transactions. // Currently only used for cashouts. // If missing, cashouts will fail. @@ -539,7 +667,7 @@ Account Management // Current status of the account // active: the account can be used - // deleted: the account has been deleted but is retained for compliance + // deleted: the account has been deleted but is retained for compliance // reasons, only the administrator can access it // Default to 'active' is missing // @since v4, will become mandatory in the next version. @@ -682,8 +810,8 @@ Transactions row_id: Integer; } -Taler Withdrawals ------------------ +Account withdrawals +------------------- .. http:post:: /accounts/$USERNAME/withdrawals @@ -691,12 +819,7 @@ Taler Withdrawals **Request:** - .. ts:def:: BankAccountCreateWithdrawalRequest - - interface BankAccountCreateWithdrawalRequest { - // Amount to withdraw. - amount: Amount; - } + The request must be a `BankAccountCreateWithdrawalRequest`. **Response:** @@ -709,6 +832,20 @@ Taler Withdrawals **Details:** + .. ts:def:: BankAccountCreateWithdrawalRequest + + interface BankAccountCreateWithdrawalRequest { + // Amount to withdraw. If given, the wallet + // cannot change the amount. + // Optional since **vC2EC**. + amount?: Amount; + + // Suggested amount to withdraw. The wallet can + // still change the suggestion. + // @since **vC2EC** + suggested_amount?: Amount; + } + .. ts:def:: BankAccountCreateWithdrawalResponse interface BankAccountCreateWithdrawalResponse { @@ -788,8 +925,16 @@ Taler Withdrawals status: "pending" | "selected" | "aborted" | "confirmed"; // Amount that will be withdrawn with this operation - // (raw amount without fee considerations). - amount: Amount; + // (raw amount without fee considerations). Only + // given once the amount is fixed and cannot be changed. + // Optional since **vC2EC**. + amount?: Amount; + + // Suggestion for the amount to be withdrawn with this + // operation. Given if a suggestion was made but the + // user may still change the amount. + // Optional since **vC2EC**. + suggested_amount?: Amount; // Account username username: string; @@ -866,9 +1011,10 @@ Cashouts The account pointed by ``$USERNAME`` was not found. :http:statuscode:`409 Conflict`: * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before. - * ``TALER_EC_BANK_BAD_CONVERSION`` : exchange rate was calculated incorrectly by the client. - * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds. - * ``TALER_EC_BANK_CONFIRM_INCOMPLETE`` : the user did not share any cashout payto to uri where to wire funds. + * ``TALER_EC_BANK_BAD_CONVERSION``: exchange rate was calculated incorrectly by the client. + * ``TALER_EC_BANK_BANK_CONVERSION_AMOUNT_TO_SMALL``: the amount of the cashout is too small. + * ``TALER_EC_BANK_UNALLOWED_DEBIT``: the account does not have sufficient funds. + * ``TALER_EC_BANK_CONFIRM_INCOMPLETE``: the user did not share any cashout payto to uri where to wire funds. :http:statuscode:`501 Not Implemented`: * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED``: the chosen ``tan_channel`` is not currently supported. * This server does not support conversion, client should check config response. |