Contributions

Adaptação para o Brasil do módulo PAYPAL IPN v2.3.4.7 para recebimento em Real
by CybernetFX - www.cybernetfx.com

Para abrir uma conta com o PayPal: https://www.paypal.com/br/mrb/pal=PXQY7VC6D6VVE

Fóruns de suporte: www.forumdowebmaster.com.br
www.forums.oscommerce.com

Créditos aos autores originais e colaboradores.

Agradecimentos a todos que colaboram voluntária e gratuitamente com a comunidade osCommerce no Brasil, contribuindo para seu crescimento.


.........................................................


PAYPAL IPN v2.3.4.7 adapted and translated for use in Brasil by CybernetFX - www.cybernetfx.com

To register with PayPal: https://www.paypal.com/br/mrb/pal=PXQY7VC6D6VVE

Support forums: www.forumdowebmaster.com.br
www.forums.oscommerce.com

Credit to original authors and contributors.

Thanks to all who contribute voluntarily and for free with the Brazilian osCommerce comunity helping its growth.

(1) OPTION 1

The following update is to address issues whereby any purchase made with Paypal IPN on stock with attributes using QTpro, was not getting updated once the purchase was finailised. QT Doctor alarm was being triggered and manual intervention was required to fix stock levels.

### Replacement files with QTPro v4.51b contribution installed ###

(2) OPTION 2

This option not only has the above ammendment (1) but also includes a fix for discount coupons where the discounted shipping rate was not being passed to paypal. Only use this option if you also have Discount Coupon Codes 3.32 contribution installed.

### Replacement files with both QTPro v4.51b and Discount Coupon Codes 3.32 contributions installed ###

Do not use the contributions changed by Aplein, these are messy and wrong!

The file
catalogextmodulespaymentpaypal_ipnipn.php
is missing!

The file
catalogextmodulespaymentpaypal_ipnpaypal_ipn.php
does not belong there!

The file
catalogincludesmodulespaymentpaypal_ipnpaypal_ipn.php
is a terrible mess, no formatting, pieces of code occur twice..

This has cost me a lot of time trouble and money.
Eveline

Konnte die Version noch nicht ganz Überarbeiten, bei mir läuft diese jedoch ohne Probleme. Paypal_IPN 3.0
------------------------------------------------------

osCommerce 2.2 MS2 PayPal IPN Payment Module v2.3.4.7


Original Authors: Harald Ponce de Leon, Mark Evans osCommerce
Team Members <http://www.oscommerce.com/about/team>


Updates by olsonsp4c, PandA.nl, Navyhost, Zoeticlight, David,
gravyface, windfjf, Monika in Germany, AlexStudio and Terra


v2.3.4.7 updated by AlexStudio and the osC community


For v2.3.4.7 to work properly, there must not be any Shipping
Calculations set in the Paypal account profile <#shipping_cals>. Click
to read more detail.


*This contribution and the documents are released under the GNU General
Public License, which means it's free but WITH NO WARRANTY WHATSOEVER!
Read THROUGH this install guide first if you encountered any problem. We
can't help you if you don't even bother to read this guide.*


PayPal: http://www.paypal.com

osCommerce: http://www.oscommerce.com

Support Thread: http://forums.oscommerce.com/index.php?showtopic=179917
<Please search in the support thread if you have any problem with this
contribution.>

TerraNetwork: http://www.terranetwork.net


Contents

* What's new in v2.3.4.7 <#news>
* Requirements <#req>
* Introduction <#intro> - please read
* Known Issues <#known> - some health warnings
* How it works <#how> - background info
* Installation <#install>
* Configuration Settings <#conf> - your shop admin settings
* PayPal Payment Status <#status> - info in order comment
* PayPal Account Settings <#paypal> - your PayPal account
* Encrypted Web Payments <#encrypted> - set up instructions
* Integrating IPN with other Contributions <#contrib> - important!
* FAQs <#faq> - Frequently Asked Questions
* Troubleshooting <#trouble>
* Support <#support>
* Developer Notes <#developer>


What's New in v2.3.4.7

* The 1st goal of v2.3.4.7 update is to fix the tax and shipping
calculation bugs in both *'Per Item'* and *'Aggregate'* modes. The
2nd goal is to fix ipn.php to work with most hosting servers.
* A new parameter *'charset'* added to paypal_ipn.php so store
owners can adjust (hardcoded) the character set if necessary. To
change the character set in the button code, find in
catalog/includes/modules/payment/paypal_ipn.php around line 495:
$parameters['charset'] = "utf-8"; // Modify this line if you have
problems with the character set.
* In v2.3.4.7 the shipping tax is now displayed as an item if 'Per
Item' mode selected.

back to top <#top>


Requirements

To use this contribution, you need these things (ask your web host if
you don't know):

* osCommerce 2.2 MS2
* PHP 4.0.2+
* cURL or a shared/dedicated SSL certificate.
* A Premier or Business account with PayPal.

back to top <#top>


Introduction

osCommerce shops require the customer to return from the PayPal site to
the shop for order details to be recorded, order emails to be generated
and stock quantities to be updated.

In the past shop administrators had problems, where a customer did not
return to the site. Shop administrators received a payment notification
from PayPal but no order details. The PayPal IPN Module addresses this
problem by storing orders prematurely (before payment) in the database
with the "Preparing [PayPal IPN]" setting and as soon as a customer pays
the order status is automatically updated to the chosen setting (usually
"Pending").

This means that even when a customer fails to return to the site, the
shop administrator will have a record of the order details even when no
order emails are generated. Any remaining orders with status "Preparing
[PayPal IPN]" have to be carefully checked and can fall into the
following scenarios:


1) Orders in progress

Recent orders with the status "Preparing [PayPal IPN]" can show an order
in progress, e.g. by a customer making amendments to his order or going
through checkout. *Action*: None - recently generated orders should be
left as they are.


2) Abandoned (unpaid) orders

If a customer chooses to abandon ordering, i.e. not continuing with
payment, then a record of the premature (unpaid) order will be stored
with the setting "Preparing [PayPal IPN]". *Action*: Delete - orders
over 48 hours old with no payment can be deleted (option to restock must
be unticked as "Preparing [PayPal IPN]" orders are not yet deducted from
stock).

back to top <#top>


Known issues

* If the IPN reply from PayPal fails, then no order emails are sent,
no stock is updated and the order status is not updated. Check the
Troubleshooting <#trouble> section to fix the problem.
* If a customer does not return to the site, their shopping basket
is not emptied.
* Merging the PayPal IPN with other contributions usually requires
PHP coding skills - please read the advice below <#contrib>.
* Duplicate order IDs - If you have more than one shop linked to
your PayPal account, then you should set your PayPal profile not
to check for duplicate orders.
* If the PayPal fails to appear as payment option in checkout check
whether the PayPal IPN has a unique sort order from your other
payment modules. Modules with the same sort order can over-ride
each other.

back to top <#top>


How it works

The PayPal IPN module stores orders prematurely in the database to be
processed by PayPal IPN notifications. This takes care of customers not
returning back to the store to store the order in the database, and
allows processing to occur when the PayPal IPN notification is received.

When communicating with the IPN notification, the order information is
sent back to PayPal in a secure manner through PHP native OpenSSL
capabilities or through cURL when OpenSSL is not available, or through a
normal unsecure manner when no secure communication means exists, to
confirm the order made. If the result is successful, the order status is
updated automatically to show a successful order has been made. Invalid
orders are left alone for the store administrator to verify.

This module also has OpenSSL public/private key encryption capabilities
to securely send the order information to PayPal during the checkout
procedure. More information about this feature can be read here:

Encrypted Web Payments:
https://www.paypal.com/us/cgi-bin/webscr?cmd=p/xcl/rec/ewp-intro-outside

This module was built to be as simple as possible without having the
need to touch core files for installation and usage.

back to top <#top>


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.


Example

An order status which looks like this:
11/06/2006 12:49:50 False Pending PayPal IPN Invalid [Pending; address]
11/06/2006 13:20:49 True Processing
11/06/2006 13:24:30 False Pending PayPal IPN Verified [Completed
(Unverified; $49.50)]
means that the payment was pending because "The payment is pending
because your customer did not include a confirmed shipping address and
your Payment Receiving Preferences is set to allow you to manually
accept or deny each of these payments". Once the payment was acceped,
the order status was updated to "Completed" by PayPal.

back to top <#top>


PayPal Account Configuration


Shipping Calculations

In order to send shipping/handling cost correctly to Paypal, you should
not setup any Shipping Calculations in PayPal account Profile.
Inactivating the settings will not work!! You must leave the Shipping
Calculations blank!!


AutoReturn

You do NOT need to enable Auto Return in your PayPal account as this
information is sent automatically by the IPN module.

If you do wish to activate it, then the return path is the pathway to
the checkout_process.php file. Sample pathways are:

* for sites with full SSL: https://yourdomain.com/checkout_process.php
* for sites with shared SSL:
https://yourserver.xssl.net/yourdomain.com/checkout_proccess.php

Note: Only enable AutoReturn if you have only shop linked to your PayPal
account!


IPN

You do NOT need to enable the IPN in your PayPal account as all the
required information is sent by the module.

If you do wish to activate it, then the notify URL is the pathway to the
/ext/modules/payment/paypal_ipn/ipn.php file.


Duplicate order problem

The PayPal IPN sends a parameter "invoice" to PayPal. This parameter is
equal to the order ID (1,2,3,4 etc). However, PayPal requires the
invoice parameter to be unique so if you have already sent an order ID
with the same number, then it will be refused. Sending the same order ID
can e.g. happen if you have two osCom shops linked to one PayPal account
- the PayPal account cannot distinguish between different shops /
domains / databases, it just looks at the number and says "hey, that's
already been paid!"

To disable the multiple order id checking to to your PayPal account - >
"Profile" - > "Payment Receiving Preferences". In there you will have
the option:

Block accidental payments:
You may prevent accidental payments by blocking duplicate invoice IDs
Yes, block multiple payments per invoice ID
No, allow multiple payments per invoice ID
Select "No".

PayPal will now allow all orders to be paid, even if the order ID has
already been paid previously. A potential problem is if customers pay an
invoice twice by mistake (e.g. refreshing browser, hitting button twice
etc.).

back to top <#top>


Setting up Encrypted Web Payments

If you have SSL enabled, then you won't need to set up encrypted web
payments as the payment module automatically uses SSL if available.

To set up yor encrypted web payments, log in to your PayPal account,
click on "Profile - > Encrypted Payment Settings". Click on "Download"
to download PayPal?s public certificate. Create your own certificate and
upload it to PayPal.

To create your own certificate, you can use openssl:
Create a private key: openssl genrsa -out my-prvkey.pem 1024
Create the public certificate: openssl req -new -key my-prvkey.pem -x509
-days 365 -out my-pubcert.pem

When you upload your certificate, PayPal returns to you a "PayPal Public
Certificate ID?=". This is one of the parameters that osC requires.

More info on this can be found at
https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf
- If you have problems with encryped web payments I strongly recommend
reading the relevant chapter in the PDF guide as it gives extensive
guidance!

You can optionally block all non-encrypted payments: go to Profile >
Website Payment Preferences, and choose ?on? in ?Block Non-encrypted
Website Payment?

back to top <#top>


Integrating with other Contributions

Note: Rule of thumb - whenever you make ANY change to
checkout_process.php you MUST manually merge the change into
paypal_ipn.php and ipn.php

The PayPal IPN works different from other payment modules and bypasses
the checkout_process file. Which means that any contribution which
modifies the checkout_process.php file will require some manual coding
TLC in paypal_ipn.php and ipn.php.

From version 1.3 of this module, the PayPal IPN Payment Module is
compatible with the Register Globals Patch v1.4 - you do not need to
make any modifications for this.

Version 2.0 introduces a new code base so any fixes posted for versions
1.x probably won't work without modification.

back to top <#top>


Frequently Asked Questions

I have no SSL and don't want to set up Encrypted Web Payments. Are
paypal ok with me sending data unprotected?
Yes, in the Order Integration Guide (PDF)
<https://www.paypal.com/en_US/pdf/PP_OrderManagement_IntegrationGuide.pdf>
PayPal states that "Because credit card and bank information is not
transmitted in Instant Payment Notification (IPN), PayPal does not
require Secure Sockets Layer (SSL) to encrypt IPN transmissions."
But note that there is a hack where customers can change the order
value of unencryped payments, so make sure that the PayPal payment
and the order value match.
*Notice:* It seems that PayPal has changed their behavior since
September 2007, stores without SSL nor cURL lib installed started
receiving *PayPal Invalid Process emails*, orders status, best
sellers list and stock quantities stopped updating. If you don't
have SSL, cURL lib is required for IPN to work with.
When I click Continue on the CONFIRM page, I go to my Test Store just
fine, but the total shows $0. Any thoughts?
Check your currency - the 0 value usually occurs if your shop & your
PayPal account have different currency restrictions or if you use
the wrong abbreviation for the currency in your shop. Canada for
exmaple must be CAD (and not CAN). A complete list of supported
curency codes is here: Supported Currencies
<https://www.paypal.com/cgi-bin/webscr?cmd=p/sell/mc/mc_wa-outside>.
Page Style - The page style to use for the transaction procedure
(defined at your PayPal Profile page). Should I touch anything here?
Only if you want to, otherwise leave blank. This setting allows you
style the PayPal pages with your logo etc. Check your PayPal account
help section for more information.
Set PayPal Acknowledged Order Status - Set the status of orders made
with this payment module to this value - Which one? For now I have
defualt is that ok?
Yes, default is fine, otherwise choose any value you wish from the
drop-down. That's entirely your choice.
My orders sometimes say[Completed (Verified; $ and sometimes it says
[Completed (Unverified; $)]. What does this mean and how does a order
become verified?
Completed is means the money are already in your account, verified
or unverified means whether the customer has a verified or unverfied
paypal account.
I've got contribution ABC and now it doesn't work with the PayPal IPN!
This is a common complaint on the support thread. Please read the
notes regarding contribution integration in this guide. As
explained, the PayPal IPN bypasses checkout_process.php so any
modifications made to this file will need to be integreated into
paypal_ipn.php and ipn.php instead. This isn't a cookie cutter
exercise and a reasonable knowledge of PHP and MySQL are highly
desirable. Additional notes for developers are added at end of this
document.
The OsCommerce version I'm running doesn't have a EXT directory. Do I
need this ext directory? And what are the CHMOD instructions?
Yes, you need to create this directory - just upload the entire
/ext/ folder to your site to ensure that you have the correct
directory structure. CHMOD is 755 for folders, 644 for the file.

back to top <#top>


Troubleshooting

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()


PayPal Resources

Pre-populate form field variables
<https://www.paypal.com/cgi-bin/webscr?cmd=p/gen/pre-populate-your-signup-outside>

IPN Variables
<https://www.paypal.com/IntegrationCenter/ic_ipn-pdt-variable-reference.html>

Developer PDF documentation
<https://www.paypal.com/IntegrationCenter/ic_documentation.html>

back to top <#top>
---------------------------------------------------

kein Voll-Update.
Nur 2 Dateien zum Austauschen.
Benötigt wird paypal_ipn_3.0.1

not a full update.
Only 2 files to replace.
Needed is paypal_ipn_3.0.1

Bitte nehmt dieses Modul.

Unter Zusammenfassung muß für die Bearbeitungsgebühr noch "Paypal-Bearbeitungsgebühr" Installiert werden.

Bei Aktivierung Steuer Klasse (Tax Class) wird auf die Bearbeitungsgebühr noch die Steuer erhoben.

Hoffe das war alles.

Grüße
Alfred

Hallo,

bevor Ihr dieses modul Installiert, erstellt bitte ein Backup bestehender dateien und der Datenbank!!!

Ich übernehme keine Haftung oder Gewährleistung!!

1. Bestellung wird gelöscht wenn der Kunde die bestellung von der Paypal-Seite Abbricht und zum Shop zurückkehrt.
Sprich: Abbrechen und zurück zu XXYY-Shop.

2. Ihr könnt jetzt entweder einen Prozentsatz oder einen festen Betrag als Bearbeitungsgebühr Eintragen.
Dieser Betrag wird als Bearbeitungsgebühr Ausgewiesen und bei Paypal in die Versandkosten gepackt. Intern, bei der Paypal-Zahlung aber wieder als Bearbeitungsgebühr Ausgewiesen.
Ist der fest Betrag gefühlt und nicht Null, wird dieser genommen, andernfalls der prozentualle wert.

3. Korrigiert wurde die Warenkorb Anzeige bei Paypal (siehe Bild). Hier werden jetzt alle Artikel mit Artikelnummer und Name sowie Bruttopreis Angezeigt.

4. Die Steuern werden hier nicht Ausgewiesen.

5. In den Versandkosten ist die Bbearbeitungsgebühr eingeschlossen.

Sollte es Probleme geben, bitte im Forum über folgenden Beitrag Hinweisen.

http://forums.oscommerce.de/index.php?showtopic=68403

Grüße
Alfred

This is a quick-and-dirty fix to a bug that causes the user to be returned (after paying with PayPal IPN) to the shopping cart with items marked as unavailable rather than the checkout_success page.

This occurs if all of the following conditions are met:
1. Their order (or another order that took place in the meantime) causes any of the products to go out of stock.
2. Stock Checking is turned on.
3. An IPN has been received with payment_status == 'Complete' before the user returns to the store

It may happen in other conditions as well.


In catalog/checkout_process.php find the lines (approx line 56):


// Stock Check
$any_out_of_stock = false;
if (STOCK_CHECK == 'true') {


and change to:

// Stock Check
$any_out_of_stock = false;
if (STOCK_CHECK == 'true' && !tep_not_null($_GET['payment_status'])) {


This bypasses the stock check when the user has been sent to the checkout_process page by PayPal.

As I said, this is quick-and-dirty. Hopefully a cleaner fix can be rolled into the next release of the PayPal IPN contribution.

this fixes a bug where the temp "working" directory likes to delete itself on some servers.

goto paypal_ipn.php in /catalog/includes/modules/payment/

around line 542 find the 1st fopen for the working directory and add this BEFORE it:

if (!file_exists(MODULE_PAYMENT_PAYPAL_IPN_EWP_WORKING_DIRECTORY)) {
mkdir(MODULE_PAYMENT_PAYPAL_IPN_EWP_WORKING_DIRECTORY, 0755);
}


just a check to see if the temp working directory exists 1st, and if it doesnt then it creates it.



the attachment is a fake file. dont download it.

There is a bug if you use Price Sensitive Discount with PayPal IPN.
http://www.oscommerce.com/community/contributions,204

The final price not include discount.

To resolve this problem, you must made this modification.

Attached file shows how to add support for "Payment Type Surcharge". This surcharge is included on subtotal. "Payment Type Surcharge" must be configured to match settings with "PayPal IPN Module" (for example,show taxes and other things like that).

Hi, ich habe das mal etwas für Deutsche abgeändert.
man bekommt jetzt immer eine Mail, ob der Kunde über Paypal bezahlt oder nicht. Geht der Kunde von Paypal zurück zum Shop und wählt eine andere Zahlweise, gibt es eine neue Bestellung. In der Bestellung mit Paypal steht dann das nicht gezahlt wurde. Auch stellt das Contrib die Bestellung wieder auf Offen, wenn man eine Rückzahlung über Paypal macht.

Bei mir funktioniert das ohne Probleme.

Installation wie gehabt.
Alles in catalog Verzeichnis und dann im Admin Installieren. Fertig.

Minor changes detailed on the forum and a couple of minor instructions mistakes.

Scott

Since 2.3.4.x
--------------
Bug fix - added the order number not passed on bug to the fileset
Feature - added the delete order from database if order is cancelled and customer is returned to store
Updated readme "Installation" section and "Troubleshooting" section

Scott

This is a fix which updates the status always after receiving an IPN notification (for register_globals OFF or ON) .

For all versions :

Find in catalog/includes/modules/payment/paypal_ipn.php


tep_session_register('cart_PayPal_IPN_ID');
// Terra register globals fix
//$_SESSION['cart_PayPal_IPN_ID'] = $cartID . '-' . $insert_id;


Replace with

// FS start
$GLOBALS['cart_PayPal_IPN_ID'] = $cartID . '-' . $insert_id;
// FS stop
tep_session_register('cart_PayPal_IPN_ID');
// FS start
// Terra register globals fix
//$_SESSION['cart_PayPal_IPN_ID'] = $cartID . '-' . $insert_id;
// FS stop

The problem : $cart_PayPal_IPN_ID was not always a global (e.g. between functions confirmation and process_button.

Only this text included !

Il semblerait que j'ai envoyé précedemment un fichier qui ne se dézippe pas bien alors le revoila.

A l'intérieur de cette version juste quelques petits bugs de corrigés,
D'une part un problème d'encodage et de charset, d'autre part des caractères un peu bizarres
qui apparaissait en haut de la page admin des modules de paiement.
Un choix de devise en euro.

Fixes for Data not returning from Paypal and Email Confirmation all jumbled Up.

Our order was not returning data back from paypal due to the php.ini file not being present in the
catalog/ext/modules/payment/paypal_ipn folder with Register_Globals = On

Full Package Included.

For those like me searching for the reason why PayaPal does not deduct the discount coupon value, HERE IS THE ANSWER!

In the admin IPN the Transaction Type needs to be set to 'AGGREGATE', it will only work this way as I have found so far.

Bug fix - In v2.3.2 shipping tax would be added twice if set 'Display Prices with Tax' to true. Added configuration key 'Display Prices with Tax' checking to decide whether to add shipping tax as an item or not.

Bug fix - In v2.3.2 when item quantity larger than 1, extra shipping tax would be added at PayPal. Fixed by multiplying the item tax by quantity before checking the tax total.


**************************************
Full package. Upgrading from v2.3.2 just replace the core file in catalog/includes/modules/payment/paypal_ipn.php

Please report bugs/problems/issues to this support thread:
http://forums.oscommerce.com/index.php?showtopic=179917

Bug fix - Rewrote the amounts calculating code so that no matter what has been set with 'Display Prices with Tax', 'Display Tax' and 'Move tax to total amount' options, amounts are now correctly sent to PayPal in both 'Per Item' and 'Aggregate' modes.

Added parameter 'charset' in the button code so the character set can be defined.

Added Shipping tax displayed as an item if 'Per Item' mode selected. Now you can add tax to shipping cost and won't mess up the amounts displayed at PayPal.

*************************************************
Full Package
Support thread: http://forums.oscommerce.com/index.php?showtopic=179917

This is exact the same package as the previous one (the second v2.3.1), just correcting the version number listed.

Bug fix - Rewrote the amounts calculating code so that no matter what has been set with 'Display Prices with Tax', 'Display Tax' and 'Move tax to total amount' options, amounts are now correctly sent to PayPal in both 'Per Item' and 'Aggregate' modes.

Added parameter 'charset' in the button code so the character set can be defined.

Added Shipping tax displayed as an item if 'Per Item' mode selected. Now you can add tax to shipping cost and won't mess up the amounts displayed at PayPal.

*************************************************
Full Package
Support thread: http://forums.oscommerce.com/index.php?showtopic=179917

Bug fix - In v2.3 when "Display Prices with Tax" set to true under admin configurations, the handling amount become negative and causes the error message "PayPal system contains an incorrectly formatted packing value" issue. Fixed by adding a configuration key checking when calculating handling amount.

Bug fix - In v2.3 The shipping/handling amount could have discrepancies when 'Per Item' mode selected. Re-wrote the shipping/handling calculation so the amounts are now accurate.

Bug fix - If the order content type is 'virtual', the customer's billing address should be sent to PayPal instead of the delivery address.

Added post v2.2 multi-language support fix by Terra.

Added 'Per Item' mode supported when Encrypted Web Payments is enabled.


************************************
Full Package
Support thread: http://forums.oscommerce.com/index.php?showtopic=179917

Bug fix - Shipping/handling/tax not sent to Paypal or sent incorrectly in previous versions. Now it sends the correct shipping/handling no matter in 'per item' or 'aggregate' mode.
.
Bugs fix in ipn.php and now it should reduce the problems in previous version.
.
Add cURL proxy server setting option.
.
Bug fix - Force shipping setting removed. Now it always sends user selected shipping address to Paypal if the order content type is not 'virtual'.
.
================================
Full package, French file included

English:
This is the french translation of Paypal IPN v2.1 & v2.2's install guide and documentation.
You'll only find a Guide_installation_LISEZ_MOI.html file replacing the install_guide_READ_ME.html in english.

French:
Le fichier à télécharger est la traduction du guide d'installation et documentation de Paypal IPN v2.1 & v2.2.
Vous trouverez uniquement un fichier Guide_installation_LISEZ_MOI.html file remplaçant le fichier install_guide_READ_ME.html en anglais.

Hello,

First, many thanx to Harald Ponce de Leon, Mark Evans and PandA.nl, Navyhost, Zoeticlight, David, gravyface, AlexStudio, windfjf, Monika in Germany and of course Terra for this very complete contribution.

You will only find here the french file for PayPal IPN. This file is based on based on v2.2.

No more need to install downloads controller to assist us in the issue we all have with digital downloads and them being made accessable to users who don't complete the transactions.

this is a MUCH easier way to fix the problem @ hand.

Please view the zip for the instrucitons.

Version 2.2 Release

3rd order status included on request of AlexStudio to make it better compatible with Download Controller
You can now select an order status for orders where PayPal sends back a "completed" status (i.e. when money has been sucessfully received into your PayPal account). For all other others (e.g. pending echecks etc.) it uses the acknowledged order status.

Minor fix to "customer's paypal address included in comment field of order"
This now only shows if "force shipping" is set to True.

Bug fix in rounding error calc

Minor updates to documentation

Community Support thread:
http://forums.oscommerce.com/index.php?act=ST&f=7&t=179917

This is a full package
I'd recommend users of version 2.0 and 2.1 to upgrade

Version 2.1

Changes:
1. Update to "force shipping" -> customer's paypal address included in comment field of order
NB: the PayPal address is NOT necessarily the the osCom shipping address - please check user guide & screenshots fore more information
2. update to documentation -> NEW screenshots document added
3. Module now includes a footer which is included in emails. Footer text can be defined in language level file (MODULE_PAYMENT_PAYPAL_IPN_TEXT_EMAIL_FOOTER). Default is an empty line.
4. AlexStudio's rounding bug error fix has been incorporated with modifications
5. AstonK2120's variable naming fix has been applied (previously two variables had same name in ipn.php)
[ref: http://forums.oscommerce.com/index.php?s=&showtopic=179917&view=findpost&p=998771]
6. Fixed shipping bug in Aggregate mode where PayPal has it's own shipping set
[ref: http://forums.oscommerce.com/index.php?s=&showtopic=179917&view=findpost&p=999192]

Package includes the "empty cart" fix by Monika in Germay posted as update on 2 Jan 2007

Community Support thread:
http://forums.oscommerce.com/index.php?act=ST&f=7&t=179917

This is a full package

if you'd like to empty the cart in any case, even for those customers that do not return to your site, it can be done right after the extra order emails have been sent in the COMPLETED loop of Terra's new code

add this code
//begin emptying cart for everyone!
tep_db_query("delete from " . TABLE_CUSTOMERS_BASKET . " where customers_id = '" . $_POST['custom'] . "'");
tep_db_query("delete from " . TABLE_CUSTOMERS_BASKET_ATTRIBUTES . " where customers_id = '" . $_POST['custom'] . "'");
//end emptying cart for everyone


right above the line that says
} // END STATUS == COMPLETED LOOP
which is line 256 for me, so it looks like this:



// send emails to other people
if (SEND_EXTRA_ORDER_EMAILS_TO != '') {
tep_mail('', SEND_EXTRA_ORDER_EMAILS_TO, EMAIL_TEXT_SUBJECT, $email_order, STORE_OWNER, STORE_OWNER_EMAIL_ADDRESS);
}

//begin emptying cart for everyone!
tep_db_query("delete from " . TABLE_CUSTOMERS_BASKET . " where customers_id = '" . $_POST['custom'] . "'");
tep_db_query("delete from " . TABLE_CUSTOMERS_BASKET_ATTRIBUTES . " where customers_id = '" . $_POST['custom'] . "'");
//end emptying cart for everyone

} // END STATUS == COMPLETED LOOP


enjoy!

Version 2.0 contains different code to previous versions. If you have a customised checkout you will need to integrate this carefully! Code fixes published for versions 1.x probably don't work with version 2.x.

This release contains the following updates:

1. Order emails & Stock update moved into ipn.php
standard order email & stock update executed when payment status is "completed"
NEW! short notification email executed when payment status is "pending"
What this means: even if customer does not return to your shop, your stock will be updated and the order emails will be sent.

2. Expaned currency support for:
AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, JPY, NOK, NZD, PLN, SEK, SGD, USD
default US Dollars

3. Added locale support (language support) for US English, UK English, German, Japanese, and French (default US English)
changes in which language PayPal presents itself based on customer's country from their primary address

4. Added "force shipping address?" option to IPN
If force shipping address is set to to TRUE, then shipping address is transmitted to PayPal and order can be eligible for Seller Protection. However this setting currently has one remaining bug as customers without PayPal account will have to re-enter their address.
If force shipping is set to FALSE, then order is not eligible for Seller Protection but customers without PayPal account will have their address fields pre-populated.
IMPORTANT! To check whether the order is eligible for Seller Protection you must check the order info in your PayPal account!

5. Extensive updates to the documentation including a brand-new FAQ section

And the following bug fixes:

6. Address details changed to transmit DELIVERY address to PayPal

7. Stock update only executed if payment_status is "completed" (otherwise every status changed would trigger stock update)

8. Aggregate now only one sum (required to fix problem when IPN is used together with CCGV(trad) and the discount results in a negative sub-total)


Remaining issues:
-> shopping cart not emptied if customer does not return to shop
-> problem with pre-populating UK county field for customers without PayPal account
-> If force shipping == True, then customers without PayPal account will have to retype their address
-> The language files could do with translating
-> Integration help files need to be updated due to new code structure

Community Support thread:
http://forums.oscommerce.com/index.php?act=ST&f=7&t=179917

COMPLETE FILE PACKAGE
Released as version 2.0 due to the code changes to give greater differentiation to version 1.x code

History:
========
1.0 initial modifications
1.1 fixed state abbreviation support -- tested with Canadian provinces and U.S. states

ToDo:
========
Add international support for telephone numbers

Description:
============
This modification enables pre-populating of the PayPal "billing information" form with order/customer information.
(Saves the customer from having to enter it in twice.)

Requirements:
=============
PayPal IPN 1.4 module must be installed and enabled.

This snippet of code adds all the required PayPal "billing information" fields (except the "security code" and credit card information) to the IPN module.

Now when a customer chooses to pay with a credit/debit card on PayPal, the billing information values are pre-populated using order/customer data from osCommerce.

This is a complete file package.

update /include/modules/payment/paypal_ipn.php

fix missing Products Attributes

============

fix 3 bugs - PayPal IPN missing updated informaton

1. When user goes to checkout_confim page but goes back to edit his/her address or comments...etc, and doesn't update the shopping cart, the updated information will not be writen to order.

2. order comments will not be updated when user goes to PayPal and doesn't click "RETURN to merchant" button

3. order id growing each time when user updates shopping cart

fix 3 bugs - PayPal IPN missing updated informaton
(/include/modules/payment/paypal_ipn.php)
1. When user goes to checkout_confim page but goes back to edit his/her address or comments...etc, and doesn't update the shopping cart, the updated information will not be writen to order.

2. order comments will not be updated when user goes to PayPal and doesn't click "RETURN to merchant" button

3. order id growing each time when user updates shopping cart

This release makes the PayPal IPN module compatible with the Register Globals Patch v1.4 - it works for both patched & standard osCom shops!

In addition the following changes were made:
- currency support for AUD (Australian Dollar) added
- ability to name the "continue" button on PayPal Payment Complete page in language file
- user guide now includes information on PayPal account

And the file package now includes integration guides for:
- QTPro 4.25
- CCGV(trad)
- oscAffiliate

Rule of thumb for integrating with other contributions: whenever a contribution requires changes to checkout_process.php you probably also need to amend paypal_ipn.php.

Community Support thread:
http://forums.oscommerce.com/index.php?act=ST&f=7&t=179917

This is a complete file package.

Version 1.2 A complete set with bug fix

- this is a complete set of all files
- contains a bug fix for the missing attributes in order confirmation email problem.
- tax fix by navyhost has also been incorporated.

You must set the module to send in Aggregate mode and also set 'Move tax to total amount' to True for this module to work properly.

The amendment below by chiwawa has not been included as it changes the base funtionality of the module.

The support thread for this module can be found here:
http://forums.oscommerce.com/index.php?showtopic=179917

Background

This is an enhancement based on the osCommerce PayPal IPN Module v1.0 For 2.2MS2 (the one that contribute on 30 Nov 2004).

I added two additional filters to the IPN module, an order Maximum filter and a country filter. If the order amount is more than a pre-defined threshold, or the delivery country is not within a predefined country list, the Paypal_ipn module will be unavailable as a payment option.
The purpose of this contribution is to avoid accepting Paypal payment for customers from some high risk countries (in terms of credit card fraud), and set a ceiling on the order amount to accept PayPal payment.

Same file as navyhost 's.

I'm new to OSC and I followed his instructions to the T. Hence I never got it to work.

To get his fix to work, the module must be "Removed" and then "Installed."

Disabling and re-enabling it is not sufficient because the intall process modifies the database. So here are his instructions with my small change...

============ navyhost's ==========
The paypal ipn module leaves tax out of the total when sending to paypal.

This is fixed with the attached zip file.

In your admin, remove the Paypal IPN module.

Then , unzip the attached file, and overwrite your existing paypal_ipn.php file in the /catalog/includes/modules/payment directory.

In your admin, install the Paypal IPN module.

You must set the module to send in Aggregate mode and also set 'Move tax to total amount' to True.

The paypal ipn module leaves tax out of the total when sending to paypal.

This is fixed with the attached zip file.

In your admin, disable the Paypal IPN module.

Then , unzip the attached file, and overwrite your existing paypal_ipn.php file in the /catalog/includes/modules/payment directory.

You must set the module to send in Aggregate mode and also set 'Move tax to total amount' to True.

- Added support for php native openssl functions
- Added check to verify the order total before changing the order status
- Store the customers paypal account status as part of the order status
- Updated Description to show credit / debit cards are accepted

This module stores orders prematurely in the database to be processed by PayPal IPN notifications. This takes care of customers not returning back to the store to store the order in the database, and allows processing to occur when the PayPal IPN notification is received.

When communicating with the IPN notification, the order information is sent back to PayPal in a secure manner through PHP native OpenSSL capabilities or through cURL when OpenSSL is not available, or through a normal unsecure manner when no secure communication means exists, to confirm the order made. If the result is successful, the order status is updated automatically to show a successful order has been made. Invalid orders are left alone for the store administrator to verify.

This module also has OpenSSL public/private key encryption capabilities to securely send the order information to PayPal during the checkout procedure.

More information about this feature can be read here:

Encrypted Web Payments: https://www.paypal.com/us/cgi-bin/webscr?cmd=p/xcl/rec/ewp-intro-outside

This module was built to be as simple as possible without having the need to touch core codebase files or database changes for installation and usage.