taler-docs

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

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

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