taler-docs

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

083-wallet-initiated-withdrawal.rst (2806B)

      1 DD 83: Wallet Initiated Withdrawal
      2 ##################################
      3 
      4 :Design status: Proposed
      5 :Implementation status: Not started
      6 :DD shepherd: TBD
      7 :Historical contributors: Antoine A
      8 :First published: 2026-02-15
      9 :Last substantive change: 2026-02-15
     10 
     11 Summary
     12 =======
     13 
     14 We want to support wallet-initiated withdrawals in addition to the bank-initiated ones we currently support.
     15 
     16 Motivation
     17 ==========
     18 
     19 For a system like Cyclos, adding a bank-initiated withdrawal will be difficult and particularly costly to maintain.
     20 However, with wallet-initiated withdrawals, all the logic would be within the implementation of the adapter we already have and maintain.
     21 
     22 
     23 Requirements
     24 ============
     25 
     26 * Must be easy to implement for future adapters
     27 * Must be easy to implement and maintain in the wallet
     28 
     29 Proposed Solution
     30 =================
     31 
     32 We already have a Taler Bank Integration API that is entirely dedicated to integrating withdrawals.
     33 By adding a single endpoint to enable the creation of a withdrawal, we can then reuse the current endpoints for the rest.
     34 I think this would make implementation in the wallet easier, as most of the logic should remain the same.
     35 
     36 API
     37 ---
     38 
     39 .. ts:def:: IntegrationConfig
     40 
     41   interface IntegrationConfig {
     42     // Whether this implementation supports wallet initiated withdrawal
     43     support_wallet_initiated: boolean;
     44   }
     45 
     46 .. http:post:: /withdrawal-operation
     47 
     48   This endpoint is used by the GNU Taler wallet to create a new withdraw operation.
     49 
     50   **Request:**
     51 
     52   .. ts:def:: BankWithdrawalOperationCreateRequest
     53 
     54     interface BankWithdrawalOperationCreateRequest {
     55       // Reserve public key that should become the wire transfer
     56       // subject to fund the withdrawal.
     57       reserve_pub: EddsaPublicKey;
     58 
     59       // Selected amount to be transferred.
     60       amount: Amount;
     61     }
     62 
     63   **Response:**
     64 
     65   :http:statuscode:`200 OK`:
     66     The bank has accepted and created the withdrawal operation chosen by the wallet.
     67     The response is a `BankWithdrawalOperationCreateResponse`.
     68   :http:statuscode:`409 Conflict`:
     69     * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the reserve public key is already used.
     70   :http:statuscode:`501 Not Implemented`:
     71     This server does not support wallet initiated withdrawal.
     72 
     73   **Details:**
     74 
     75   .. ts:def:: BankWithdrawalOperationCreateResponse
     76 
     77     interface BankWithdrawalOperationCreateResponse {
     78       // ID identifying the operation being created
     79       withdrawal_id: Slug;
     80     }
     81 
     82 Test Plan
     83 =========
     84 
     85 I would first implement this new endpoint in libeufin-bank first so that this new flow can be easily tested using the demo deployment
     86 and then I would add it to all adapters that can support it: taler-cyclos and maybe taler-magnet-bank.
     87 
     88 
     89 Alternatives
     90 ============
     91 
     92 
     93 Drawbacks
     94 =========
     95 
     96 * A new flow to test
     97 
     98 Discussion / Q&A
     99 ================