Support for PayPal(tm) Payments
*******************************

Ikoba generally supports paying things via PayPal. For this, we use
the REST-API provided by PayPal.

To make that work, you have to (1) obtain app credentials from PayPal
and (2) make that credentials known to ikoba.


Getting Credentials from PayPal
+++++++++++++++++++++++++++++++

1) Create a general PayPal account

   Browse https://www.paypal.com and create a new account. If you plan
   to provide services or goods payed via PayPal. you should of course
   create a business account. You can, however, start with a personal
   account as it is upgradeable at a later point in time.

   For only testing ikoba PayPal support, a personal account is
   sufficient.

2) Register as a developer at PayPal

   Go to https://developer.paypal.com and log in with the credentials
   obtained in step 1. This will create some fake users/merchants for
   you, which are *not* suitable for use with the PayPal REST API.

3) Create a REST-API compatible application

   After logging in on https://developer.paypal.com/ go to the
   dashboard and create a new app by clicking the respective button.

Afterwards, in the developer dashboard under "My apps" you can find
your new set of client IDs and secrets for both, sandbox and live use.


Setting PayPal Client ID, secret, etc.
++++++++++++++++++++++++++++++++++++++

To make the credentials known to Ikoba, put them into configuration
files like this::

  # paypal.conf

  [rest-client]
  id = <YOUR-VERY-OWN-PAYPAL-REST-CLIENT-ID>
  secret = <YOUR-VERY-OWN-PAYPAL-REST-CLIENT-SECRET>
  # valid values: sandbox, live
  mode = sandbox

Out of the box, we expect these files to be in the following _two_
locations:

  path/to/ikoba/install/etc/paypal.conf
  path/to/ikoba/install/etc/paypal-testing.conf

Obviously, the second file is used for (automated) testing.

.. note:: As these credentials are bound to
          persons/companies/organisations, we do not share them via
          version control.

For developers: The credentials given via ZCML and config files are
used on startup to initialize the PayPal SDK. Therefore, it should not
be neccessary to care for the credentials when creating Payment
objects after the Grok instance started.