From 8c0ae3802525659729ad4f30f5f567cafa9a8121 Mon Sep 17 00:00:00 2001
From: Marcello Stanisci <stanisci.m@gmail.com>
Date: Fri, 28 Jun 2019 15:10:13 +0200
Subject: Drafting headless withdrawals API.

---
 api-bank.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/api-bank.rst b/api-bank.rst
index 9256e3d7..8c6211cd 100644
--- a/api-bank.rst
+++ b/api-bank.rst
@@ -21,6 +21,83 @@
 Bank API
 =========
 
+This API provides programmatic user registration in the bank.
+
+.. _bank-register:
+.. http:post:: /user/register
+
+**Request** The body of this request must have the format of a `BankRegistrationRequest`_.
+
+**Response**
+
+:status 200 OK: The new user has been correctly registered.
+:status 409 Conflict: the username requested by the client is not available anymore
+:status 406 Not Acceptable: unacceptable characters were given as username / password.
+
+**Details**
+
+.. _BankRegistrationRequest:
+.. code-block:: tsref
+
+  interface BankRegistrationRequest {
+  
+    // Username to use for registration.
+    username: string;
+
+    // Password to associate with the username.
+    password: string;
+  }
+
+
+This API provides programmatic withdrawing of cash via Taler.
+
+.. _bank-register:
+.. http:post:: /taler/withdraw
+
+**Request** The body of this request must have the format of a `BankTalerWithdrawRequest`_.
+
+**Response**
+
+:status 200 OK: The withdrawal was correctly initiated, and a `BankTalerWithdrawResponse`_ object is returned.
+:status 406 Not Acceptable: the user does not have sufficient credit to fulfill their request.
+:status 404 Not Found: The (exchange's) bank account was not found.
+
+**Details**
+
+.. _BankTalerWithdrawRequest:
+.. code-block:: tsref
+
+  interface BankTalerWithdrawRequest {
+
+    // Authentication method used
+    auth: BankAuth;
+  
+    // How much money will be withdrawn
+    amount: Amount;
+
+    // Reserve public key.
+    reserve_pub: string;
+
+    // Exchange bank details specified in the 'payto'
+    // format.  NOTE: this field is optional, therefore
+    // the bank will initiate the withdrawal with the
+    // default exchange, if not given.
+    exchange_wire_details: string;
+  }
+
+.. _BankTalerWithdrawResponse:
+.. code-block:: tsref
+
+  interface BankTalerWithdrawResponse {
+
+    // Sender account details in 'payto' format.
+    sender_wire_details: string;
+
+    // Exchange base URL.  Optional: only returned
+    // if the user used the default exchange.
+    exchange_url: string;
+  }
+
 This API allows one user to send money to another user, within the same "test"
 bank.  The user calling it has to authenticate by including his credentials in the
 request.
-- 
cgit v1.2.3