updated the documentation
This commit is contained in:
paulcc
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
|
||||
|
||||
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
|
||||
and change the +clazz+ in the migration and/or the database.
|
||||
1. Start by identifying the relevant class representing your locale's paypal express gateway
|
||||
|
||||
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.)
|
||||
|
||||
|
||||
## 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
|
||||
update the base protocol, eg allowing detailed order info to be passed, and supporting some of the new
|
||||
options in version 57.0.
|
||||
update the base protocol, eg allowing detailed order info to be passed, and supporting _some_ (not all)
|
||||
of the new options in version 57.0.
|
||||
|
||||
## Testing
|
||||
|
||||
|
|
@ -42,34 +72,55 @@ Pity it logs you off automatically after a relatively short time period
|
|||
|
||||
## 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.
|
||||
|
||||
** 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
|
||||
|
||||
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
|
||||
avoiding this option unless you've tested it.
|
||||
info to be ignored (and not displayed - probably because the PPX addition checking doesn't tally).
|
||||
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
|
||||
|
||||
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?
|
||||
|
||||
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
|
||||
1. Look at using PPX to assist in shipping method choices (or present user with a choice before
|
||||
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