Merge pull request #34 from mociepka/preauth

Add CyberSource gateway and pre-authorization 

4 files changed, 143 insertions, 48 deletions

diff --git a/doc/index.rst b/doc/index.rst
index 9a7c5e9..617500f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -9,4 +9,6 @@ Contents:
 
    install.rst
    usage.rst
+   refund.rst
+   preauth.rst
    modules.rst
diff --git a/doc/modules.rst b/doc/modules.rst
index 7dea489..3adfecf 100644
--- a/doc/modules.rst
+++ b/doc/modules.rst
@@ -11,8 +11,8 @@ Dummy
 
 Example::
 
-   PAYMENT_VARIANTS = {
-       'dummy': ('payments.dummy.DummyProvider', {})}
+      PAYMENT_VARIANTS = {
+          'dummy': ('payments.dummy.DummyProvider', {})}
 
 
 Authorize.Net
@@ -28,12 +28,12 @@ Authorize.Net
 
 Example::
 
-   # use staging environment
-   PAYMENT_VARIANTS = {
-       'authorizenet': ('payments.authorizenet.AuthorizeNetProvider', {
-           'login_id': '1234login',
-           'transaction_key': '1234567890abcdef',
-           'endpoint': 'https://test.authorize.net/gateway/transact.dll'})}
+      # use staging environment
+      PAYMENT_VARIANTS = {
+          'authorizenet': ('payments.authorizenet.AuthorizeNetProvider', {
+              'login_id': '1234login',
+              'transaction_key': '1234567890abcdef',
+              'endpoint': 'https://test.authorize.net/gateway/transact.dll'})}
 
 
 Braintree (Python 2 only)
@@ -49,12 +49,41 @@ Braintree (Python 2 only)
 
 Example::
 
-   # use sandbox
-   PAYMENT_VARIANTS = {
-       'braintree': ('payments.braintree.BraintreeProvider', {
-           'merchant_id': '112233445566',
-           'public_key': '1234567890abcdef',
-           'private_key': 'abcdef123456'})}
+      # use sandbox
+      PAYMENT_VARIANTS = {
+          'braintree': ('payments.braintree.BraintreeProvider', {
+              'merchant_id': '112233445566',
+              'public_key': '1234567890abcdef',
+              'private_key': 'abcdef123456'})}
+
+
+Cybersource
+-----------
+
+.. class:: payments.cybersource.CyberSourceProvider(merchant_id, password[, sandbox=True, capture=True])
+
+   This backend implements payments using `Cybersource <http://www.cybersource.com/www/>`_.
+
+   :param merchant_id: Your Merchant ID
+   :param password: Generated transaction security key for the SOAP toolkit
+   :param sandbox: Whether to use a sandbox environment for testing
+   :param capture: Whether to capture the payment automatically.  See :ref:`capture-payments` for more details.
+
+Example::
+
+      # use sandbox
+      PAYMENT_VARIANTS = {
+          'cybersource': ('payments.cybersource.CyberSourceProvider', {
+              'merchant_id': 'example',
+              'password': '1234567890abcdef',
+              'capture': False,
+              'sandbox': True})}
+
+
+Cybersource allows you to pass Merchant-Defined Data, which is additional information about the payment or the order, such as an order number, additional customer information, or a special comment or request from the customer. This can be accomplished by passing your data to the :class:`Payment` instance::
+
+      >>> payment.attrs.merchant_defined_data = {'01': 'foo', '02': 'bar'}
+
 
 Dotpay
 ------
@@ -74,12 +103,12 @@ Dotpay
 
 Example::
 
-   # use defaults for channel and lang but lock available channels
-   PAYMENT_VARIANTS = {
-       'dotpay': ('payments.dotpay.DotpayProvider', {
-           'seller_id': '123',
-           'pin': '0000',
-           'lock': True})}
+      # use defaults for channel and lang but lock available channels
+      PAYMENT_VARIANTS = {
+          'dotpay': ('payments.dotpay.DotpayProvider', {
+              'seller_id': '123',
+              'pin': '0000',
+              'lock': True})}
 
 
 Google Wallet
@@ -95,12 +124,12 @@ Google Wallet
 
 Example::
 
-   # use sandbox
-   PAYMENT_VARIANTS = {
-       'wallet': ('payments.wallet.GoogleWalletProvider', {
-           'seller_id': '112233445566',
-           'seller_secret': '1234567890abcdef',
-           'library': 'https://sandbox.google.com/checkout/inapp/lib/buy.js'})}
+      # use sandbox
+      PAYMENT_VARIANTS = {
+          'wallet': ('payments.wallet.GoogleWalletProvider', {
+              'seller_id': '112233445566',
+              'seller_secret': '1234567890abcdef',
+              'library': 'https://sandbox.google.com/checkout/inapp/lib/buy.js'})}
 
 This backend requires js files that should be added to the template using ``{{ form.media }}`` e.g:
 
@@ -121,22 +150,25 @@ E.g: ``https://example.com/payments/process/wallet``
 PayPal
 ------
 
-.. class:: payments.paypal.PaypalProvider(client_id, secret[, endpoint='https://api.paypal.com'])
+.. class:: payments.paypal.PaypalProvider(client_id, secret[, endpoint='https://api.paypal.com', capture=True])
 
    This backend implements payments using `PayPal.com <https://www.paypal.com/>`_.
 
    :param client_id: Client ID assigned by PayPal or your email address
    :param secret: Secret assigned by PayPal
    :param endpoint: The API endpoint to use. To test using sandbox, use ``'https://api.sandbox.paypal.com'`` instead
+   :param capture: Whether to capture the payment automatically. See :ref:`capture-payments` for more details.
+
 
 Example::
 
-   # use sandbox
-   PAYMENT_VARIANTS = {
-       'paypal': ('payments.paypal.PaypalProvider', {
-           'client_id': 'user@example.com',
-           'secret': 'iseedeadpeople',
-           'endpoint': 'https://api.sandbox.paypal.com'})}
+      # use sandbox
+      PAYMENT_VARIANTS = {
+          'paypal': ('payments.paypal.PaypalProvider', {
+              'client_id': 'user@example.com',
+              'secret': 'iseedeadpeople',
+              'endpoint': 'https://api.sandbox.paypal.com',
+              'capture': False})}
 
 .. class:: payments.paypal.PaypalCardProvider(client_id, secret[, endpoint='https://api.paypal.com'])
 
@@ -146,10 +178,10 @@ Example::
 
 Example::
 
-   PAYMENT_VARIANTS = {
-       'paypal': ('payments.paypal.PaypalCardProvider', {
-           'client_id': 'user@example.com',
-           'secret': 'iseedeadpeople'})}
+      PAYMENT_VARIANTS = {
+          'paypal': ('payments.paypal.PaypalCardProvider', {
+              'client_id': 'user@example.com',
+              'secret': 'iseedeadpeople'})}
 
 
 Sage Pay
@@ -167,12 +199,12 @@ Sage Pay
 
 Example::
 
-   # use simulator
-   PAYMENT_VARIANTS = {
-       'sage': ('payments.sagepay.SagepayProvider', {
-           'vendor': 'example',
-           'encryption_key': '1234567890abcdef',
-           'endpoint': 'https://test.sagepay.com/Simulator/VSPFormGateway.asp'})}
+      # use simulator
+      PAYMENT_VARIANTS = {
+          'sage': ('payments.sagepay.SagepayProvider', {
+              'vendor': 'example',
+              'encryption_key': '1234567890abcdef',
+              'endpoint': 'https://test.sagepay.com/Simulator/VSPFormGateway.asp'})}
 
 
 Stripe
@@ -187,11 +219,11 @@ Stripe
 
 Example::
 
-   # use sandbox
-   PAYMENT_VARIANTS = {
-       'stripe': ('payments.stripe.StripeProvider', {
-           'secret_key': 'sk_test_123456',
-           'public_key': 'pk_test_123456'})}
+      # use sandbox
+      PAYMENT_VARIANTS = {
+          'stripe': ('payments.stripe.StripeProvider', {
+              'secret_key': 'sk_test_123456',
+              'public_key': 'pk_test_123456'})}
 
 This backend requires js files that should be added to the template using ``{{ form.media }}`` e.g:
 
diff --git a/doc/preauth.rst b/doc/preauth.rst
new file mode 100644
index 0000000..668ff38
--- /dev/null
+++ b/doc/preauth.rst
@@ -0,0 +1,43 @@
+.. _capture-payments:
+
+Authorization and capture
+=========================
+
+Some gateways offer a two-step payment method known as Authorization & Capture, which allows you to collect the payment manually after the buyer has authorized it. To enable this payment type, you have to set the ``capture`` parameter to ``False`` in the configuration of payment backend::
+
+      # settings.py
+      PAYMENT_VARIANTS = {
+          'default': ('payments.dummy.DummyProvider', {'capture': False})}
+
+
+Capturing the payment
+---------------------
+To capture the payment from the buyer, call the ``capture()`` method on the :class:`Payment` instance::
+
+      >>> from payments import get_payment_model
+      >>> Payment = get_payment_model()
+      >>> payment = Payment.objects.get()
+      >>> payment.capture()
+
+By default, the total amount will be captured. You can capture a lower amount, by providing the ``amount`` parameter::
+
+      >>> from decimal import Decimal
+      >>> payment.capture(amount=Decimal(10.0))
+
+.. note::
+
+  Only payments with the ``preauth`` status can be captured.
+
+
+Releasing the payment
+---------------------
+To release the payment to the buyer, call the ``release()`` method on your :class:`Payment` instance::
+
+      >>> from payments import get_payment_model
+      >>> Payment = get_payment_model()
+      >>> payment = Payment.objects.get()
+      >>> payment.release()
+
+.. note::
+
+  Only payments with the ``preauth`` status can be released.
\ No newline at end of file
diff --git a/doc/refund.rst b/doc/refund.rst
new file mode 100644
index 0000000..8591569
--- /dev/null
+++ b/doc/refund.rst
@@ -0,0 +1,18 @@
+Refunding a payment
+===================
+
+If you need to refund a payment, you can do this by calling the ``refund()`` method on your :class:`Payment` instance::
+
+      >>> from payments import get_payment_model
+      >>> Payment = get_payment_model()
+      >>> payment = Payment.objects.get()
+      >>> payment.refund()
+
+By default, the total amount would be refunded. You can perform a partial refund, by providing the ``amount`` parameter::
+
+      >>> from decimal import Decimal
+      >>> payment.refund(amount=Decimal(10.0))
+
+.. note::
+
+    Only payments with the ``confirmed`` status can be refunded.