document reducer return values for IBAN auth

1 files changed, 42 insertions, 2 deletions

diff --git a/doc/sphinx/reducer.rst b/doc/sphinx/reducer.rst
index 68df5b1..dcfc522 100644
--- a/doc/sphinx/reducer.rst
+++ b/doc/sphinx/reducer.rst
@@ -1591,7 +1591,7 @@ that applications must all handle. States other than ``solved`` are:
           }
         }
 
-    - **rate-limit-exceeded**:
+    - **rate-limit-exceeded**: This indicates that the user has made too many invalid attempts in too short an amount of time.
 
       .. code-block:: json
 
@@ -1609,7 +1609,7 @@ that applications must all handle. States other than ``solved`` are:
            }
          }
 
-    - **authentication-timeout**:
+    - **authentication-timeout**: This indicates that the challenge is awaiting for some external authentication process to complete. The application should ``poll`` for it to complete, or proceed with selecting other challenges.
 
       .. code-block:: json
 
@@ -1627,6 +1627,46 @@ that applications must all handle. States other than ``solved`` are:
            }
          }
 
+    - **authentication-instructions**: This indicates that the challenge requires the user to perform some authetnication method-specific actions. Details about what the user should do are provided.
+
+      .. code-block:: json
+
+        {
+          "recovery_state": "CHALLENGE_SELECTING",
+          "recovery_information": {
+              "...": "..."
+          }
+          "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+          "challenge_feedback": {
+            "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+              "state": "external-instructions",
+              "method": "iban",
+              "details": {
+                "...": "..."
+              }
+            }
+          }
+        }
+
+    The specific instructions depend on the ``method``.
+    They include:
+
+      - **iban**: The user must perform a wire transfer from their account to the Anastasis provider.
+
+        .. code-block:: json
+
+          {
+            "challenge_amount": "EUR:1",
+            "credit_iban": "DE12345789000",
+            "business_name": "Data Loss Incorporated",
+            "wire_transfer_subject": 987654321
+          }
+
+        Note that the actual wire transfer subject must contain both
+        the numeric ``wire_transfer_subject`` given above as well as
+        the string ``Anastasis``. Thus, when generating human-readable
+        instructions from the above, the display output should be
+        ``Anastasis 987654321``.
 
 **poll:**