taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-accounts-USERNAME-cashouts.rst (3076B)

      1 .. http:post:: /accounts/$USERNAME/cashouts
      2 
      3   Initiates a conversion to fiat currency.  The fiat
      4   bank account to be
      5   credited is the one specified at registration time via the
      6   *cashout_payto_uri* parameter.  The regional bank account
      7   is specified via ``$USERNAME``.
      8 
      9   .. note::
     10 
     11     Consult the `cashout rates call <cashout-rates>`_ to learn
     12     about any applicable fee or exchange rate.
     13 
     14 
     15   **Request:**
     16 
     17   .. ts:def:: CashoutRequest
     18 
     19     interface CashoutRequest {
     20       // Nonce to make the request idempotent.  Requests with the same
     21       // ``request_uid`` that differ in any of the other fields
     22       // are rejected.
     23       request_uid: ShortHashCode;
     24 
     25       // Optional subject to associate to the
     26       // cashout operation.  This data will appear
     27       // as the incoming wire transfer subject in
     28       // the user's fiat bank account.
     29       subject?: string;
     30 
     31       // That is the plain amount that the user specified
     32       // to cashout.  Its $currency is the (regional) currency of the
     33       // bank instance.
     34       amount_debit: Amount;
     35 
     36       // That is the amount that will effectively be
     37       // transferred by the bank to the user's fiat bank
     38       // account.
     39       // It is expressed in the fiat currency and
     40       // is calculated after the cashout fee and the
     41       // exchange rate.  See the /cashout-rate call.
     42       // The client needs to calculate this amount
     43       // correctly based on the amount_debit and the cashout rate,
     44       // otherwise the request will fail.
     45       amount_credit: Amount;
     46     }
     47 
     48   **Response:**
     49 
     50   :http:statuscode:`200 OK`:
     51     The cashout request was correctly created.
     52     This returns the `CashoutResponse` response.
     53   :http:statuscode:`202 Accepted`:
     54     2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10**
     55   :http:statuscode:`401 Unauthorized`:
     56     Invalid or missing credentials.
     57   :http:statuscode:`403 Forbidden`:
     58     Missing rights.
     59   :http:statuscode:`404 Not found`:
     60     The account pointed by ``$USERNAME`` was not found.
     61   :http:statuscode:`409 Conflict`:
     62     * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before.
     63     * ``TALER_EC_BANK_BAD_CONVERSION``: exchange rate was calculated incorrectly by the client.
     64     * ``TALER_EC_BANK_BANK_CONVERSION_AMOUNT_TO_SMALL``: the amount of the cashout is too small.
     65     * ``TALER_EC_BANK_UNALLOWED_DEBIT``: the account does not have sufficient funds or the amount is too low or too high.
     66     * ``TALER_EC_BANK_CONFIRM_INCOMPLETE``: the user did not share any cashout payto to uri where to wire funds.
     67   :http:statuscode:`501 Not Implemented`:
     68     * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED``: the chosen ``tan_channel`` or one of ``tan_channels`` is not currently supported.
     69     * This server does not support conversion, client should check config response.
     70 
     71   **Details:**
     72 
     73   .. ts:def:: CashoutResponse
     74 
     75     interface CashoutResponse {
     76       // ID identifying the operation being created
     77       cashout_id: Integer;
     78     }