updated the documentation
This commit is contained in:
parent
0427146bf4
commit
56838c90ef
105
README.markdown
105
README.markdown
|
@ -1,20 +1,50 @@
|
||||||
# Paypal Express
|
# Paypal Express for Spree
|
||||||
|
|
||||||
Bridge between ActiveMerchant's paypal express (PPX) gateway code and Spree
|
Bridge between ActiveMerchant's Paypal Express (henceforth PPX) gateway code and Spree
|
||||||
|
|
||||||
|
|
||||||
## Setup and Customization
|
## Setup and Customization
|
||||||
|
|
||||||
It's currently set up to run the UK version of the gateway, but this isn't an essential detail - should be easy to change.
|
|
||||||
|
|
||||||
1. Start by creating/identifying the relevant class representing your locale's paypal express gateway
|
1. Start by identifying the relevant class representing your locale's paypal express gateway
|
||||||
and change the +clazz+ in the migration and/or the database.
|
|
||||||
|
|
||||||
2. Modify +lib/spree/paypal_express.rb+ to load up details for your gateway
|
2. If there isn't one, then you can easily create one and patch it in. You can drop it in
|
||||||
|
the directory +lib/active_merchant/billing/gateways/+ in an extension - probably best in your
|
||||||
|
+site+ extension - and make sure it is loaded with the following line (suitably modified) in
|
||||||
|
your extension activation code :
|
||||||
|
|
||||||
|
require File.join(SiteExtension.root, "lib", "active_merchant", "billing", "gateways", "paypal_express_narnia.rb")
|
||||||
|
|
||||||
|
See how I've handled the UK gateway customization in this extension for more info.
|
||||||
|
|
||||||
|
3. Over-ride the hook +paypal_site_options+ in the OrdersController (eg with a +class_eval+ in your
|
||||||
|
+site+ extension's activation code) so that it returns a _hash_ with at least the following
|
||||||
|
fields. The hook is sent the current order value, in case it is needed.
|
||||||
|
|
||||||
|
* +:ppx_class+ -- name of the actual gateway class
|
||||||
|
* +:login+ -- the merchant's login email address
|
||||||
|
* +:password+ -- the merchant's Paypal API Credentials Password
|
||||||
|
* +:signature+ -- the merchant's Paypal API Credentials signature string
|
||||||
|
|
||||||
|
4. You can also over-ride other PPX settings from this hook, eg the +:description+ string
|
||||||
|
attached to transactions, or the colour scheme and logo, or ... (see +lib/spree/paypal_express.rb+
|
||||||
|
for more information.
|
||||||
|
|
||||||
|
5. Over-ride the hook +paypal_variant_tax+ to calculate the tax amount for a single unit of a
|
||||||
|
variant. The hook is passed the +price+ from the containing +line_item+, plus the variant
|
||||||
|
itself. Note that the line_item price and the variant price can diverge (the former won't be
|
||||||
|
changed if the administrator changes the variant price), and Spree usually ignores the
|
||||||
|
variant price after the line_item has been created, so you probably want to calculate tax
|
||||||
|
from the line_item price. You should return a floating point number here. The hook is
|
||||||
|
located in the OrdersController.
|
||||||
|
|
||||||
|
6. Over-ride the hook +paypal_shipping_and_handling_costs+ (also in the OrdersController), to
|
||||||
|
determine a shipping and handling estimate for the order. See below for a discussion of
|
||||||
|
shipping issues and how they affect PPX.
|
||||||
|
|
||||||
|
The hook is sent the order value, and must return a _hash_ containing (at least) a
|
||||||
|
:shipping and a :handling value (both floats), which are the total costs for the order.
|
||||||
|
|
||||||
You'll notice that I'm using Spree's gateway config mechanism. This choice is debatable: Spree is basically
|
|
||||||
set up for using one gateway at a time, whereas we probably want a main gateway plus Paypal as a backup
|
|
||||||
choice.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
@ -27,12 +57,12 @@ The payment representation isn't perfect: basically, Spree is oriented towards c
|
||||||
work is needed to generalise it to other options. For now, it is a bit hacked. (See the TODO list.)
|
work is needed to generalise it to other options. For now, it is a bit hacked. (See the TODO list.)
|
||||||
|
|
||||||
|
|
||||||
## Relationship with active merchant
|
## Relationship with Active Merchant
|
||||||
|
|
||||||
This ext contains three files which are updates or extensions to current active merchant code. They are
|
This extension contains three files which are updates or extensions to current active merchant code. They are
|
||||||
loaded up when the extension is initialized, and will over-ride the existing gem files. The modifications
|
loaded up when the extension is initialized, and will over-ride the existing gem files. The modifications
|
||||||
update the base protocol, eg allowing detailed order info to be passed, and supporting some of the new
|
update the base protocol, eg allowing detailed order info to be passed, and supporting _some_ (not all)
|
||||||
options in version 57.0.
|
of the new options in version 57.0.
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
|
@ -42,34 +72,55 @@ Pity it logs you off automatically after a relatively short time period
|
||||||
|
|
||||||
## Status and Known issues
|
## Status and Known issues
|
||||||
|
|
||||||
IMPORTANT: requires edge rails (it might work with 0.8.4)
|
IMPORTANT: requires spree version 0.8.5 or later (there's a tag in the repo for earlier versions, but it needs some bug patching now)
|
||||||
|
|
||||||
[06Jul09] I don't know of any serious bugs or issues at present in this code, so you should be able to
|
[15Jul09] I don't know of any serious bugs or issues at present in this code, so you should be able to
|
||||||
start using this without serious problems - but do note the TODO list below.
|
start using this without serious problems - but do note the TODO list below.
|
||||||
|
|
||||||
** Temporarily, I've had to over-ride two admin views: order/show and payments/index: this will be unpicked
|
Temporarily, I've had to over-ride two admin views: order/show and payments/index: this will be unpicked
|
||||||
once Spree is generalised to support payment types other than creditcards
|
once Spree is generalised to support payment types other than creditcards
|
||||||
|
|
||||||
WARNING: there seems to be an issue with the :shipping_discount issue which causes submitted order
|
WARNING: there seems to be an issue with the :shipping_discount issue which causes submitted order
|
||||||
info to be ignored (and not displayed) - see +lib/spree/paypal_express.rb+ for more info, so I suggest
|
info to be ignored (and not displayed - probably because the PPX addition checking doesn't tally).
|
||||||
avoiding this option unless you've tested it.
|
See +lib/spree/paypal_express.rb+ for more info. I suggest avoiding this option unless you've
|
||||||
|
tested it carefully. The insurance options are also not tested yet.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Hooks
|
||||||
|
|
||||||
|
These were discussed in the customization section above, but for reference, they are:
|
||||||
|
|
||||||
|
* +paypal_variant_tax(sale_price, variant)+
|
||||||
|
* +paypal_site_opts(order)+
|
||||||
|
* +paypal_shipping_and_handling_costs(order)+
|
||||||
|
|
||||||
|
|
||||||
|
## Shipping Issues
|
||||||
|
|
||||||
|
It is important to note that Spree won't have selected a shipping method when the PPX process
|
||||||
|
is started. My sites only have a single shipping method, so I can get away with defaulting to
|
||||||
|
that method and using that for calculations. It also means that I've not written any code yet
|
||||||
|
for selecting from applicable methods etc etc.
|
||||||
|
|
||||||
|
Note that PPX allows you to capture up to 115% of the original authorized amount: this could
|
||||||
|
allow some flexibility in shipping choices, eg you could add a stage after return from PPX
|
||||||
|
which asks for a shipping choice and confirms the final amount to be captured.
|
||||||
|
|
||||||
|
It seems that PPX might have support for choosing a shipping method on its screens, but I
|
||||||
|
have not tried to use this yet.
|
||||||
|
|
||||||
## TODO
|
## TODO
|
||||||
|
|
||||||
0. Allow easy change of locale for gateway version
|
0. Add support for accepting PPX payment at the credit card stage (important)
|
||||||
|
|
||||||
1. Move gateway config to the preferences system, to avoid interference with main gateways?
|
1. Look at using PPX to assist in shipping method choices (or present user with a choice before
|
||||||
|
|
||||||
2. Add support for accepting PPX payment at the credit card stage (important)
|
|
||||||
|
|
||||||
3. Look at using PPX to assist in shipping method choices (or present user with a choice before
|
|
||||||
they jump to PPX interaction)
|
they jump to PPX interaction)
|
||||||
|
|
||||||
4. Improve payment tracking support in Spree (eg generalise beyond creditcard bias)
|
2. Improve payment tracking support in Spree (eg generalise beyond creditcard bias)
|
||||||
|
|
||||||
5. Add some tests
|
3. Add some tests
|
||||||
|
|
||||||
|
4. Get some of my code into active merchant
|
||||||
|
|
||||||
6. Get some of my code into active merchant
|
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue