Many hours have been spent writing and supporting this module. If it helped you out (and is making you money),
donations are a great way of saying "Thanks!"
This Payment Module combined the PayPal SOAP API and IPN feature into one, designed for store owners who have a Premier or Business account at PayPal,
including following features:
Express Checkout API is an SOAP API provided by PayPal. By introducing this API, transactions no longer pass through user's internet browsers or agents.
All connections are established directly between your host and PayPal servers, there for a much higher security level is provided.
Payers must sign-up with PayPal. Customer without PayPal account must create one before paying. (required for PayPal Express Checkout API)
Pass through customers' personal info to PayPal so they don't need to fill-in account sign-up form at PayPal, all filled up automatically.
Review order payment in store (instead of PayPal site) before transaction, there for no need to create pre-mature order records in database.
Update order status immediately if the payment transaction result is completed, no need to wait for IPN responses.
Built in IPN feature for updating order status automatically once if pending payments (eCheck) are cleared, and payments refunded as well.
Capable of declining unverified PayPal accounts. (Optional - setup through admin)
Capable of complete dumping transaction/IPN detail in debug email, including sent out requests and recieved responses, and optional dumping email for
successful transactions as well. (This is for PayPal 3005 error without triggering debug emails)
Customers can select verified shipping address from PayPal file, and alter the shipping address set in checkout shipping page. (Express Checkout API
built-in feature - This makes seller protection fully eligible possible)
Showing per item details in both osCommerce and PayPal receipt, including tax, shipping, low order fee (shown as handling in PayPal receipt).
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
PayPal Express Checkout payment module first send out a token request when the Express Checkout Button hit or the customer reaches the
checkout confirmation page. The order total and the shipping address are included in this initial request. PayPal responds to this request with an unique
token string. This is done through SOAP API, directly between your host and PayPal's server, there for the customer has no chance to intercept the
transmission. This payment module picks up the token string, and sends the customer to PayPal along with this token string, for the customer to authorize this
payment request.
If the customer didn't have a PayPal account, he needs to sign-up one with address fields pre-populated (by the shipping address sent with the initial request).
The customer can choose an alternate address, which could possibly be a confirmed shipping address in the PayPal file of his account.
Then PayPal sends the customer back to your store with the token string, so this payment module can send the transaction request later with this token,
for PayPal to identify that the payment with this token has been autorized. No transaction has been made yet at this point.
This payment module will send a second request to PayPal to fetch the customer's address info selected at PayPal. If the customer didn't change the address,
the original address will be sent back. Then it alters the order with the new address if changed, and adds a new record in address book if the address doesn't exist.
Also if a different shipping address sent back, it sends the customer to checkout shipping page to update the shipping cost. Along with this payment module a new review payment page, the customer can review his order and make necessary changes if he wants to,
and then hit the PAY button right in your store.
At this point, the payment has been confirmed by the customer, it takes the customer to checkout process and sends out the transaction request,
with the updated order info if the customer changed anything. If the response from PayPal is a successful transaction result,
it logs the order in database and update the order status with the payment result, Completed or Pending.
The built-in IPN (Instant Payment Notification) feature will update the order status automatically when the payment status have been updated,
eg. from Pending to Completed, or failed...etc.
Follow these instructions carefully or you might leave old values in your database!
Go into your administrative section -> Modules -> Payment and copy down all of the settings for this module.
Click on "Remove" and uninstall this module.
Modify updated files list below.
Notice: Upgrading from earlier versions not listed here, please do file comparing manually to upgrade.
Go into your administrative section -> Modules -> Payment and install the "PayPal Direct Payment" module updating the settings with what you wrote
down in step 1. And then refer to the configuration section for the new setting options.
Enable PayPal Express Checkout IPN Module?
This option defaults to False, which allows you to install it in a live store. You must switch it to True to enable this payment module.
Live or Sandbox API:
This option defaults to use Sandbox for testing. The "Sandbox" is for testing your store setup. You'll need to create an account at http://developer.paypal.com
and download a sandbox certificate to use this function.
"Live" is for when you're ready for live transactions. Note that the certificate for live and sandbox transactions are different!
Utilize Express Checkout Button?
This option defaults to Yes. The Express Checkout Button is required to be shown in the first step of checkout process, and it should not be displayed with
other payment method. If you want to be eligible for the Express Checkout Promotion, you must set this option to Yes. If set to no, the button will not be shown.
If set this to Yes, the first page shown in the checkout steps will be a checkout flow selection page with only 2 buttons. One for the Express Checkout Button
flow and the other for normal checkout flow.
Skip Confirmation Page?
This option defaults to No. Set this to Yes if you want to skip the 'first' confirmation page. Customers might get confused with the checkout confirmation and
the review payment page which looked almost the same, and they might skip the PAY button because they thought the order has already been confirmed.
Accept Verified Accounts Only?
This option enables you to decline customers without a verified PayPal account.
Allow Edit Shipping Address at PayPal?
This option defaults to Yes, to allow customers to select an address from existing PayPal file. If set to No, customers cannot edit shipping address at PayPal,
and PayPal will also reject invalid address on the initial request.
The better chance for payments to be eligible for PayPal's Seller Protection is to allow customers to select address from file, which can possibly be a
confirmed address. Recommended: Yes.
Note: For a payment to be eligible for the Seller Protection, the shipping address needs to be confirmed.
Require Confirmed Shipping Address?
This option defaults to Yes. If the shipping address is unconfirmed, it could be rejected at PayPal page. Set this to No if you ship world wide.
Addresses from most countries are unconfirmed.
Skip Shipping Address?
This option defaults to No. PayPal doesn't allow shipping to a different country other than the payer's country registered. Set this to yes if you want to accept
shipping to different countries, no shipping address will be sent to PayPal.
Notice: Skipping shipping address will make all your payments not eligible for
the seller protection.
API Username/API password:
Fill in your PayPal API access username and password here. This is NOT the same as your paypal login username/password.
API Certificate:
The ABSOLUTE path to your API certificate downloaded from PayPal API access page.
Payment Zone:
Defaults to NONE. If a zone is selected, only enable this payment module for that zone.
Transaction Currency:
The currency for PayPal to use for the transaction. Selected Currency allows multiple currencies to be accepted, where the customer chosen currency is
used for the transaction. If you use this option then you must have enabled acceptance of those currencies in your PayPal account settings. If a specific
currency is selected (i.e. only EUR, only USD, ...) and the customer has selected another currency during the checkout procedure, the
transaction will be forced to the currency defined in this setting.
Set Cancelled Order Status:
Pending payments like eChecks could be failed by customers at PayPal. Set this order status for IPN to update cancelled orders, and keep them from mixing up
with other Pending orders. Cancelled orders are still in database, and you need to delete them manually, to restore the stock quantity.
Set Completed Order Status:
Once the transaction response with a completed result received, this payment module will log the order in databse with this order status. Pending results
(eCheck) will set order status to 1, which is Pending by default osCommerce setup.
Note: If the transaction failed with no reponse, there will not be any order recorded in database. Usually those failed transactions are not paid,
however this scenario has not been tested thoroughly. If your customers complained about their failed transactions, you need to check your PayPal account
to see if the payment exist.
Page Style
Defaults to PayPal. If you have setup a customized PayPal Payment Page Style in your account profile, you can set it here.
Debug E-Mail Address
If you want to receive debug emails, fill in your email address here. DO NOT set this to a false email which you have in Sandbox. This email address must be
a real one.
Send Every Transaction Dumping Email?
Enable this option ONLY if you want to receive EVERY transaction's dumping in email. Sometimes PayPal threw error messages like 3005 error without
triggering Debug Emails. Enable this option will send every transaction dumping including successful ones. (For advanced user only)
Proxy Address
If cURL transactions need to go through a proxy, type the address here. Otherwise, leave it blank. Users of GoDaddy hosting services will need to fill this
in, which is currently the address: http://64.202.165.130:3128
Sort order of display
MUST set to 1. PayPal requires to display this payment module as the first choice in the list.
Some of the settings can easily get confused. In order to prevent potential problems, please follow the instructions below:
Sales Tax/ Shipping Calculations
Do not set anything in these 2 items. Although the settings here should be overridden,
but there are some issues related to these 2 settings.
Payment Receiving Preferences
Block payments sent to me in a currency I do not hold:
If you set this to yes, will block payments in currencies you don't hold.
Instant Payment Notification Preferences
Overridden, settings here have no effect.
Website Payment Certificates
This payment module uses SOAP API, you need to obtain the API certificate from API Access page, not here.
The information sent back by PayPal IPN is showing in the order comment. For example:
Date Added
Customer Notified
Status
Comments
01/11/2007 08:59:38
X
Pending
PayPal IPN Verified
[Completed (PayPal account:Verified; USD 169.79)]
Toatl amount did not match Address status: unconfirmed
The first line in comments means this update came from a verified IPN response. Sometimes it could be PayPal IPN Invalid, which means you received an INVALID
notification, it should be treated as suspicious and be investigated.
The second line Completed means that the payment has been completed. If the payment status is pending, a reason will be followed. It could be other
status in this place, showing the latest payment status updated at PayPal. PayPal account:Verified means that the payer's PayPal account is verified.
And then the currency of this payment, followed by the total amount at the end.
The 3rd line means that there is a problem with this IPN reponse, which the total amount doesn't match the order record in database. With this total amount
discrepancy found in the IPN response, this payment module set the order status to Pending automatically, and sent out an email to notify store owner that
there is a problem with this order and it needs some attention.
The last line means that the shipping address is not a confirmed address, which made this payment not eligible for PayPal's Seller Protection. Intangible orders
will not have address status shown here.
Notice: PayPal does not allow adding taxes to shipping/handling. Either include taxes in the shipping/handling(Low Order Fee) cost, or just don't add
taxes to them. Otherwise there will be some warnings in the transaction reponses, and the PayPal receipt will not show detail items up. However, the transaction
can still be made successfully.
Notice: If the shipping address selected at PayPal page was not in the customer's address book, a new record will be created. However, PayPal only
sends back a full name along with the shipping address rather than firstname lastname. if there are more than 2 words in the name, there is no way to decide
which part is firstname or lastname. So it simply grabs the first word as firstname, and the rest as lastname.
Notice: When set Allow Edit Shipping Address at PayPal to Yes, if an invalid shipping address sent to PayPal, PayPal will not reject it.
Instead, the shipping address will be replaced with one in the customer's file. No warning shown at PayPal page to notify the customer that the shipping address
been changed. However, an error message will be shown in checkout shipping page (ec_shipping.php) when the customer returns, notifying that the shipping address
has been changed at PayPal.
Notice: If you want to only enable this payment module on certain conditions (minimum order amount, shipping weight/cost etc.) you can add those in
function update_status(). However, the Express Checkout Button bypasses shipping calculations and there for ignors the shipping conditions. If you need the
shipping conditions to decide to enable EC IPN module or not, you need to disable the Express Checkout Button, so EC IPN can pick up the shipping condition
checkings.
Warning: Pending order status will allow customers to download their intangibale items. This is the original behavior of osCommerce, not a bug in this
payment module. If you are selling downloadable goods, Super Download Shop
contribution is recommended to secure the download access for pending payments.
Please run the diagnostics script to find out possible installation mistakes first.
Q: The disgnostics.php page never loaded in IE7, and FireFox gives this error:
Firefox has detected that the server is redirecting the request for this address in a way that will never complete.
A: When checking the request type (http or https), your host server responds an unrecognizable value. Please refer to
this thread for a possible solution, and
modify the diagnostics.php to handle the response from your host.
Q: When I try to checkout, I always get this error: An error occured when we tried to establish a connection to PayPal's servers.
A: Either your API username or password are wrong or your certificate is FUBAR'd
Q: When I try to checkout, it gives me the error: PayPal Express Checkout IPN module installation incomplete! There should be XML files located in
/var/www/vhosts/website.com/httpdocs/includes/ec_xml/ !
A: You didn't upload all of the files or put the ec_xml directory in the wrong place. It should be in your store's includes folder.
Q: The ec_shipping.php/express_checkout.php comes up blank!
A: If you implemented a template page design, you need to check the html source code to see if anything is broken when loading the page. These 2 files
are just a modified copy of stock checkout_shipping.php/checkout_confirmation.php.
THIS IS RELEASED WITH NO WARRANTY WHATSOEVER!
Use at your own risk!!
Before Adding This Contribution To Your Online Shop, You Should Back Up All Files Related To This Contribution and your database as well.