Payment Modules
===============

Satchmo currently has support for several different payment modules.  This
document will discuss some of the particular configuration items to keep in
mind for each module.

There are 3 primary types of payment modules in Satchmo:
    
    1. Modules based on views not asking for credit card number on the merchant site:

        Google Checkout, PayPal, Sermepa.

    2. Modules that collect and process a card number:
        
        Authorize.net Cybersource.net, Sage Pay, TrustCommerce.

    3. Modules which are not typical payment gateways:
        
        Auto success, COD (cash on delivery), dummy, gift certificate, purchase order.

.. index:: Authorize.net

Authorize.net
-------------
The authorize.net module requires that you have a valid authorize.net account.
In order to get your transaction key and transaction login, go to the
`site <http://www.authorize.net/>`_ and complete the account registration process.
When you have completed it, you can fill in the appropriate fields in the
admin settings to enable this payment processor.

If you have a test account with authorize.net and you log in through
https://test.authorize.net/gateway/transact.dll, then you should use the default 
test URL.  If you do not have a test account you will get an Error 13 message 
unless you change the URL to https://secure.authorize.net/gateway/transact.dll.  
You will also need to login in to authorize.net and make sure your account has 
test mode turned on.

.. index:: TrustCommerce

TrustCommerce
-------------
TrustCommerce configuration is very similar to authorize.net.  You will need
to go to `TrustCommerce <http://www.trustcommerce.com/>`_ and get your account
setup.

One special note with TrustCommerce - you must have the tclink libraries installed.
You can get these from `here <http://www.trustcommerce.com/tclink.html>`_.

Once the library is installed, you can fill in your login and password information
in the admin config.

.. index:: CyberSource

CyberSource
-----------
CyberSource operates similarly to TrustCommerce and Authorize.net.  If you register
at the `CyberSource Site <http://www.cybersource.com/>`_ you will get all the
credentials you need to configure this module.

.. index:: Paypal

PayPal
------

Satchmo uses `Paypal's Instant Payment Notification <https://www.paypal.com/ipn>`_ service. The notes below describe how to configure
it for your setup.

Configuration
^^^^^^^^^^^^^

.. data:: PAYMENT_PAYPAL.BUSINESS

   The email address for your paypal account.

.. data:: PAYMENT_PAYPAL.BUSINESS_TEST

   The email address for testing your paypal account.

.. data:: PAYMENT_PAYPAL.CURRENCY_CODE

   Currency code for Paypal transactions.

   Defaults to USD.

.. data:: PAYMENT_PAYPAL.LIVE

   Whether to accept real payments.

   Defaults to False.

.. data:: PAYMENT_PAYPAL.POST_URL

   The Paypal URL for real transaction posting.

   Defaults to `https://www.paypal.com/cgi-bin/webscr`.

.. data:: PAYMENT_PAYPAL.RETURN_ADDRESS

   Where Paypal will return the customer after the purchase is complete. This
   can be a named url and defaults to 'satchmo_checkout-success'.

.. data:: PAYMENT_PAYPAL.POST_TEST_URL

   The Paypal URL for test transaction posting.

   Defaults to `https://www.sandbox.paypal.com/cgi-bin/webscr`.

.. data:: PAYMENT_PAYPAL.URL_BASE

   Defaults to `^paypal/`.

Step by Step Instructions for Configuring Paypal IPN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following steps describe how to configure Paypal IPN for production use.

    1.  Make sure that 'payment.modules.paypal' is listed in your INSTALLED_APPS tuple, within your settings.py file.

Then go into your /admin settings and ensure the configuration is correct for yuour site:
    
    2. In Site Settings -> Payment Settings, Check "Accept real payments".
    3. In Site Settings -> Paypal Payment Settings, enter your Merchant Paypal account email 
    4. In Site Settings -> Paypal Payment Settings verify that POST URL is: https://www.paypal.com/cgi-bin/webscr 
    5. If you want paypal to adjust your stock levels, make sure your Track inventory levels is checked                       

Now, configure your Paypal Merchant Account through the Paypal website:
    
    6. In History select IPN History 
    7. Select the enable IPN option
    8. Use the correct Notification URL. For example: http://www.mydomain.com/checkout/paypal/ipn/

Double check your Satchmo sites domain name to make sure it matches the notification url above:
    9. Go to /admin/sites/site/ and make sure your domain name is the same as the one you configured about in PayPal. In the example above, under Sites put in mydomain.com

There is one note to remember about using paypal with utf-8 characters. By default Paypal will send an IPN call encoded as cp-1252 which 
will break when the payment module calls PayPal again in utf-8 and there are special characters in the call. The solution is to login to 
PayPal and change the website encoding of your account on PayPal to utf-8 in your profile settings (bottom right link on the profile page).

.. index:: Google Checkout

Google Checkout
---------------
There are a couple of different ways to integrate with Google Checkout. Satchmo
uses the XML option. When configuring your checkout account via Google, select:
"Option A - Configure your form to submit directly to Google Checkout."

It is recommended that you review the `Google checkout documentation
<http://code.google.com/apis/checkout/developer/Google_Checkout_XML_API.html#create_checkout_cart>`_
in order to understand how the process works.

.. index:: Protx, Sage Pay

Sage Pay (Formerly Protx)
-------------------------
This processor is included in the default Satchmo store.

.. index:: Sermepa

Sermepa
-------
This processor is included in the default Satchmo store. 

