Changeset 12305 for main/waeup.ikoba/branches/uli-payments/src/waeup/ikoba/payments/paypal.py

Timestamp:

23 Dec 2014, 13:06:04 (10 years ago)

Author:

uli

Message:

Put all local changes into repos. Sorry for the mess!

File:

• main/waeup.ikoba/branches/uli-payments/src/waeup/ikoba/payments/paypal.py (modified) (3 diffs)

main/waeup.ikoba/branches/uli-payments/src/waeup/ikoba/payments/paypal.py

@@ -18 +18 @@
 """Support for PayPal payments.
 """
+import decimal
+import grok
 import ConfigParser
+import inspect
 import paypalrestsdk
+import re
+import uuid
+from zope import schema
 from zope.component import queryUtility
-from waeup.ikoba.interfaces import IPayPalConfig
+from zope.interface import Interface, Attribute
+from waeup.ikoba.interfaces import MessageFactory as _
+from waeup.ikoba.interfaces import IPayPalConfig, SimpleIkobaVocabulary
+from waeup.ikoba.utils.helpers import attrs_to_fields
+from waeup.ikoba.payments.interfaces import (
+    IPayment, IPaymentGatewayService, IPayer, IPaymentItem, IPayee,
+    )
+from waeup.ikoba.payments.paypal_countries import COUNTRIES_VOCAB
+from waeup.ikoba.payments.paypal_currencies import CURRENCIES_VOCAB
+
+#: Intents allowed for paypal based payments
+PAYMENT_INTENTS = ('sale', 'authorize', 'order')
+
+#: Payment methods allowed by PayPal
+PAYMENT_METHODS = ('credit_card', 'paypal')
+
+#: Payer status set/accepted by PayPal
+PAYER_STATUS = ('VERIFIED', 'UNVERIFIED')
+
+#: Tax ID types accepted by PayPal (yes, this list is complete)
+TAX_ID_TYPES = ('BR_CPF', 'BR_CNPJ')
+
+#: Address types accepted by PayPal
+ADDRESS_TYPES = ('residential', 'business', 'mailbox')
+
+#: A vocabulary with address types
+ADDRESS_TYPES_VOCAB = SimpleIkobaVocabulary(
+    *[(_(x), x) for x in ADDRESS_TYPES])
+
+#: Credit card types accepted by PayPal
+CREDIT_CARD_TYPES = ('visa', 'mastercard', 'discover', 'amex')
+
+CREDIT_CARD_TYPES_VOCAB = SimpleIkobaVocabulary(
+    *[(_(x), x) for x in CREDIT_CARD_TYPES])
+
+#: Credit card status accepted by PayPal
+CREDIT_CARD_STATUS = ('expired', 'ok')
+
+CREDIT_CARD_STATUS_VOCAB = SimpleIkobaVocabulary(
+    *[(_(x), x) for x in CREDIT_CARD_STATUS])
+
+#: Stock keeping units we support.
+STOCK_KEEPING_UNITS = {
+    "pcs": _("pieces"),
+    }
+
+STOCK_KEEPING_UNITS_VOCAB = SimpleIkobaVocabulary(
+    *[(value, key) for key, value in STOCK_KEEPING_UNITS.items()])
+
+#: Payment methods (flags) used by PayPal
+PAYMENT_OPTION_METHODS = ('INSTANT_FUNDING_SOURCE', )
+PAYMENT_OPTION_METHODS_VOCAB = SimpleIkobaVocabulary(
+    *[(_(x), x) for x in PAYMENT_OPTION_METHODS])
+
+
+def to_dict(obj, name_map={}):
+    """Turn `obj` into some dict representation.
+    """
+    result = dict()
+    for name in dir(obj):
+        if name.startswith('_'):
+            continue
+        value = getattr(obj, name)
+        if value is None:
+            continue
+        if inspect.ismethod(value):
+            continue
+        if hasattr(value, 'to_dict'):
+            value = value.to_dict()
+        elif isinstance(value, list):
+            value = [x.to_dict() for x in value]
+        elif isinstance(value, decimal.Decimal):
+            value = u"%.2f" % (value, )
+        else:
+            value = unicode(value)
+        name = name_map.get(name, name)
+        result[name] = value
+    return result
 
 
@@ -91 +174 @@
 
 
-def get_payment():
+class Payer(object):
+    """A payer as required in paypal payments.
+
+    According to Paypal docs:
+
+    `payment_method` must be one of ``'paypal'`` or ``'credit_card'``
+    as stored in `PAYMENT_METHODS`.
+
+    `funding_instruments` is a list of `FundingInstrument` objects. I
+    think the list must be empty for ``paypal`` payments and must
+    contain at least one entry for ``credit_card`` payments.
+
+    `payer_info` must be provided for ``paypal`` payments and might be
+    provided for ``credit_card`` payments. It's a `PayerInfo` object.
+
+    `status` reflects the payer's PayPal account status and is
+    currently supported for ``paypal`` payments. Allowed values are
+    ``'VERIFIED'`` and ``'UNVERIFIED'`` as stored in `PAYER_STATUS`.
+    """
+    def __init__(self, payment_method, funding_instruments=[],
+                 payer_info=None, status=None):
+        if payment_method not in PAYMENT_METHODS:
+            raise ValueError(
+                "Invalid payment method: use one of %s" %
+                (PAYMENT_METHODS, )
+                )
+        if status and status not in PAYER_STATUS:
+            raise ValueError(
+                "Invalid status: use one of %s" % (PAYER_STATUS, )
+                )
+        self.payment_method = payment_method
+        self.funding_instruments = funding_instruments
+        self.payer_info = payer_info
+        self.status = status
+
+
+class PayerInfo(object):
+    """Payer infos as required by Paypal payers.
+
+    Normally used with a `Payer` instance (which in turn is part of a
+    `payment`).
+
+    According to PayPal docs:
+
+    Pre-filled by PayPal when `payment_method` is ``'paypal'``.
+
+    `email`: 127 chars max. I don't think, this value is pre-filled.
+
+    `first_name`: First name of payer. Assigned by PayPal.
+
+    `last_naem`: Last name of payer. Assigned by PayPal.
+
+    `payer_id`: Payer ID as assigned by PayPal. Do not mix up with any
+    Ikoba Payer IDs.
+
+    `phone`: Phone number representing the payer. 20 chars max.
+
+    `shipping_address`: a shipping address object of payer. Assigned
+    by PayPal.
+
+    `tax_id_type`: Payer's tax ID type. Allowed values: ``'BR_CPF'``,
+    ``'BR_CNPJ'`` (I have not the slightest clue what that means).
+    Supported (PayPal-wise) with ``paypal`` payment method only (not
+    with ``credit_card``).
+
+    `tax_id`: Payer's tax ID. Here the same as for `tax_id_type`
+    applies (except that also other values are accepted).
+
+    By default all values are set to the empty string and shipping
+    address to `None`.
+
+    See also: :class:`Payer`
+    """
+    def __init__(self, email='', first_name='', last_name='',
+                 payer_id='', phone='', shipping_address=None,
+                 tax_id_type='', tax_id=''):
+        if tax_id_type and tax_id_type not in TAX_ID_TYPES:
+            raise ValueError(
+                "Invalid tax id type: use one of %s" %
+                (TAX_ID_TYPES, )
+                )
+        self.email = email
+        self.first_name = first_name
+        self.last_name = last_name
+        self.payer_id = payer_id
+        self.phone = phone
+        self.shipping_address = shipping_address
+        self.tax_id_type = tax_id_type
+        self.tax_id = tax_id
+
+
+class FundingInstrument(object):
+    """Representation of a payer's funding instrument as required by PayPal.
+
+    Represents always a credit card. Either by a complete set of
+    credit card infos or by a credit card token, which contains only a
+    limited set of credit card data and represents a full set stored
+    in PayPal vault.
+    """
+
+    def __init__(self, credit_card=None, credit_card_token=None):
+        if credit_card is None and credit_card_token is None:
+            raise ValueError(
+                "Must provide credit card data or a token")
+        if credit_card is not None and credit_card_token is not None:
+            raise ValueError(
+                "Must provide credit card data *or* a token, not both.")
+        self.credit_card = credit_card
+        self.credit_card_token = credit_card_token
+
+    def to_dict(self):
+        return to_dict(self)
+
+
+class ICreditCard(Interface):
+    """A credit card (full data set) as accepted by PayPal.
+    """
+
+    paypal_id = schema.TextLine(
+        title=u'PayPal ID',
+        description=u'ID of the credit card provided by PayPal.',
+        required=False,
+        )
+
+    payer_id = schema.TextLine(
+        title=u'Payer ID',
+        description=(u'A unique identifier for the credit card. This '
+                     u'identifier is provided by Ikoba and must be set '
+                     u'with all future transactions, once put into '
+                     u'PayPal vault.'),
+        required=True,
+        )
+
+    number = schema.TextLine(
+        title=u'Credit Card Number',
+        description=u'Numeric characters only w/o spaces or punctuation',
+        required=True,
+        )
+
+    credit_card_type = schema.Choice(
+        title=u'Credit Card Type',
+        description=u'Credit card types supported by PayPal.',
+        required=True,
+        source=CREDIT_CARD_TYPES_VOCAB,
+        )
+
+    expire_month = schema.Int(
+        title=u'Expiration Month',
+        description=u"Month, the credit card expires.",
+        required=True,
+        default=1,
+        min=1,
+        max=12,
+        )
+
+    expire_year = schema.Int(
+        title=u'Expiration Year',
+        description=u'4-digit expiration year.',
+        required=True,
+        default=2020,
+        min=1900,
+        max=9999,
+        )
+
+    cvv2 = schema.TextLine(
+        title=u'CVV2',
+        description=u'3-4 digit card validation code',
+        required=False,
+        )
+
+    first_name = schema.TextLine(
+        title=u'First Name',
+        description=u"Cardholder's first name.",
+        required=False,
+        )
+
+    last_name = schema.TextLine(
+        title=u'Last Name',
+        description=u"Cardholder's last name.",
+        required=False,
+        )
+
+    billing_address = Attribute(
+        "Billing address associated with card.")
+
+    state = schema.Choice(
+        title=u"Status",
+        description=(u"Status of credit card funding instrument. "
+                     u"Value assigned by PayPal."
+                     ),
+        required=False,
+        source=CREDIT_CARD_STATUS_VOCAB,
+        default=None,
+        )
+
+    valid_unti = schema.TextLine(
+        title=u'Valid until',
+        description=(u'Funding instrument expiratiopn date, '
+                     u'assigned by PayPal'),
+        required=False,
+        )
+
+
+@attrs_to_fields
+class CreditCard(object):
+    """A credit card (full info set) as used by PayPal.
+
+    Normally used with a `FundingInstrument` instance.
+
+    According to PayPal docs:
+
+    `paypal_id`: provided by PayPal when storing credit card
+          data. Required if using a stored credit card.
+
+    `payer_id`: Unique identifier. If none is given, we assign a
+          uuid. The uuid reads 'PAYER_<32 hex digits>'.
+
+    `number`: Credit card number. Numeric characters only with no
+          spaces or punctuation. The string must conform with modulo
+          and length required by each credit card type. Redacted in
+          responses. Required.
+
+    `credit_card_type`: One of ``'visa'``, ``'mastercard'``,
+          ``'discover'``, ``'amex'``. Required.
+
+    `expire_month`: Expiration month. A number from 1 through
+          12. Required.
+
+    `expire_year`: 4-digit expiration year. Required.
+
+    `cvv2`: 3-4 digit card validation code.
+
+    `first_name`: card holders first name.
+
+    `last_name`: card holders last name.
+
+    `billing_address`: Billing address associated with card. A
+      `Billing` instance.
+
+    `state`: state of the credit card funding instrument. Valid values
+      are ``'expired'`` and ``'ok'``. *Value assigned by PayPal.*
+
+    `paypal_valid_until`: Funding instrument expiration date.
+       *Value assigned by PayPal.* Not to confuse with the credit cards
+       expiration date, which is set via `expire_month` and
+       `expire_year`.
+
+    """
+    grok.implements(ICreditCard)
+
+    def __init__(self, paypal_id=None, payer_id=None, number=None,
+                 credit_card_type=None, expire_month=1, expire_year=2000,
+                 cvv2=None, first_name=None, last_name=None,
+                 billing_address=None, state=None, paypal_valid_until=None):
+        if not re.match('^[0-9]+$', number):
+            raise ValueError("Credit card number may "
+                             "not contain non-numbers.")
+        if payer_id is None:
+            payer_id = u'PAYER_' + unicode(uuid.uuid4().hex)
+        self.paypal_id = paypal_id
+        self.payer_id = payer_id
+        self.number = number
+        self.credit_card_type = credit_card_type
+        self.expire_month = expire_month
+        self.expire_year = expire_year
+        self.cvv2 = cvv2
+        self.first_name = first_name
+        self.last_name = last_name
+        self.billing_address = billing_address
+        self.state = state
+        self.paypal_valid_until = paypal_valid_until
+
+    def to_dict(self):
+        return to_dict(self, name_map={'credit_card_type': 'type'})
+
+
+class ICreditCardToken(Interface):
+    """A credit card token corresponding to a credit card stored with PayPal.
+    """
+    credit_card_id = schema.TextLine(
+        title=u"Credit Card ID",
+        description=u"ID if credit card previously stored with PayPal",
+        required=True,
+        )
+
+    payer_id = schema.TextLine(
+        title=u'Payer ID',
+        description=(u'A unique identifier for the credit card. This '
+                     u'identifier is provided by Ikoba and must be set '
+                     u'with all future transactions, once put into '
+                     u'PayPal vault.'),
+        required=True,
+        )
+
+    last4 = schema.TextLine(
+        title=u"Credit Card's last 4 numbers",
+        description=(
+            u"Last four digits of the stored credit card number. "
+            u"Value assigned by PayPal."),
+        required=False,
+        min_length=4,
+        max_length=4
+        )
+
+    credit_card_type = schema.Choice(
+        title=u'Credit Card Type',
+        description=(
+            u'Credit card type supported by PayPal. Value assigned '
+            u'by PayPal.'),
+        required=False,
+        source=CREDIT_CARD_TYPES_VOCAB,
+        )
+
+    expire_month = schema.Int(
+        title=u'Expiration Month',
+        description=u"Month, the credit card expires. Assigned by PayPal.",
+        required=True,
+        default=1,
+        min=1,
+        max=12,
+        )
+
+    expire_year = schema.Int(
+        title=u'Expiration Year',
+        description=u'4-digit expiration year. Assigned by PayPal.',
+        required=True,
+        default=2020,
+        min=1900,
+        max=9999,
+        )
+
+
+class CreditCardToken(object):
+    grok.implements(ICreditCardToken)
+
+    def __init__(self, credit_card_id, payer_id=None, last4=None,
+                 credit_card_type=None, expire_month=None, expire_year=None):
+        self.credit_card_id = credit_card_id
+        self.payer_id = payer_id
+        self.last4 = last4
+        self.credit_card_type = credit_card_type
+        self.expire_month = expire_month
+        self.expire_year = expire_year
+
+    def to_dict(self):
+        return to_dict(self, name_map={'credit_card_type': 'type'})
+
+
+class IShippingAddress(Interface):
+    """A shipping address as accepted by PayPal.
+    """
+    recipient_name = schema.TextLine(
+        title=u'Recipient Name',
+        required=True,
+        description=u'Name of the recipient at this address.',
+        max_length=50,
+        )
+
+    type = schema.Choice(
+        title=u'Address Type',
+        description=u'Address Type.',
+        required=False,
+        source=ADDRESS_TYPES_VOCAB,
+        )
+
+    line1 = schema.TextLine(
+        title=u'Address Line 1',
+        required=True,
+        description=u'Line 1 of the address (e.g., Number, street, etc.)',
+        max_length=100,
+        )
+
+    line2 = schema.TextLine(
+        title=u'Address Line 2',
+        required=False,
+        description=u'Line 2 of the address (e.g., Suite, apt #, etc.)',
+        max_length=100,
+        )
+
+    city = schema.TextLine(
+        title=u'City',
+        required=True,
+        description=u'City name',
+        max_length=50,
+        )
+
+    country_code = schema.Choice(
+        title=u'Country',
+        required=True,
+        description=u'2-letter country code',
+        source=COUNTRIES_VOCAB,
+        )
+
+    postal_code = schema.TextLine(
+        title=u'Postal code',
+        required=False,
+        description=(u'Zip code or equivalent is usually required '
+                     u'for countries that have them.'),
+        max_length=20,
+        )
+
+    state = schema.TextLine(
+        title=u'State',
+        required=False,
+        description=(u'2-letter code for US stated, and the '
+                     u'equivalent for other countries.'),
+        max_length=100,
+        )
+
+    phone = schema.TextLine(
+        title=u'Phone',
+        required=False,
+        description=u'Phone number in E.123 format.',
+        max_length=50,
+        )
+
+
+@attrs_to_fields
+class ShippingAddress(object):
+    """A shipping address as used in PayPal transactions.
+    """
+    grok.implements(IShippingAddress)
+
+    def __init__(self, recipient_name, type='residential', line1='',
+                 line2=None, city='', country_code=None,
+                 postal_code=None, state=None, phone=None):
+        self.recipient_name = recipient_name
+        self.type = type
+        self.line1 = line1
+        self.line2 = line2
+        self.city = city
+        self.country_code = country_code
+        self.postal_code = postal_code
+        self.state = state
+        self.phone = phone
+
+    def to_dict(self):
+        return to_dict(self)
+
+
+class IAddress(Interface):
+    """An address as accepted by PayPal.
+    """
+    line1 = schema.TextLine(
+        title=u'Address Line 1',
+        required=True,
+        description=u'Line 1 of the address (e.g., Number, street, etc.)',
+        max_length=100,
+        )
+
+    line2 = schema.TextLine(
+        title=u'Address Line 2',
+        required=False,
+        description=u'Line 2 of the address (e.g., Suite, apt #, etc.)',
+        max_length=100,
+        )
+
+    city = schema.TextLine(
+        title=u'City',
+        required=True,
+        description=u'City name',
+        max_length=50,
+        )
+
+    country_code = schema.Choice(
+        title=u'Country',
+        required=True,
+        description=u'2-letter country code',
+        source=COUNTRIES_VOCAB,
+        )
+
+    postal_code = schema.TextLine(
+        title=u'Postal code',
+        required=False,
+        description=(u'Zip code or equivalent is usually required '
+                     u'for countries that have them.'),
+        max_length=20,
+        )
+
+    state = schema.TextLine(
+        title=u'State',
+        required=False,
+        description=(u'2-letter code for US stated, and the '
+                     u'equivalent for other countries.'),
+        max_length=100,
+        )
+
+    phone = schema.TextLine(
+        title=u'Phone',
+        required=False,
+        description=u'Phone number in E.123 format.',
+        max_length=50,
+        )
+
+
+@attrs_to_fields
+class Address(object):
+    """A postal address as used in PayPal transactions.
+    """
+    grok.implements(IAddress)
+
+    def __init__(self, line1='', line2=None, city='', country_code=None,
+                 postal_code=None, state=None, phone=None):
+        self.line1 = line1
+        self.line2 = line2
+        self.city = city
+        self.country_code = country_code
+        self.postal_code = postal_code
+        self.state = state
+        self.phone = phone
+
+    def to_dict(self):
+        """Turn Adress into a dict that can be fed to PayPal classes.
+        """
+        return to_dict(self)
+
+
+class AmountDetails(object):
+    """Amount details can be given with Amount objects.
+
+    All parameters are passed in as decimals (`decimal.Decimal`).
+
+    All numbers stored here, might have 10 characters max with
+    support for two decimal places.
+
+    No parameter is strictly required, except `subtotal`, which must
+    be set if any of the other values is set.
+
+    `shipping`: Amount charged for shipping.
+
+    `subtotal`: Amount for subtotal of the items. Automatically
+      computed. If no other item was set, subtotal is `None`.
+
+    `tax`: Amount charged for tax.
+
+    `fee`: Fee charged by PayPal. In case of a refund, this is the fee
+      amount refunded to the original recipient of the payment. Value
+      assigned by PayPal.
+
+    `handling_fee`: Amount being charged for the handling
+      fee. Currently supported with paypal payment_method only, but
+      available for credit_card payment_method at a later date.
+
+    `insurance`: Amount being charged for the insurance fee. Currently
+      supported with paypal payment_method only, but available for
+      credit_card payment_method at a later date.
+
+    `shipping_discount`: Amount being discounted for the shipping
+      fee. Currently supported with paypal payment_method only, but
+      available for credit_card payment_method at a later date.
+    """
+    def __init__(self, shipping=None, tax=None, fee=None,
+                 handling_fee=None, insurance=None, shipping_discount=None):
+        self.shipping = shipping
+        self.tax = tax
+        self.fee = fee
+        self.handling_fee = handling_fee
+        self.insurance = insurance
+        self.shipping_discount = shipping_discount
+
+    @property
+    def subtotal(self):
+        names = (
+            'shipping', 'tax', 'fee', 'handling_fee', 'insurance',
+            'shipping_discount'
+            )
+        result = None
+        for name in names:
+            val = getattr(self, name)
+            if name == 'shipping_discount' and val is not None:
+                val = -val
+            if val is not None:
+                if result is None:
+                    result = val
+                else:
+                    result += val
+        return result
+
+    def to_dict(self):
+        return to_dict(self)
+
+
+class IAmount(Interface):
+    """An amount as used by PayPal in payments.
+    """
+    currency = schema.Choice(
+        title=u'Currency',
+        description=u'PayPal does not support all currencies. Required.',
+        required=True,
+        source=CURRENCIES_VOCAB,
+        default=u'USD',
+        )
+
+    total = schema.Decimal(
+        title=u'Total',
+        description=(
+            u'Total amount charged from the payer to the payee. '
+            u'In case of a refund, this is the refunded amount to '
+            u'the original payer from the payee.'),
+        required=True,
+        default=decimal.Decimal("0.00"),
+        max=decimal.Decimal("9999999.99")
+        )
+
+    details = Attribute(
+        """Additional details related to a payment amount.
+        """)
+
+
+@attrs_to_fields
+class Amount(object):
+    grok.implements(IAmount)
+
+    def __init__(self, currency="USD", total=decimal.Decimal("0.00"),
+                 details=None):
+        self.currency = currency
+        self.total = total
+        self.details = details
+
+    def to_dict(self):
+        return to_dict(self)
+
+
+class IItem(Interface):
+    """PayPal Item.
+
+    Items in a PayPal context are goods sold to customers.
+    """
+    quantity = schema.Int(
+        title=u"Quantity",
+        description=u"Number of this particular items.",
+        required=True,
+        default=1,
+        max=9999999999,
+        )
+
+    name = schema.TextLine(
+        title=u"Name",
+        description=u"Item name",
+        required=True,
+        max_length=127,
+        )
+
+    price = schema.Decimal(
+        title=u"Price",
+        description=u"Price",
+        required=True,
+        max=decimal.Decimal("9999999.99"),
+        )
+
+    currency = schema.Choice(
+        title=u"Currency",
+        description=u"Currency",
+        source=CURRENCIES_VOCAB,
+        default=u'USD',
+        required=True,
+        )
+
+    sku = schema.Choice(
+        title=u"SKU",
+        description=u"Stock keeping unit corresponding to item.",
+        source=STOCK_KEEPING_UNITS_VOCAB,
+        required=False,
+        )
+
+    description = schema.TextLine(
+        title=u"Description",
+        description=(
+            u"Description of Item. Currently supported with paypal "
+            u"payments only."
+            ),
+        max_length=127,
+        required=False,
+        )
+
+    tax = schema.Decimal(
+        title=u"Tax",
+        description=(
+            u"Tax of the item. Currently supported with paypal "
+            u"payments only."
+            ),
+        required=False,
+        )
+
+
+@attrs_to_fields
+class Item(object):
+    """See IItem for docs.
+    """
+    grok.implements(IItem)
+
+    def __init__(self, name, quantity=1, price=decimal.Decimal("0.00"),
+                 currency="USD", sku=None, description=None, tax=None):
+        self.name = name
+        self.quantity = quantity
+        self.price = price
+        self.currency = currency
+        self.sku = sku
+        self.description = description
+        self.tax = tax
+
+    def to_dict(self):
+        return to_dict(self)
+
+
+class IItemList(Interface):
+    """List of `Item` objects and a related `ShippingAddress`.
+
+    `items`: can be a simple list of `Item` objects.
+
+    `shipping_address`: a `ShippingAddress` object. Only needed if
+      different from Payer address.
+    """
+    items = schema.List(
+        title=u"Items",
+        description=u"PayPal Items are sold goods",
+        value_type=schema.Object(
+            title=u"Item",
+            description=u"Item in a list",
+            schema=IItem,
+            )
+        )
+
+    shipping_address = schema.Object(
+        title=u"Shipping Address",
+        description=u"Shipping address of receiver if different from payee.",
+        schema=IShippingAddress,
+        required=False,
+        )
+
+
+@attrs_to_fields
+class ItemList(object):
+    """List of `Item` objects and a related `ShippingAddress`.
+
+    `items`: can be a simple list of `Item` objects.
+
+    `shipping_address`: a `ShippingAddress` object. Only needed if
+      different from Payer address.
+    """
+    grok.implements(IItemList)
+
+    def __init__(self, items=[], shipping_address=None):
+        self.items = items
+        self.shipping_address = shipping_address
+
+    def to_dict(self):
+        return to_dict(self)
+
+
+class IPaymentOptions(Interface):
+    """Payment options requested for a certain purchase unit.
+
+    `allowed_payment_method`: Optional payment method type. If
+      specified, the transaction will go through for only instant
+      payment. Allowed values: ``INSTANT_FUNDING_SOURCE``. Only for
+      use with the ``paypal`` payment_method, not relevant for the
+      ``credit_card`` payment_method.
+    """
+    allowed_payment_method = schema.Choice(
+        title=u"Allowed payment method",
+        description=(
+            u"Optional payment type. If specified, the transaction "
+            u"will go through for only instant payment. Only for use "
+            u"with paypal payment method, not relevant for credit cards."
+            ),
+        required=False,
+        source=PAYMENT_OPTION_METHODS_VOCAB,
+        )
+
+
+@attrs_to_fields
+class PaymentOptions(object):
+    """Payment options requested for a certain purchase unit.
+    """
+    grok.implements(IPaymentOptions)
+
+    def __init__(self, allowed_payment_method=None):
+        if allowed_payment_method not in (
+            None, 'INSTANT_FUNDING_SOURCE'):
+            raise ValueError(
+                "allowed_payment_method of PaymentOptions must be None or "
+                "'INSTANT_FUNDING_SOURCE'"
+                )
+        self.allowed_payment_method = allowed_payment_method
+
+    def to_dict(self):
+        return to_dict(self)
+
+
+class ITransaction(Interface):
+    """PayPal transactions provide payment transaction details.
+    """
+    amount = schema.Object(
+        title=u"Amount",
+        description=u"Amount being collected.",
+        schema=IAmount,
+        required=True,
+        )
+
+    description = schema.TextLine(
+        title=u"Description",
+        description=u"Description of transaction",
+        required=False,
+        max_length=127,
+        )
+
+    item_list = schema.Object(
+        title=u"Item List",
+        description=u"List of items",
+        required=False,
+        schema=IItemList,
+        )
+
+    # XXX: This should be defined more precisely: What kind of objects, etc.
+    #      PayPal docs say: "array of sale, authorization, capture, or refund,
+    #      objects"
+    related_resources = Attribute("Arbitrary objects")
+
+    invoice_number = schema.TextLine(
+        title=u"Invoice Number",
+        description=(
+            u"Invoice number used to track the payment. "
+            u"Currently supported with paypal payment_method only."
+            ),
+        required=False,
+        max_length=256,
+        )
+
+    custom = schema.TextLine(
+        title=u"Custom text",
+        description=(
+            u"Free-form field for the use of clients. Currently "
+            u"supported with paypal payment_method only."),
+        required=False,
+        max_length=256,
+        )
+
+    soft_descriptor = schema.TextLine(
+        title=u"Soft descriptor",
+        description=(
+            u"Soft descriptor used when charging this funding "
+            u"source. Currently supported with paypal payment_method only"
+            ),
+        required=False,
+        max_length=22,
+        )
+
+    payment_options = schema.Object(
+        title=u"Payment Options",
+        description=u"Payment options requested for this purchase unit.",
+        required=False,
+        schema=IPaymentOptions,
+        )
+
+
+@attrs_to_fields
+class Transaction(object):
+    # See ITransaction for description
+
+    grok.implements(ITransaction)
+
+    def __init__(self, amount, description=None, item_list=None,
+                 related_resources=[], invoice_number=None, custom=None,
+                 soft_descriptor=None, payment_options=None):
+        self.amount = amount
+        self.description = description
+        self.item_list = item_list
+        self.related_resources = related_resources
+        self.invoice_number = invoice_number
+        self.custom = custom
+        self.soft_descriptor = soft_descriptor
+        self.payment_options = payment_options
+
+    def to_dict(self):
+        """Give a `dict` representation of this `Transaction`.
+        """
+        return to_dict(self)
+
+
+def get_payment(intent='sale', payment_method='credit_card'):
     """Construct a payment.
 
     You have to `create()` the payment yourself.
 
+    Returns a paypalrestsdk Payment object, not an Ikoba payment.
+
+    As `intent` currently only the string ``'sale'`` is supported.
+
     XXX: Just some sampledata yet.
     """
+    if intent != "sale":
+        raise ValueError(
+            "Currently, only 'sale' is allowed as type of paypal"
+            "payment.")
     payment = paypalrestsdk.Payment(
         {
-            "intent": "sale",
+            "intent": intent,
             "payer": {
                 "payment_method": "credit_card",
@@ -123 +1094 @@
                     ]},
             "transactions": [{
-                    "amount": {
-                        "total": "7.47",
-                        "currency": "USD",
-                        "details": {
-                            "subtotal": "7.41",
-                            "tax": "0.03",
-                            "shipping": "0.03"}},
-                    "description": ("This is the payment "
-                                    "transaction description.")
-                    }]
+                "amount": {
+                    "total": "7.47",
+                    "currency": "USD",
+                    "details": {
+                        "subtotal": "7.41",
+                        "tax": "0.03",
+                        "shipping": "0.03"}},
+                "description": ("This is the payment "
+                                "transaction description.")
+                }]
             }
         )
     return payment
+
+
+class IPayPalPayment(IPayment):
+    """A paypal payment.
+    """
+
+
+class PayPalPayment(grok.Model):
+    """A paypal payment.
+    """
+    pass
+
+
+class PayPalCreditCardService(grok.GlobalUtility):
+    grok.implements(IPaymentGatewayService)
+    grok.name('paypal_creditcard')
+
+    title = _(u'Credit Card (PayPal)')
+
+    def create_payment(self, payer, payment_item,  payee=None):
+        if not IPayer.providedBy(payer):
+            payer = IPayer(payer)
+        if not IPaymentItem.providedBy(payment_item):
+            payment_item = IPaymentItem(payment_item)
+        return None
+        payment = get_payment()
+        return payment
+
+
+class PayPalRegularPaymentService(grok.GlobalUtility):
+    grok.implements(IPaymentGatewayService)
+    grok.name('paypal_regular')
+
+    title = _(u'PayPal Payment')