osCommerceITalia

Codice: Seleziona tutto

Installing the PayPal IPN

If you already have a version of this PayPal IPN module installed, then
you will need to remove the IPN from your admin area first (by clicking
"remove") before following the steps below.

1. Copy the files in the directory structure set in the contribution
download file to your osCommerce installation directory inc. the
new /ext/ folder.
2. Make any changes you need to the language level files.
3. In catalogincludesfunctionsgeneral.php

Find the ENDING:
?>

Insert this BEFORE: // START DELETE TEMP PAYPAL IPN ORDER // This
is used in shopping_cart.php when a temporary order needs to be
deleted // after it was cancelled by customer on paypal site.
function tep_remove_order($order_id, $restock = false) { if
($restock == 'on') { $order_query = tep_db_query("select
products_id, products_quantity from " . TABLE_ORDERS_PRODUCTS . "
where orders_id = '" . (int)$order_id . "'"); while ($order =
tep_db_fetch_array($order_query)) { tep_db_query("update " .
TABLE_PRODUCTS . " set products_quantity = products_quantity + " .
$order['products_quantity'] . ", products_ordered =
products_ordered - " . $order['products_quantity'] . " where
products_id = '" . (int)$order['products_id'] . "'"); } }
tep_db_query("delete from " . TABLE_ORDERS . " where orders_id =
'" . (int)$order_id . "'"); tep_db_query("delete from " .
TABLE_ORDERS_PRODUCTS . " where orders_id = '" . (int)$order_id .
"'"); tep_db_query("delete from " .
TABLE_ORDERS_PRODUCTS_ATTRIBUTES . " where orders_id = '" .
(int)$order_id . "'"); tep_db_query("delete from " .
TABLE_ORDERS_STATUS_HISTORY . " where orders_id = '" .
(int)$order_id . "'"); tep_db_query("delete from " .
TABLE_ORDERS_TOTAL . " where orders_id = '" . (int)$order_id .
"'"); } // END DELETE TEMP PAYPAL IPN ORDER
4. In catalogshopping_cart.php

Find this:
$breadcrumb->add(NAVBAR_TITLE, tep_href_link(FILENAME_SHOPPING_CART));

Insert this AFTER: // START DELETE PAYPAL TEMP ORDER // Check to
see if customer has cancelled a paypal_ipn process if (
$HTTP_GET_VARS['ipn']== 'cancel_ipn' &&
tep_not_null($HTTP_GET_VARS['order']) ) { // Make sure that this
order is THIS customers' order // We don't want anybody to pass
order numbers to here and delete other people's orders!!!!
$delete_order_query = tep_db_query("SELECT customers_id FROM " .
TABLE_ORDERS . " WHERE `orders_id`='" .
(int)$HTTP_GET_VARS['order'] . "'"); $delete_order =
tep_db_fetch_array($delete_order_query); //echo "DEBUG -
delete_order=".$delete_order['customers_id']."<br />"; //echo
"DEBUG - customer id in session=".$customer_id."<br />"; if (
$delete_order['customers_id']==$customer_id ) { // Delete the
order //echo "DEBUG - about to delete order!!!<br />";
tep_remove_order($HTTP_GET_VARS['order'], ''); } } // END DELETE
PAYPAL TEMP ORDER
5. Go to the Administration Tool->Modules->Payment section at your
osCommerce Administration Tool.
6. Install the /PayPal IPN/ module and configure its parameters.
Note: The module is disabled by default so configuration can occur
during the operation of a live store.

back to top <#top>


Configuration Settings (Shop Admin)


Enable PayPal IPN Module

When enabled, the customer is allowed to choose the PayPal IPN payment
method at the checkout procedure.


Gateway Server

The server to use for transaction processing.

The /Testing/ server uses PayPals Sandbox server, and the /Live/ server
is used to process real transactions.

Please note that the Testing/Sandbox server is independent to the Live
server, and requires it's own seller user account. Accounts can be
created for free at https://developer.paypal.com.

Note: This is set to the Testing server by default.


E-Mail Address

The e-mail address of the business account setup at PayPal (the seller
e-mail address). The funds gathered from purchased orders paid through
the PayPal IPN module will be sent to this PayPal account.


Sort order of display

The order in which the PayPal IPN payment method should be shown on the
checkout payment page if more than one payment method is available.


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 Pay Pal account
settings. If a specific currency is selected (i.e. EUR, USD, ..) and the
customer has selected another currency during the checkout procedure,
the transaction will be forced to the currency defined by the store
administrator.


Payment Zone

If defined, the PayPal IPN payment method will only be available to
orders made within the defined zone.


Set Preparing Order Status

As soon as the checkout confirmation page is shown to the customer, the
contents of the shopping cart are prematurely stored in the orders table
with this defined order status.

If the customer decides to alter the content of their shopping cart
(different products, different shipping or billing address, or if the
currency has been changed), the order is deleted from the orders table
and is reinserted with the updated information.

This only occurs when the checkout confirmation page is shown to the
customer, so if the shopping cart has been modified, it will be out of
sync with the premature order in the database until the checkout
confirmation page is shown again.

If a premature order has been stored in the orders database table and
the customer does not make the payment transaction at PayPal, the order
will remain in the database until manually removed by the store
administrator. This can be done easily by selecting the "Set Preparing
Order Status" status on the status filter on the Administration
Tool->Customers->Orders page, to show the current existing orders made
prematurely.

Please take care when removing premature orders - make sure they are a
few days old.

Premature orders will have their order status set to the "Preparing
[PayPal IPN]" value but will not contain an entry in the order status
history database table until the customer has made the payment
transaction at PayPal and has returned back to the store to the checkout
process and checkout success pages. (This can be used to differentiate
between invalid and valid orders)


Set PayPal Acknowledged Order Status

This is the status the premature order is set to when an IPN
notification from PayPal has been received, and has returned the result
of VERIFIED.

Notifications with the result of INVALID will not make any modification
to the premature order.

VERIFIED orders will automatically have an order status history record
inserted containing the PayPal status values in the order comment. This
comment will not be sent to the customer via e-mail, but is visible to
the customer when they view their order online.


Set PayPal Completed Order Status

This is the status the premature order is set to when an IPN
notification from PayPal has been received, has returned the result of
VERIFIED and the PayPal payment status is returend as "completed".

Only orders where payment has been received successfully should show
with this order status, allowing you e.g. to use it for releasing
downloadable content.


Transaction Type

This allows you to define how the transactions should be processed at
PayPal - either with each product in the order being passed to PayPal
(Per Item), or without the products with just the order totals being
passed to PayPal (Aggregate).

The recommended setting is Aggregate. Per item can cause problems,
especially when used together with contributions such as CCGV(trad).


Move tax to total

Do you want to move the tax to the total amount? If true PayPal will
allways show the total amount including tax. Now working in both 'per
item' and 'aggregate' modes, so the choice is all yours.


Page Style

The page style to use which is defined in your PayPal Profile account.
PayPal allows you to define page styles from within your PayPal account
to display e.g. your logo during checkout. Leave blank for default style.


Debug E-Mail Address

All parameters to an Invalid order is sent to this e-mail address for
debugging/verification purposes.


cURL Proxy server

If curl transactions need to go through a proxy, type the address here
starting with http://. Otherwise, leave it blank. The current GoDaddy
proxy address is http://proxy.shr.secureserver.net:3128


Enable Encrypted Web Payments

When enabled, the order parameters will be encrypted to be sent to PayPal.

Note: This feature requires a working OpenSSL installation on your
server, with access rights to the "openssl" program file.

Note: The "openssl" program file is called via PHPs exec() function,
which the webserver needs to have access to.


Your Private Key

The location and filename of your private key to use for signing the
order data.


Your Public Certificate

The location and filename of your public certificate to use for signing
the order data.


PayPal's Public Certificate

The location and filename of the PayPal public key to use for encrypting
the order data.


Your PayPal Public Certificate ID

The public certificate ID that PayPal should use to decrypt the
encrypted order data.

Note: This is defined at your PayPal Encrypted Payment Settings Profile
page.


Working Directory

The working directory to create temporary files. (All created files are
automatically deleted when no longer needed)


OpenSSL Location

The location and filename of the OpenSSL "openssl" program file.

back to top <#top>


PayPal Payment Status - info in order comment

The information sent back by PayPal is included in the order comment in
brackets. The following replies are possible:

* Canceled-Reversal: A reversal has been canceled. For example, you
won a dispute with the customer, and the funds for the transaction
that was reversed have been returned to you.
* Completed: The payment has been completed, and the funds have been
added successfully to your account balance.
* Denied: You denied the payment. This happens only if the payment
was previously pending because of possible reasons described for
the PendingReason element.
* Expired: This authorization has expired and cannot be captured.
* Failed: The payment has failed. This happens only if the payment
was made from your customer's bank account.
* In-Progress: The transaction is in process of authorization and
capture.
* Partially-Refunded: The transaction has been partially refunded.
* Pending: The payment is pending. See pending_ re for more information.
* Processed: A payment has been accepted.
* Refunded: You refunded the payment.
* Reversed: A payment was reversed due to a chargeback or other type
of reversal. The funds have been removed from your account balance
and returned to the buyer. The reason for the reversal is
specified in the ReasonCode element.
* Voided: This authorization has been voided.

For more informatin and a full list of reasons please go to
https://www.paypal.com/IntegrationCenter/ic_ipn-pdt-variable-reference.html
and scroll down until you see "payment_ status".

Understanding the possible codes will help you to correctly identify the
information sent back by PayPal and stored in the order comment.

Codice: Seleziona tutto

If payments are being received at PayPal but the stock level/orders
status is not updated and confirmation emails are not sent, then IPN
(Instant Payment Notification) is not working.
Follow the check list below for trouble shooting:

* Make sure you have copied the *ext* folder to your server
under your catalog directory.
* Try to open catalog/ext/modules/payment/paypal_ipn/ipn.php in
internet browser
(*http://yourdomain.com/catalog/ext/modules/payment/paypal_ipn/ipn.php*
change the words marked in red corresponding to your store). A
blank page will show up if there is no problem accessing this
script. If you can't access this script (access denied or file
not found), nor can PayPal call back to it. Do not password
protect the ext folder, and make sure the access permission is
set to 644.
* If your server has register globals off and you need to turn
it on by using a custom php.ini file, you need to put that
php.ini under the ext folder as well. IPN won't work if
register globals turned off.
* Check if you have a shared/dedicated SSL, or your server has
cURL lib installed. IPN won't work if you don't have any of these.
* Check if your server requires cURL connections to route
through a proxy server. If this is the case, you need to setup
the cURL proxy address.
* If none of the tips above works, post your problem in detail
to the support thread
<http://forums.oscommerce.com/index.php?showtopic=179917>.
Please include the PHP version, cURL version, osCommerce
version and PayPal IPN version.


If orders are not returning data back from PayPal, then it is possible
that "Register Globals" is not set *On*. A /php.ini/ file must be
present in the catalog/ext/modules/payment/paypal_ipn folder.

* Create a file called php.ini and add this line to the top:
Register_Globals = On
* Save the file, place it in the
catalog/ext/modules/payment/paypal_ipn folder, and upload.
* Your data should now pass back to your site and update in your
database.


If email confirmations are sent with character anomalies and aren't
formatted properly, then you may need to add the nl2br() tag to your
tep_mail functions.

In catalog/ext/modules/payment/paypal_ipn/ipn.php

Find this: tep_mail($order->customer['name'],
$order->customer['email_address'], EMAIL_TEXT_SUBJECT,
$email_order, STORE_OWNER, STORE_OWNER_EMAIL_ADDRESS);

REPLACE with this: tep_mail($order->customer['name'],
$order->customer['email_address'], EMAIL_TEXT_SUBJECT,
nl2br($email_order), STORE_OWNER, STORE_OWNER_EMAIL_ADDRESS);

Find this: tep_mail('', SEND_EXTRA_ORDER_EMAILS_TO,
EMAIL_TEXT_SUBJECT, $email_order, STORE_OWNER,
STORE_OWNER_EMAIL_ADDRESS);

REPLACE with this: tep_mail('', SEND_EXTRA_ORDER_EMAILS_TO,
EMAIL_TEXT_SUBJECT, nl2br($email_order), STORE_OWNER,
STORE_OWNER_EMAIL_ADDRESS);


back to top <#top>


Support

Community support for this module is provided on the osCommerce forum:
http://forums.oscommerce.com/index.php?act=ST&f=7&t=179917

There's also a useful thread by AlexStudio about PayPal IPN, SSLs &
Encrypted Web Payments and Download Controller:
http://forums.oscommerce.com/index.php?showtopic=177853&st=0&p=730503.

Please do not PM or email myself (Terra) unless you are looking for paid
support via my osCom hosting & development company www.terranetwork.net
<http://www.terranetwork.net>.

back to top <#top>


Developer Notes


ipn.php

ipn.php handles the information returend by PayPal. Whenever the payment
status changes, ipn.php is accessed and the order updated. Since version
2.0 the ipn.php also handles stock updates and sending of order emails.
Please note that the ipn.php is accessed every time the status changes -
e.g. when an echeck clears or a payment is refunded.

As the ipn.php is outside the customer's session id, we don't have all
the arrays from checkout_process.php. What we have is:

* Variables generated by application_top.php
* $order array generated by the function query() in the order class.
The $order array in ipn.php DIFFERS from the $order array
available in checkout_process!. To check the array structure go to
the function query() in the order class /includes/classes/order.php.
* Any variables posted back by PayPal as $_POST.

To check what an array contains, you can send it as an email. Add the
following code to ipn.php e.g. around line 91 (and change the email
address to one of your own):
// DEBUG let's check the array
$order_email = print_r($_POST,true) . "nn" . EMAIL_SEPARATOR . "nn"
. print_r($_order,true);
mail('youremail@yourdomain.com', 'Debug Test Array', $order_email);
// DEBUG DEBUG DEBUG


paypal_ipn.php

paypal_ipn.php handles the pre-storing of the order and sending the
parameters to PayPal.


checkout_process.php

paypal_ipn.php bypases checkout_process by loading a redirect into the
before_process. No code in checkout_process.php after the
before_process() is used (around line 50).


Payment processes

osCommerce uses a number of functions in the checkout process to include
code from the payment module. The following list gives you the function
name and the page which contains it:

* checkout_payment: javascript_validation(); selection()
* checkout_confirmation: update_status(); pre-confirmation_check();
confirmation(); process_button()
* checkout_process: before_process(); after_process()

Codice: Seleziona tutto

If orders are not returning data back from PayPal, then it is possible
that "Register Globals" is not set *On*. A /php.ini/ file must be
present in the catalog/ext/modules/payment/paypal_ipn folder.

* Create a file called php.ini and add this line to the top:
Register_Globals = On
* Save the file, place it in the
catalog/ext/modules/payment/paypal_ipn folder, and upload.
* Your data should now pass back to your site and update in your
database.