{
"info": {
"author": "Edition1",
"author_email": "info@edition.nl",
"bugtrack_url": null,
"classifiers": [
"Environment :: Web Environment",
"Framework :: Plone :: 3.3",
"Framework :: Plone :: 4.0",
"Framework :: Plone :: 4.1",
"Framework :: Plone :: 4.2",
"License :: OSI Approved :: GNU General Public License (GPL)",
"Operating System :: OS Independent",
"Programming Language :: Python :: 2.4",
"Programming Language :: Python :: 2.6"
],
"description": "Introduction\n============\n\n``collective.mollie`` provides a wrapper for the `Mollie iDeal\nAPI`_. This wrapper *can* be used without any further Plone\nintegration. However, this package also provides:\n\n - `Adapters`_ to store payment information on objects.\n - `Browser views`_ which can be used to have Mollie report back.\n - An `event`_ which can be subscribed to to be notified when payment status has been updated.\n\n.. _`Mollie iDeal API`: http://www.mollie.nl/support/documentatie/betaaldiensten/ideal/\n\n\niDeal\n=====\n\nThe complete iDeal payment process contains the following steps:\n\n1. `Request the list of banks`_\n2. `Request a payment`_\n3. `Have the customer do the payment`_\n4. `Check the payment`_\n5. `Customer is returning to the site`_\n\n\nRequest the list of banks\n-------------------------\n\nSince the list of banks may change, you always need to retrieve it\nbefore you do the payment::\n\n >>> from zope.component import getUtility\n >>> from collective.mollie.interfaces import IMollieIdeal\n >>> ideal_wrapper = getUtility(IMollieIdeal)\n >>> ideal_wrapper.get_banks()\n [('0031', 'ABN AMRO'), ...]\n\nIf the ``TESTMODE`` flag is set, you can retrieve a test bank::\n\n >>> ideal_wrapper.TESTMODE = True\n >>> ideal_wrapper.get_banks()\n [('9999', 'TBM Bank')]\n >>> ideal_wrapper.TESTMODE = False\n >>> ideal_wrapper.get_banks()\n [('0031', 'ABN AMRO'), ...]\n\nThe result of the call is a list of tuples. Each tuple consists of a\nbank ID and name. The name can be used to present to the customer so\nhe/she can choose which bank to use. The ID is needed in the next\nstep.\n\n.. note ::\n\n If you want to use the test mode from Molllie to test payments,\n please **also** switch your Mollie account to test mode otherwise\n Mollie will not accept a test payment, even though the URL might\n point to the test bank.\n\n\nRequest a payment\n-----------------\n\nWhen you know which bank will be used to pay, you can request a\npayment with the API::\n\n >>> ideal_wrapper.request_payment(partner_id='999999',\n ... bank_id='9999', amount='123', message='The message',\n ... report_url='http://example.com/report',\n ... return_url='http://example.com/return',\n ... profile_key='999999')\n ('123...123', 'http://...')\n\nThe result is a ``transaction_id``, and a URL to send the customer to\nto perform the payment.\n\n.. note::\n\n The ``amount`` of the payment has to be in **cents**. The\n ``message`` may only be 29 characters (any more characters are\n ignored). The ``profile_key`` parameter is optional. You only need\n to use it if you want to use a different payment profile than the\n default for the specified account.\n\n\nHave the customer do the payment\n--------------------------------\n\nThis package does not handle this step. You should redirect the\ncustomer to the URL returned by ``request_payment``, and hope he/she\ncompletes the transaction.\n\n\nCheck the payment\n-----------------\n\nOnce the ``report_url`` (see `Request a payment`_) has been pinged by\nMollie, you can check the status of the payment::\n\n >>> ideal_wrapper.check_payment(partner_id='999999',\n ... transaction_id='123...123')\n {'transaction_id': '123...123',\n 'amount': '123',\n 'currency': 'EUR',\n 'paid': True,\n 'status': 'Success',\n 'consumer': {\n 'name': 'T. TEST',\n 'account': '0123456789',\n 'city': 'Testdorp'\n }\n }\n\nWhen the state is anything other than \"Success\", there will be no data\nabout the consumer.\n\n\nCustomer is returning to the site\n---------------------------------\n\nThis is where the customer is returned to the ``return_url``. However,\nthis step is not handled by this package. You should use the result\nfrom the previous step (`Check the payment`_) to inform the customer\nand present further actions, where appropriate.\n\nIt may happen that the ``report_url`` is not yet called and thus the\nstate of the payment is not yet known. Mollie advises to report to the\ncustomer that the status is unknown but that the payment will be\nautomatically processed once the status is final.\n\n\nPlone integration\n=================\n\nIf you want to integrate iDeal payments in your Plone project, you can\nuse the iDeal wrapper as defined in the ``MollieIdeal`` utility which\nwas described above.\n\nAdapters\n--------\n\nHowever, you can also use one of the adapters defined in the package:\n``MollieIdealPayment`` and ``MollieIdealMultiplePayments``. By using\none of these, information about payments is persistently stored on the\nadapted objects.\n\nYou can adapt any object that implements the ``IAttributeAnnotatable``\ninterface. For instance::\n\n >>> from zope.annotation import IAttributeAnnotatable\n >>> from persistent import Persistent\n >>> from zope.interface import Interface\n >>> class IFoo(Interface):\n >>> pass\n >>> class Foo(Persistent):\n ... implements(IFoo, IAttributeAnnotatable)\n\nIf you only want to store a single payment on an object, as is common\nfor a specific purchase, you can use the ``IMollieIdealPayment``\ninterface::\n\n >>> from collective.mollie.interfaces import IMollieIdealPayment\n >>> purchase = Foo()\n >>> purchase_payment = IMollieIdealPayment(purchase)\n\nNow you can request banks, a payment URL and the payment status::\n\n >>> purchase_payment.get_banks()\n [('0031', 'ABN AMRO'), ...]\n >>> purchase_payment.get_payment_url(partner_id='999999',\n ... bank_id='9999', amount='123', message='The message',\n ... report_url='http://example.com/report',\n ... return_url='http://example.com/return',\n ... profile_key='999999')\n 'http://....'\n >>> purchase_payment.get_payment_status()\n 'Success'\n\nNote that you do not have to repeat the ``partner_id`` or\n``transaction_id`` when requesting the payment status. This\ninformation was stored when you requested the payment url and is reused\nfor the ``get_payment_status`` call.\n\nAs stated earlier, the payment information is stored persistently::\n\n >>> purchase_payment.paid\n True\n >>> purchase_payment.amount\n '123'\n >>> purchase_payment.consumer\n {'name': 'T. TEST',\n 'account': '0123456789',\n 'city': 'Testdorp'\n }\n\nIn cases where multiple payments need to be stored on a single object,\nyou can use the ``IMollieIdealMultiplePayments`` interface. For\nexample if you want to allow multiple people to be able to donate to\nsome charity::\n\n >>> from collective.mollie.interfaces import IMollieIdealMultiplePayments\n >>> charity = Foo()\n >>> charity_donations = IMollieIdealMultiplePayments(charity)\n\nAs was previously the case, you can also request the available banks::\n\n >>> charity_payment.get_banks()\n [('0031', 'ABN AMRO'), ...]\n\nWhen you retrieve a payment URL, you also get a transaction ID::\n\n >>> charity_payment.get_payment_url(partner_id='999999',\n ... bank_id='9999', amount='123', message='The message',\n ... report_url='http://example.com/report',\n ... return_url='http://example.com/return',\n ... profile_key='999999')\n ('123...', 'http://....')\n\nThis transaction ID is required when you want to access the data for a\npayment::\n\n >>> charity_payment.get_payment_status('123...')\n 'Success'\n >>> payment = charity_payment.get_transaction('123...')\n >>> payment['paid']\n True\n >>> payment['amount']\n '123'\n >>> payment['consumer']\n {'name': 'T. TEST',\n 'account': '0123456789',\n 'city': 'Testdorp'\n }\n\nNote that the way to get to the payment information is also a bit\ndifferent than in the single payment case.\n\n\nBrowser Views\n-------------\n\nAs described in the section `Check the payment`_, you have to wait with\nchecking the payment status until Mollie has pinged the\n``report_url``.\n\nYou can write your own view, but you can also use one provided by\n``collective.mollie``: the ``ReportPaymentStatusView`` and\n``ReportMultiplePaymentsStatusView`` classes. These views checks\nwhether the ``transaction_id`` from the request matches one stored\non the object. If it does, the payment status of the object is checked\nimmediately.\n\nTo use the simple payment view, first register it::\n\n \n\nAlternatively you can use the multiple payment report view::\n\n \n\n(You probably should only register the view for specific\ninterfaces. And obviously you can give it any name you want.)\n\nThen use ``