Index: /main/waeup.ikoba/branches/uli-payments/src/waeup/ikoba/payments/interfaces.py
===================================================================
--- /main/waeup.ikoba/branches/uli-payments/src/waeup/ikoba/payments/interfaces.py	(revision 12275)
+++ /main/waeup.ikoba/branches/uli-payments/src/waeup/ikoba/payments/interfaces.py	(revision 12276)
@@ -18,4 +18,5 @@
 import decimal
 from zope import schema
+from zope.interface import Interface
 from waeup.ikoba.interfaces import (
     IIkobaObject, SimpleIkobaVocabulary, ContextualDictSourceFactoryBase)
@@ -33,4 +34,21 @@
     (_('Failed'), STATE_FAILED),
     )
+
+
+class IPaymentGatewayService(Interface):
+    """A financial gateway service.
+
+    Any gateway provider might provide several services. For instance
+    payments by credit card, scratch card, bank transfer, etc. An
+    `IPaymentGatewayService` represents one of those services.
+
+    Payment services are normally registered as a named global
+    utility.
+    """
+    title = schema.TextLine(
+        title=u'Title',
+        description=u'Human readable name of gateway service.',
+        required=True,
+        )
 
 
@@ -52,7 +70,24 @@
     """A base representation of payments.
 
+    In a payment, a payer payes someone (the payee) for something, the
+    item to pay.
+
+    We currently support only the case where one payer pays one payee
+    for one item. The item might include taxes, handling,
+    shipping, etc.
+
+    As in RL any payment is actually performed by some financial
+    service provider (like paypal, interswitch, etc.), each of which
+    might provide several types of payments (credit card, scratch
+    card, you name it).
+
+    In Ikoba we call financial service providers 'gateway' and their
+    types of services are handled as gateway types. Therefore PayPal
+    handling a credit card payment is different from PayPal handling a
+    regular PayPal account transaction.
+
     A payment can be approve()d, which means the act of paying was
-    really performed. It can also fail for any reason.
-
+    really performed. It can also fail for any reason, in which case
+    we mark the payment 'failed'.
     """
     payment_id = schema.TextLine(
@@ -69,5 +104,5 @@
 
     payed_item_id = schema.TextLine(
-        title=u'Payed Item',
+        title=u'Payed Item ID',
         default=None,
         required=True,
