DD 83: Wallet Initiated Withdrawal

23.84. DD 83: Wallet Initiated Withdrawal#

Design status:: Proposed
Implementation status:: Not started
DD shepherd:: TBD
Historical contributors:: Antoine A
First published:: 2026-02-15
Last substantive change:: 2026-02-15

23.84.1. Summary#

We want to support wallet-initiated withdrawals in addition to the bank-initiated ones we currently support.

23.84.2. Motivation#

For a system like Cyclos, adding a bank-initiated withdrawal will be difficult and particularly costly to maintain. However, with wallet-initiated withdrawals, all the logic would be within the implementation of the adapter we already have and maintain.

23.84.3. Requirements#

Must be easy to implement for future adapters
Must be easy to implement and maintain in the wallet

23.84.4. Proposed Solution#

We already have a Taler Bank Integration API that is entirely dedicated to integrating withdrawals. By adding a single endpoint to enable the creation of a withdrawal, we can then reuse the current endpoints for the rest. I think this would make implementation in the wallet easier, as most of the logic should remain the same.

23.84.4.1. API#

interface IntegrationConfig {
  // Whether this implementation supports wallet initiated withdrawal
  support_wallet_initiated: boolean;
}

POST /withdrawal-operation#

This endpoint is used by the GNU Taler wallet to create a new withdraw operation.

Request:

interface BankWithdrawalOperationCreateRequest {
  // Reserve public key that should become the wire transfer
  // subject to fund the withdrawal.
  reserve_pub: EddsaPublicKey;

  // Selected amount to be transferred.
  amount: Amount;
}

Response:

200 OK:

The bank has accepted and created the withdrawal operation chosen by the wallet. The response is a BankWithdrawalOperationCreateResponse.

409 Conflict:

TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT: the reserve public key is already used.

501 Not Implemented:

This server does not support wallet initiated withdrawal.

Details:

interface BankWithdrawalOperationCreateResponse {
  // ID identifying the operation being created
  withdrawal_id: Slug;
}

23.84.5. Test Plan#

I would first implement this new endpoint in libeufin-bank first so that this new flow can be easily tested using the demo deployment and then I would add it to all adapters that can support it: taler-cyclos and maybe taler-magnet-bank.

23.84.6. Alternatives#

23.84.7. Drawbacks#

A new flow to test