From 288602cc2bedd17731dbc44d70711b8942c23164 Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 20 Jan 2016 15:56:47 +0100
Subject: event doc

---
 api-merchant.rst         |  2 +-
 integration-merchant.rst | 38 ++++++++++++++++++++++++++++++++++----
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/api-merchant.rst b/api-merchant.rst
index c6b8fb14..d857db00 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -24,7 +24,6 @@ Encodings
 
 Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`.
 
-.. _offer:
 .. _contract:
 
 Offer and Contract
@@ -35,6 +34,7 @@ that is legally non-binding:
 
   .. _tsref-type-Offer:
   .. code-block:: tsref
+    :name: offer
 
     interface Offer {
       // The actual contract
diff --git a/integration-merchant.rst b/integration-merchant.rst
index 37aac501..577f4d5f 100644
--- a/integration-merchant.rst
+++ b/integration-merchant.rst
@@ -10,11 +10,41 @@ The purchase flow consists of the following steps:
 
 1. UA visits merchant's checkout page
 2. The merchant's checkout page notifies the wallet
-   of the contract (``taler-deliver-contract``)
+   of the contract (``taler-deliver-contract``).
 3. The user reviews the contract inside the wallet
-4. The wallet directs the UA to the payment execution page (``taler-execute-contract``)
+4. The wallet directs the UA to the payment execution page
+5. The execution page must send the event ``taler-execute-payment`` with
+   the contract hash of the payment to be executed.
+6. The wallet executes the payment in the domain context of the
+   execution page and emits the ``taler-payment-result`` event
+   on the execution page.
+7. The execution page reacts to the payment result (which
+   is either successful or unsuccessful) by showing
+   an appropriate response to the user.
 
-The *execution page* allows the wallet to make a request
-to the merchant from the store's domain.
+----------------
+Event Reference
+----------------
 
+.. topic:: ``taler-deliver-contract``
 
+  The event takes an :ref:`offer <offer>` as event detail.
+
+.. topic:: ``taler-execute-payment``
+
+  The event takes `H_contract` of a :ref:`Contract <tsref-type-Contract>` as event detail.
+
+.. topic:: ``taler-payment-result``
+
+  The event takes the following object as event detail:
+
+  .. code-block:: tsref
+
+    {
+      // was the payment successful?
+      success: boolean;
+
+      // human-readable indication of what went wrong
+      hint: string;
+    }
+   
-- 
cgit v1.2.3