diff options
| -rw-r--r-- | core/api-corebank.rst | 256 |
1 files changed, 118 insertions, 138 deletions
diff --git a/core/api-corebank.rst b/core/api-corebank.rst index bbb50540..7ac6e813 100644 --- a/core/api-corebank.rst +++ b/core/api-corebank.rst @@ -62,7 +62,7 @@ Config .. http:get:: /config Return the protocol version and configuration information about the bank. - This specification corresponds to ``current`` protocol being version **3**. + This specification corresponds to ``current`` protocol being version **4**. **Response:** @@ -71,13 +71,6 @@ Config **Details:** - .. ts:def:: TanChannel - - enum TanChannel { - SMS = "sms", - EMAIL = "email" - } - .. ts:def:: Config interface Config { @@ -160,11 +153,7 @@ Account Management // Defaults to false. is_taler_exchange?: boolean; - // Addresses where to send the TAN for transactions. - // Currently only used for cashouts. - // If missing, cashouts will fail. - // In the future, might be used for other transactions - // as well. + // Addresses where to send the TAN for protected operations. contact_data?: ChallengeContactData; // 'payto' URI of a fiat bank account. @@ -178,16 +167,13 @@ Account Management payto_uri?: string; // If present, set the max debit allowed for this user - // Only admin can change this property. - debit_threshold?: Amount - - // Deprecated use ``contact_data`` instead - // will be removed in the next release - challenge_contact_data?: ChallengeContactData; + // Only admin can set this property. + debit_threshold?: Amount; - // Deprecated use ``payto_uri`` instead - // will be removed in the next release - internal_payto_uri?: string; + // 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. + tan_channel?: TanChannel; } .. ts:def:: ChallengeContactData @@ -215,7 +201,10 @@ Account Management * ``TALER_EC_BANK_REGISTER_PAYTO_URI_REUSE`` : payto URI already used. * ``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 change their debt limit. + * ``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_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``. **Details:** @@ -236,6 +225,8 @@ Account Management **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`: @@ -257,12 +248,7 @@ Account Management .. ts:def:: AccountReconfiguration interface AccountReconfiguration { - // Addresses where to send the TAN for transactions. - // Currently only used for cashouts. - // If missing, cashouts will fail. - // In the future, might be used for other transactions - // as well. - // Only admin can change this property. + // Addresses where to send the TAN for protected operations. contact_data?: ChallengeContactData; // 'payto' URI of a fiat bank account. @@ -281,19 +267,16 @@ Account Management // If present, change the max debit allowed for this user // Only admin can change this property. - debit_threshold?: Amount - - // Deprecated use ``contact_data`` instead - // will be removed in the next release - challenge_contact_data?: ChallengeContactData; + debit_threshold?: Amount; - // Deprecated and have no effect - // will be removed in the next release - is_taler_exchange?: boolean; + // If present, enables 2FA and set the TAN channel used for challenges + tan_channel?: TanChannel; } **Response:** + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. :http:statuscode:`204 No content`: Operation successful. :http:statuscode:`401 Unauthorized`: @@ -303,8 +286,9 @@ Account Management :http:statuscode:`409 Conflict`: * ``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_PATCH_CONTACT``: a non-admin user has tried change their contact info. + * ``TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT`` : a non-admin user has tried to change their debt limit. + * ``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``. .. _account-password-reconfig: @@ -328,6 +312,8 @@ Account Management **Response:** + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. :http:statuscode:`204 No content`: Operation successful. :http:statuscode:`404 Not found`: @@ -387,10 +373,6 @@ Account Management // Is this a taler exchange account? is_taler_exchange: boolean; - - // Deprecated use ``username`` instead - // will be removed in the next release - account_name: string; } .. http:get:: /accounts @@ -516,6 +498,9 @@ Account Management // Is this a taler exchange account? is_taler_exchange: boolean; + + // Is 2FA enabled and what channel is used for challenges? + tan_channel?: TanChannel; } Transactions @@ -625,6 +610,8 @@ Transactions :http:statuscode:`200 Ok`: The bank responds with an `CreateTransactionResponse` object. + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. :http:statuscode:`400 Bad Request`: The request was invalid or the payto://-URI used unacceptable features. :http:statuscode:`401 Unauthorized`: @@ -690,6 +677,8 @@ Taler Withdrawals **Response:** + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. :http:statuscode:`204 No content`: The withdrawal operation has been confirmed. :http:statuscode:`404 Not found`: @@ -762,11 +751,6 @@ Cashouts credited is the one specified at registration time via the *cashout_payto_uri* parameter. The regional bank account is specified via ``$USERNAME``. - The bank sends a TAN to the customer to let them confirm the - operation. The request is only available to ordinary users, not - to the administrator. - - The same request can be posted several times to trigger TAN retransmission. .. note:: @@ -805,98 +789,35 @@ Cashouts // correctly based on the amount_debit and the cashout rate, // otherwise the request will fail. amount_credit: Amount; - - // 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. - tan_channel?: TanChannel; } **Response:** :http:statuscode:`200 OK`: - The cashout request was correctly created and - the TAN authentication now is pending. + The cashout request was correctly created. This returns the `CashoutPending` response. + :http:statuscode:`202 Accepted`: + 2FA is required for this operation. This returns the `Challenge` response. :http:statuscode:`404 Not found`: 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_MISSING_TAN_INFO`` : the user did not share any contact data where to send the TAN via ``tan_channel``. * ``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. - :http:statuscode:`502 Bad Gateway`: - * ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition via ``tan_channel`` failed. **Details:** - .. ts:def:: CashoutPending + .. ts:def:: CashoutResponse - interface CashoutPending { + interface CashoutResponse { // ID identifying the operation being created - // and now waiting for the TAN confirmation. cashout_id: Integer; } - -.. _cashout-abort: - -.. http:post:: /accounts/$USERNAME/cashouts/$CASHOUT_ID/abort - - Aborts ``CASHOUT_ID`` operation. Has no effect on an already aborted - operation. - - **Response:** - - :http:statuscode:`204 No content`: - The cashout operation has been aborted. - :http:statuscode:`404 Not found`: - The cashout operation was not found. - :http:statuscode:`409 Conflict`: - The cashout operation has been confirmed previously and can't be aborted. - :http:statuscode:`501 Not implemented`: - This server does not support conversion, client should check config response. - -.. _cashout-confirm: - -.. http:post:: /accounts/$USERNAME/cashouts/$CASHOUT_ID/confirm - - Confirms ``CASHOUT_ID`` operation by providing its - TAN. Has no effect on an already confirmed - cashout operation. This call is responsible for wiring the funds to the - user's fiat bank account. - - **Request:** - - .. ts:def:: CashoutConfirm - - interface CashoutConfirm { - // the TAN that confirms $CASHOUT_ID. - tan: string; - } - - **Response:** - - :http:statuscode:`204 No content`: - The cashout operation has been confirmed. - :http:statuscode:`404 Not found`: - The operation was not found. - :http:statuscode:`409 Conflict`: - * ``TALER_EC_BANK_CONFIRM_ABORT_CONFLICT`` : the cashout has been aborted previously and can't be confirmed. - * ``TALER_EC_BANK_CONFIRM_INCOMPLETE`` : the user did not share any cashout payto to uri where to wire funds. - * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds. - * ``TALER_EC_BANK_BAD_CONVERSION`` : exchange rate has changed since operation creation. - * ``TALER_EC_BANK_TAN_CHALLENGE_FAILED`` : wrong or expired TAN. - :http:statuscode:`429 Too many requests`: - Too many failed confirmation attempts, a new TAN must be requested. - :http:statuscode:`501 Not implemented`: - This server does not support conversion, client should check config response. - - .. _circuit-cashout-details: .. http:get:: /accounts/$USERNAME/cashouts/$CASHOUT_ID @@ -918,8 +839,6 @@ Cashouts .. ts:def:: CashoutStatusResponse interface CashoutStatusResponse { - status: "pending" | "aborted" | "confirmed"; - // Amount debited to the regional bank account. amount_debit: Amount; @@ -931,26 +850,13 @@ Cashouts // Time when the cashout was created. creation_time: Timestamp; - - // Time when the cashout was confirmed via its TAN. - // Missing when the operation wasn't confirmed yet. - confirmation_time?: Timestamp; - - // Channel of the last successful transmission of the TAN challenge. - // Missing when all transmissions failed. - tan_channel?: TanChannel; - - // Info of the last successful transmission of the TAN challenge. - // Missing when all transmissions failed. - tan_info?: string; } .. _circuit-cashouts: .. http:get:: /accounts/$USERNAME/cashouts - Returns the list of all the (pending and confirmed) cash-out operations - for an account. + Returns the list of all cash-out operations for an account. **Request:** @@ -981,15 +887,13 @@ Cashouts interface CashoutInfo { cashout_id: Integer; - status: "pending" | "aborted" | "confirmed"; } .. http:get:: /cashouts - Returns the list of all the (pending and confirmed) cash-out operations - for **all** accounts. + Returns the list of all cash-out operations for **all** accounts. - Typically can only be used by the administrators. + Can only be used by the administrators. **Request:** @@ -1025,11 +929,87 @@ Cashouts interface GlobalCashoutInfo { cashout_id: Integer; username: string; - status: "pending" | "aborted" | "confirmed"; } .. _cashout-rates: +2FA +--- + +.. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID + + Send TAN code for the ``CHALLENGE_ID`` challenge. + + This request can be posted several times to trigger TAN retransmission when the current code has expired or too many confirmation attempts have been made. + + **Response:** + + :http:statuscode:`200 OK`: + The TAN code have been sent. This returns `TanTransmission` response. + :http:statuscode:`401 Unauthorized`: + Invalid credentials or missing rights. + :http:statuscode:`404 Not Found`: + The challenge was not found. + :http:statuscode:`502 Bad Gateway`: + * ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition via ``tan_channel`` failed. + + **Details:** + + .. ts:def:: TanTransmission + + interface TanTransmission { + // Channel of the last successful transmission of the TAN challenge. + tan_channel: TanChannel; + + // Info of the last successful transmission of the TAN challenge. + tan_info: string; + } + + .. ts:def:: Challenge + + interface Challenge { + // Unique identifier of the challenge to solve to run this protected + // operation. + challenge_id: string; + } + + .. ts:def:: TanChannel + + enum TanChannel { + SMS = "sms", + EMAIL = "email" + } + + +.. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID/confirm + + Solves the ``CHALLENGE_ID`` challenge and performs the protected operation. + + When the challenge is confirmed, you can call the protected endpoint again with ``CHALLENGE_ID`` in the ``X-Challenge-Id`` HTTP header and an empty request body. + + **Request:** + + .. ts:def:: ChallengeSolve + + interface ChallengeSolve { + // The TAN code that solves $CHALLENGE_ID + tan: string; + } + + **Response:** + + :http:statuscode:`204 No Content`: + The challenge is confirmed. + :http:statuscode:`401 Unauthorized`: + Invalid credentials or missing rights. + :http:statuscode:`404 Not Found`: + The challenge was not found. + :http:statuscode:`409 Conflict`: + * ``TALER_EC_BANK_TAN_CHALLENGE_FAILED`` : wrong TAN. + * ``TALER_EC_BANK_TAN_CHALLENGE_EXPIRED`` : expired TAN. + :http:statuscode:`429 Too many requests`: + Too many failed confirmation attempts, a new TAN must be requested. + Monitor ------- |