FBDSC Payment
From FreeBert Wiki
|
Installation, Configuration & Customization |
Contents |
[edit] Adding, Editing & Customizing Payment Options
The shopping cart is designed to allow multiple payment options that a customer can choose from. The cart has two built-in payment methods and allows the integration of additional, 3rd-party payment processing services (such as PayPal, AlertPay, etc). The settings controlling payment options are found in /script root directory/inc/payment_mods/PaymentOptions.php.
[edit] Built in Payment Options
The cart comes equipped with two payment options that can be used or disabled, they are Money Orders, and Phone Orders.
[edit] Money Orders
The Money Order option allows customers to print off a printer-friendly page showing their customer account info (name & address) and their order contents & total. The print-off includes instructions to print off the page, purchase a money order and send it via mail to you. (Note: the Admin section has the ability to add transaction details to an order, which would then 'activate' the order as normal, sending invoice emails to you (the admin) and the customer - you would do this once you have received the money order from the customer.) The money order option can be activated or disabled. If disabled, it will not display as payment option to customers during checkout, nor will it be an option in the admin section when manually entering a transaction. If activated, there are certain settings you must set for it to work correctly. In the PaymentOptions.php file, look for the section with the title:
// Settings For Money Order
- $Arr_MoneyOrder['active'] Set = 0 to disable, = 1 to enable
If you set the money order active, you need to ensure that all the settings below are correct:
- $Arr_MoneyOrder['MakeOutTo'] Name You Want Money Order Made Out To - Should Match Your Bank Account
- $Arr_MoneyOrder['StreetAndNumber'] Address Number & Street Name
- $Arr_MoneyOrder['AptBox'] Box Number / Apt#
- $Arr_MoneyOrder['City'] City
- $Arr_MoneyOrder['State'] State / Province
- $Arr_MoneyOrder['Country'] Country
- $Arr_MoneyOrder['Zip'] Zip / Postal Code
- $Arr_MoneyOrder['MoneyOrderFee'] Extra fee for processing money order - set to 0(zero) for none
- $Arr_MoneyOrder['AdditionalInstructions']' Additional comments / instructions for customers to follow
[edit] Phone Orders
The Phone Order option allows customers to checkout with their order (which saves their order in the database), and then prompts them to call a phone number you specify so they can arrange payment over the phone with you (or your employees) directly. (Note: the Admin section has the ability to add transaction details to an order, which would then 'activate' the order as normal, sending invoice emails to you (the admin) and the customer). The phone order option can be activated or disabled. If disabled, it will not display as a payment option to customers during checkout, nor will it be an option in the admin section when manually entering a transaction. If activated, there are certain settings you must set for it to work correctly. In the PaymentOptions.php file, look for the section with the title:
// Settings For Phone Order
- $Arr_PhoneOrder['active'] Set = 0 to disable, = 1 to enable
- $Arr_PhoneOrder['SalesPhoneNumber'] The phone number you want customers to call in for phone orders
- $Arr_PhoneOrder['AdditionalInstructions'] Text with additional comments / instructions for customers regarding phone orders
[edit] Third-Party / Custom Payment Options
The shopping cart system is designed to integrate with as many various online payment solutions as possible. This is faciliated through the 'Custom Payment Options' settings. During checkout, customers will be displayed any custom payment options you have setup / defined. The cart comes with PayPal & AlertPay setup as example customer payment options (Note: to use either PayPal and or AlertPay as a payment option you will have to have an account with them). When a customer chooses a custom payment option, they will be redirected to that site's secure servers to process the transaction. The item / description for custom payment options will appear on the 3rd party site / service as 'Your Site Title' Invoice# 'current order's invoice num'.
In otherwords, if customers select PayPal as their payment option, they will be taken to PayPal's secure site where they will make payment for an item described above: the cart contents will not be uploaded, only the total amount. The cart contents are already stored in the database, and only the invoice number is needed to retrieve those values.
Most, if not all third party online payment services offer a post-transaction notification which we will call Instant Payment Notification. The idea is that after a successful online transation, the online service (i.e. PayPal) will send your server a notification that the payment is complete. A special page in the cart recieves that notification, checks its validity, and if valid will process the transaction by adding a transaction entry to the database, updating the order's orderstatus as Payment Received, and send an email to both the customer and admin with the order and transaction details.
Unfortuntily each payment service has its own Instant Payment Notification routine / requirements. Therefore you must have one specific IPN file for each custom payment option that you wish to receive Instant Payment Notification.
In summary, there are two things that need to be done to add a custom payment option (with Instant Payment Notification): setup the payment option in the PaymentOptions.php file AS WELL AS create an Instant Payment Notification file for that option.
[edit] Setup the payment option in the PaymentOptions.php file
In the PaymentOptions.php file, look for the section with the title:
// Custom Payment Options
Each 3rd party online service you wish to use must have a complete set options defined to work properly. The first part of the section deals with basic info about the service, including its title, its url and some text descriptions. The next section deals with sending the data to the online service. This is done via form post - the body of the form post is composed of 2 types of settings 'Special' fields and additional fields. 'Special fields' define fields for the post body by specifiying the fieldname, and then its 'special' type. For instance, alertpay requires the 'total' field to be named 'ap_amount'. The next section, additional fields, allows the inclusion of other, static or 'non-special' form fields required by the service. All the required info should be available from the online service provider, either via a support / help section or manual for posting order details and receiving Instant Payment Notifications
[edit] Create an Instant Payment Notification (IPN) file for that option
An Instant Payment Notification file is the actual file in the cart / on your site that will receive & process the notification from a given online service. Each online service defined in the custom payment options section must have a corresponding IPN file. All IPN files are located in: /script root directory/IPN/. Note: the IPN filename must match the IPN filename setting for payment option. (if the IPN filename does not match the setting, the IPN system will fail).
PayPalIPN.php & AlertPayIPN.php included in the cart (cart root diretory/IPN/) are both fully functional example IPN pages. (Infact the PayPal IPN page is a bit more complex than the standard IPN page needs to be (like AlertPays), as PayPal requires the script to communicate back with the PayPal server to confirm the contents & validity of their IPN post. To handle that an addtional function was created to handle the required PayPal postback security check.)
The idea is to 'capture' or copy to local variables the values sent from the 3rd party transaction provider to the IPN script, and then pass THOSE variables to the standard process transaction function used by all IPN (and admin manual transaction) routines. Each transaction provider employs different fieldnames to represent common fields (eg 'invoicenumber','invoice','orderid'), as well as employ different security measures (like PayPal's), making individual IPN files for each custom payment option a necessary step to properly capture & validate IPN data before passing it to the standard process transaction function.
To make a IPN for a different 3rd party transaction provider, first setup the variables defining that option in PaymentOptions.php (copy the AlertPay set, and alter and rename to suit the new provider) then copy the AlertPayIPN.php IPN file, rename (to match the title of the new option's ipn filename setting). In the newly renamed file, your real concern is to section which sets the following local variables with data from the post sent to the IPN from the provider:
// Assign Local Vars:
- $Order_ID // the invoice num the cart assigned to this order and passed to the transaction provider
- $Transaction_Provider // the name / id of this payment merchant (such as "AlertPay")
- $Transaction_Provider_ID // the payment merchant's own id for this transaction
- $Transaction_Amount // the total amount charged to the customer
(the total transaction amount, passed from the transaction provider) - $Transaction_Date = date('Y-m-d'); // Current Date, no need to change this
- $Transaction_Time = date('H:i:s'); // Current Time, no need to change this
Note: If you copied your new IPN file from the existing PayPal one and your transaction provider does not require a 'postback' to validate the IPN (as PayPal does), then you can delete the line:
$IPN_Results=validate_ipn();
as well as the function defition for validate_ipn() near the bottom of the file, and simply pass the posted IPN variables directly to the local variables, listed above.
|
Installation, Configuration & Customization |
