-first rough sketch for IBAN authorization plugin"

1 files changed, 32 insertions, 1 deletions

diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst
index 67c1fef..152a65e 100644
--- a/doc/sphinx/rest.rst
+++ b/doc/sphinx/rest.rst
@@ -446,7 +446,9 @@ charge per truth operation using GNU Taler.
     `EncryptedKeyShare`_ is returned in body (in binary).
   :http:statuscode:`202 Accepted`:
     The escrow provider will respond out-of-band (i.e. SMS).
-    The body may contain human-readable instructions on next steps.
+    The body may contain human- or machine-readable instructions on next steps.
+    In case the response is in JSON, the format is given
+    by `ChallengeInstructionMessage`_.
   :http:statuscode:`208 Already Reported`:
     An authentication challenge was recently send, client should
     simply respond to the pending challenge.
@@ -519,3 +521,32 @@ charge per truth operation using GNU Taler.
       account_sig: EddsaSignature;
 
     }
+
+
+  .. _ChallengeInstructionMessage:
+  .. ts:def:: ChallengeInstructionMessage
+
+    type ChallengeInstructionMessage =
+      | IbanChallengeInstructionMessage;
+
+    interface IbanChallengeInstructionMessage {
+
+      // What kind of challenge is this?
+      method: "iban";
+
+      // How much should be wired?
+      amount: Amount;
+
+      // What is the target IBAN?
+      credit_iban: String;
+
+      // What is the receiver name?
+      business_name: String;
+
+      // What is the expected wire transfer subject?
+      wire_transfer_subject: Integer;
+
+      // Hint about the origin account that must be used.
+      debit_account_hint: String;
+
+    }