document purse deletion API

1 files changed, 28 insertions, 0 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 7fbe6fe2..68528fb7 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -3930,6 +3930,34 @@ Wallet-to-wallet transfers
     }
 
 
+
+.. http:delete:: /purses/$PURSE_PUB
+
+  Delete a purse that is unmerged and not yet expired. Refunds any money that
+  is already in the purse.
+
+  **Request:**
+
+  The request body must be empty, as recommended for HTTP delete in general.
+  To authorize the request, the header must contain a
+  ``Taler-Purse-Signature: $PURSE_SIG`` where ``$PURSE_SIG`` is the Crockford base32-encoded
+  EdDSA signature of purpose TALER_SIGNATURE_WALLET_PURSE_DELETE.
+
+  **Response:**
+
+  :http:statuscode:`204 No Content`:
+    The operation succeeded, the exchange confirms that the purse
+    was deleted.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid.
+    This response comes with a standard `ErrorDetail` response.
+  :http:statuscode:`404 Not Found`:
+    The purse is not known. Might have already been deleted previously.
+  :http:statuscode:`409 Conflict`:
+    It is too late to delete the purse, its fate (merge or expiration)
+    was already decided.
+
+
 .. http:POST:: /purses/$PURSE_PUB/merge
 
   Merge purse with account, adding the value of the purse into