post-accounts-USERNAME-cashouts.rst (3460B)
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 :ref:`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, including 22 // ``amount_credit``, 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 Idempotency compares the account, ``amount_debit``, ``amount_credit`` and 49 ``subject``. Repeating an identical request returns the original result; 50 changing any of those values while reusing ``request_uid`` returns 51 ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``. In particular, a corrected 52 conversion quote must use a new ``request_uid``. 53 54 **Response:** 55 56 :http:statuscode:`200 OK`: 57 The cashout request was correctly created. 58 This returns the `CashoutResponse` response. 59 :http:statuscode:`202 Accepted`: 60 2FA is required for this operation. This returns the `ChallengeResponse` response. @since **v10** 61 :http:statuscode:`401 Unauthorized`: 62 Invalid or missing credentials. 63 :http:statuscode:`403 Forbidden`: 64 Missing rights. 65 :http:statuscode:`404 Not found`: 66 The account pointed by ``$USERNAME`` was not found. 67 :http:statuscode:`409 Conflict`: 68 * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before. 69 * ``TALER_EC_BANK_BAD_CONVERSION``: exchange rate was calculated incorrectly by the client. 70 * ``TALER_EC_BANK_BANK_CONVERSION_AMOUNT_TO_SMALL``: the amount of the cashout is too small. 71 * ``TALER_EC_BANK_UNALLOWED_DEBIT``: the account does not have sufficient funds or the amount is too low or too high. 72 * ``TALER_EC_BANK_CONFIRM_INCOMPLETE``: the user did not share any cashout payto to uri where to wire funds. 73 :http:statuscode:`501 Not Implemented`: 74 * ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED``: the chosen ``tan_channel`` or one of ``tan_channels`` is not currently supported. 75 * This server does not support conversion, client should check config response. 76 77 **Details:** 78 79 .. ts:def:: CashoutResponse 80 81 interface CashoutResponse { 82 // ID identifying the operation being created 83 cashout_id: Integer; 84 }