modules/ec_linkpoint/NOTES.txt

// $Id: ec_linkpoint.module
/*
 *   20081110
 *   A lot of comments left in for developing, final
 *   may want to remove comments, or have a commented
 *   file and then file with comments removed for module file
 *
 *   A module used for Linkpoint API payment gateway 
 *   with Drupal e-commerce, not ubercart
 *   
 *   This derivation done by Paul Pruett, ec_linkpoint@cocoavillage.com
 *   because, well I needed a linkpoint api for myself ;).
 *   If someone wants to run with this module full time, or help, let me know!
 *
 *   Much of the code derived from the cvs respository
 *   for the linkpoint api for e-commerce with drupal 4.*
 *   http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/ecommerce/contrib/linkpoint_api/
 *   some of the code is similar and was compared to the
 *   ecommerce/contrig/authorize_net/authorizen_net.module
 *   AND also the apparent derivation from similar source 
 *   used by ubercart, see http://www.ubercart.org/contrib/903
 *   Elvis McNeely in gratitude for comparison. 
 *   (http://www.lafayetteweb.com | ubercart@mcneelycorp.com
 *   who wrote something for e-commerce then adapted to ubercart
 *   http://groups.drupal.org/node/4600
 *   Also I want to mention 'aliensun' post  http://drupal.org/node/142150
 *   which was also available to compare.
 *
 ********************************************************************
 * OTHER NOTES:
 *
 * ACHTUNG!  The codes expects that the website supports SSL, https
 * and if your website does not allow redirect to https, or is not
 * forced to be https it may fail in a way not explaining. SO be sure
 * to setup webserver so same address with either http or https works!
 *
 * This is a credit card processing interface using the Linkpoint API payment
 * gateway. It requires php to support CURL and SSL.
 *
 * Configuration:
 * From Linkpoint, you get a Store ID, and a certificate (.pem) file.
 * Upload the .pem file to your web server, preferrably NOT under the
 * public_html/www directory.
 *
 * Enter your Store ID, and the location of the .pem file. You can
 * use relative path names. For example, if you uploaded the file to
 * your home directory (the one above your public_html directory), then
 * you can use "../12345.pem"
 * 
 * Note: providing full path recommended - relative path might not work
 * on some systems resulting the following error:
 * "unable to use client certificate (no key found or wrong pass phrase?)"
 *
 ********************************************************************
*/

// NOTE, we prefixed alot with ec_linkpoint_ instead of linkpoint_api
// because we are making a separate module to install/uninstall
// but dependent on e-commerce module.
//
// also we will use path admin/ecsettings in our drupal menus for admin settings
//


/********************************************************************
 * E-commerce Hooks
 ********************************************************************/

// here is something different than ubercart, the newer e-commerce core has
// hooks for payment interface, like hook_paymentapi
// for the hook_paymentapi we need to return:
// &$txn  The transaction object for an order. This keeps growing in data from screen to screen.
// $op    What kind of action is being performed. 
// see: http://drupalecommerce.org/api/function/hook_paymentapi/53
//
// BTW, we could set form variables so that the return could be custom, but for
// now we will leave it 'Pay with credit card'
//
// notes for $op parameters 
// "display name" 
//   The name of the method displayed to customers.
//   This is purely for display purposes and my be descriptive.
// "on checkout" 
//   Called after the customer selects their payment method. 
//   This can be used for any specific validation the payment method needs to impose. 
//   Be sure to call form_set_error() to raise a warning to the system.
// "form" 
//   Called durring the checkout process. This is used to display options 
//   to the user for choosing between payment options. Nothing wil be displayed 
//   if only one payment option exists.
// "update/insert"
//   Called after the user has submitted the payment page so any additional 
//   payment details can be stored in the database.
// "payment page"
//   Display the form for accepting credit card information or redirect to a 
//   third party payment processor.
// "delete" 
//   Called when the transaction is being deleted 
//


// fyi, another hook that ubercart does not use but we need, 
// because e-commerce gateways payment modules
/*
* Implementation of hook_ec_transactionapi().
*
* http://drupalecommerce.org/api/function/hook_ec_transactionapi/53
*
*   Handle store transaction actions.
*
* &$txn 
*   A transaction object, passed by reference.
*
* $op 
*   A string containing the name of the ec_transactionapi operation. Possible values:
*
* "insert"
*   A new transaction is being created. Called by e.g. store_transaction_save(), with 
*   $txn an object containing edit fields Standard records in ec_transaction etc. have 
*   already been inserted. No return value.
* "load"
*   A transaction is being loaded from the database. Called by e.g. store_transaction_load(),
*   with $txn containing the transaction loaded so far.
* "update"
*   A transaction is being updated. Called by e.g. store_transaction_save(), with $txn 
*   an object containing edit fields Standard records in ec_transaction etc. have already
*   been updated. No return value.
* "delete"
*   A transaction is being deleted. The parameter $txn contains all the transaction 
*   information, since the standard records in ec_transaction etc. have already been 
*   deleted. No return value.
* "validate"
*   Transaction $txn is being inserted. Argument $a3 contains the section to validate. 
*   Errors should be set with form_set_error(). No return value. Called by e.g. 
*   store_transaction_validate(), from e.g. 
*   Menu: ?q=admin/store with $_POST['op'] == [ t('Update transaction') or t('Create new transaction')
*   ] on submission of a form to create a new transaction or update an existing transaction. 
*
* $a3 Additional argument, depending on $op.
*
* For "validate", this is the section to validate, in upper case. Possible values include:
*    o 'OVERVIEW':
*    o 'ADDRESSES':
*    o 'ITEMS':
*    o 'ALL' (default): Validate all sections. 
* 
*/ 


// misc stuff notes, not used so far...

// don't think we need to use hook_checkoutapi ?
//
//  we maybe could benefit? maybe not? authorize.net does not use it...
//
// see http://drupalecommerce.org/api/function/hook_checkoutapi/53
/*   hook_checkoutapi we did not use....yet.
* Manipulate the checkout process, including injecting form pages.
*
* Checkoutapi can be implemented by any module. It can be used to insert a 
* page into into the checkout process and even validate/save the form data. 
* Another feature of the API is the ability to push data onto the final 
* review page before final checkout. Note that the order of the form pages 
* is controlled via http://example.com/index.php?q=admin/store/checkout Parameters
*
*&$txn The transaction object for an order. This keeps growing in data from screen to screen.
*
* $op What kind of action is being performed. Possible values:
* "form": Inject a form page into the checkout process. Don't forget to add a submit button.
* "save": The injected form page has been submitted. Save your data in this hook. 
*   IMPORTANT: $txn->screen must be incremented here in order to go to the next screen! $txn->screen++;
* "validate": The customer has just finished editing the form page and is trying to submit it.
*   This hook can be used to check or even modify the transaction object. 
*   Errors should be set with form_set_error().
* "review": The last page of the checkout process is being viewed before the order is placed.
* "review_validate": validation for review page. Called within the form validate hook so has same requirements.
* "review_save": save section of the review page. Called within the form submit hook and has same requirements.
*
*/


// thoughts.... probably should have a check somewhere to make sure php supports curl, think ubercard does?


/*
*
* some linkpoint response field notes 
*
* r_avs 	The Address Verification System (AVS) response for this transaction. The first character indicates whether the contents of the addrnum tag match the address number on file for the billing address. The second character indicates whether the billing zip code matches the billing records. The third character is the raw AVS response from the card-issuing bank. The last character indicates whether the cvmvalue was correct and may be .M. for Match, .N. for No Match, or .Z. if the match could not determined. See the sections entitled Using Address Verification and Using the Card Code for additional information on using this information to help you combat fraud.
*
* r_ordernum 	The order number associated with this transaction.
*
* r_error 	Any error message associated with this transaction.
*
* r_approved 	The result of the transaction, which may be APPROVED, DECLINED, or FRAUD.
*
* r_code 	The approval code for this transaction.
*
* r_message 	Any message returned by the processor; e.g., .CALL VOICE CENTER..
*
* r_time 	The time and date of the transaction server response.
*
* r_ref 	The reference number returned by the credit card processor.
*
* r_tdate 	A server time-date stamp for this transaction. Used to uniquely identify a specific transaction where one order number may apply to several individual transactions. See the Transaction Details Data Fields section for further information and an example of tdate.
*
* r_tax 	The calculated tax for the order, when the ordertype is calctax.
*
* r_shipping 	The calculated shipping charges for the order, when the ordertype is calcshipping.
*
* r_score 	If LinkShieldTM is enabled on the account, the LinkShield fraud risk score will be returned in this field. A value of 0 indicates a low risk of fraud; a value of 99 indicates a high risk of fraud.
*
*/
1	// $Id: ec_linkpoint.module
2	/*
3	* 20081110
4	* A lot of comments left in for developing, final
5	* may want to remove comments, or have a commented
6	* file and then file with comments removed for module file
7	*
8	* A module used for Linkpoint API payment gateway
9	* with Drupal e-commerce, not ubercart
10	*
11	* This derivation done by Paul Pruett, ec_linkpoint@cocoavillage.com
12	* because, well I needed a linkpoint api for myself ;).
13	* If someone wants to run with this module full time, or help, let me know!
14	*
15	* Much of the code derived from the cvs respository
16	* for the linkpoint api for e-commerce with drupal 4.*
17	* http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/ecommerce/contrib/linkpoint_api/
18	* some of the code is similar and was compared to the
19	* ecommerce/contrig/authorize_net/authorizen_net.module
20	* AND also the apparent derivation from similar source
21	* used by ubercart, see http://www.ubercart.org/contrib/903
22	* Elvis McNeely in gratitude for comparison.
23	* (http://www.lafayetteweb.com \| ubercart@mcneelycorp.com
24	* who wrote something for e-commerce then adapted to ubercart
25	* http://groups.drupal.org/node/4600
26	* Also I want to mention 'aliensun' post http://drupal.org/node/142150
27	* which was also available to compare.
28	*
29	********************************************************************
30	* OTHER NOTES:
31	*
32	* ACHTUNG! The codes expects that the website supports SSL, https
33	* and if your website does not allow redirect to https, or is not
34	* forced to be https it may fail in a way not explaining. SO be sure
35	* to setup webserver so same address with either http or https works!
36	*
37	* This is a credit card processing interface using the Linkpoint API payment
38	* gateway. It requires php to support CURL and SSL.
39	*
40	* Configuration:
41	* From Linkpoint, you get a Store ID, and a certificate (.pem) file.
42	* Upload the .pem file to your web server, preferrably NOT under the
43	* public_html/www directory.
44	*
45	* Enter your Store ID, and the location of the .pem file. You can
46	* use relative path names. For example, if you uploaded the file to
47	* your home directory (the one above your public_html directory), then
48	* you can use "../12345.pem"
49	*
50	* Note: providing full path recommended - relative path might not work
51	* on some systems resulting the following error:
52	* "unable to use client certificate (no key found or wrong pass phrase?)"
53	*
54	********************************************************************
55	*/
56
57	// NOTE, we prefixed alot with ec_linkpoint_ instead of linkpoint_api
58	// because we are making a separate module to install/uninstall
59	// but dependent on e-commerce module.
60	//
61	// also we will use path admin/ecsettings in our drupal menus for admin settings
62	//
63
64
65
66	/********************************************************************
67	* E-commerce Hooks
68	********************************************************************/
69
70	// here is something different than ubercart, the newer e-commerce core has
71	// hooks for payment interface, like hook_paymentapi
72	// for the hook_paymentapi we need to return:
73	// &$txn The transaction object for an order. This keeps growing in data from screen to screen.
74	// $op What kind of action is being performed.
75	// see: http://drupalecommerce.org/api/function/hook_paymentapi/53
76	//
77	// BTW, we could set form variables so that the return could be custom, but for
78	// now we will leave it 'Pay with credit card'
79	//
80	// notes for $op parameters
81	// "display name"
82	// The name of the method displayed to customers.
83	// This is purely for display purposes and my be descriptive.
84	// "on checkout"
85	// Called after the customer selects their payment method.
86	// This can be used for any specific validation the payment method needs to impose.
87	// Be sure to call form_set_error() to raise a warning to the system.
88	// "form"
89	// Called durring the checkout process. This is used to display options
90	// to the user for choosing between payment options. Nothing wil be displayed
91	// if only one payment option exists.
92	// "update/insert"
93	// Called after the user has submitted the payment page so any additional
94	// payment details can be stored in the database.
95	// "payment page"
96	// Display the form for accepting credit card information or redirect to a
97	// third party payment processor.
98	// "delete"
99	// Called when the transaction is being deleted
100	//
101
102
103	// fyi, another hook that ubercart does not use but we need,
104	// because e-commerce gateways payment modules
105	/*
106	* Implementation of hook_ec_transactionapi().
107	*
108	* http://drupalecommerce.org/api/function/hook_ec_transactionapi/53
109	*
110	* Handle store transaction actions.
111	*
112	* &$txn
113	* A transaction object, passed by reference.
114	*
115	* $op
116	* A string containing the name of the ec_transactionapi operation. Possible values:
117	*
118	* "insert"
119	* A new transaction is being created. Called by e.g. store_transaction_save(), with
120	* $txn an object containing edit fields Standard records in ec_transaction etc. have
121	* already been inserted. No return value.
122	* "load"
123	* A transaction is being loaded from the database. Called by e.g. store_transaction_load(),
124	* with $txn containing the transaction loaded so far.
125	* "update"
126	* A transaction is being updated. Called by e.g. store_transaction_save(), with $txn
127	* an object containing edit fields Standard records in ec_transaction etc. have already
128	* been updated. No return value.
129	* "delete"
130	* A transaction is being deleted. The parameter $txn contains all the transaction
131	* information, since the standard records in ec_transaction etc. have already been
132	* deleted. No return value.
133	* "validate"
134	* Transaction $txn is being inserted. Argument $a3 contains the section to validate.
135	* Errors should be set with form_set_error(). No return value. Called by e.g.
136	* store_transaction_validate(), from e.g.
137	* Menu: ?q=admin/store with $_POST['op'] == [ t('Update transaction') or t('Create new transaction')
138	* ] on submission of a form to create a new transaction or update an existing transaction.
139	*
140	* $a3 Additional argument, depending on $op.
141	*
142	* For "validate", this is the section to validate, in upper case. Possible values include:
143	* o 'OVERVIEW':
144	* o 'ADDRESSES':
145	* o 'ITEMS':
146	* o 'ALL' (default): Validate all sections.
147	*
148	*/
149
150
151
152
153
154
155
156	// misc stuff notes, not used so far...
157
158	// don't think we need to use hook_checkoutapi ?
159	//
160	// we maybe could benefit? maybe not? authorize.net does not use it...
161	//
162	// see http://drupalecommerce.org/api/function/hook_checkoutapi/53
163	/* hook_checkoutapi we did not use....yet.
164	* Manipulate the checkout process, including injecting form pages.
165	*
166	* Checkoutapi can be implemented by any module. It can be used to insert a
167	* page into into the checkout process and even validate/save the form data.
168	* Another feature of the API is the ability to push data onto the final
169	* review page before final checkout. Note that the order of the form pages
170	* is controlled via http://example.com/index.php?q=admin/store/checkout Parameters
171	*
172	*&$txn The transaction object for an order. This keeps growing in data from screen to screen.
173	*
174	* $op What kind of action is being performed. Possible values:
175	* "form": Inject a form page into the checkout process. Don't forget to add a submit button.
176	* "save": The injected form page has been submitted. Save your data in this hook.
177	* IMPORTANT: $txn->screen must be incremented here in order to go to the next screen! $txn->screen++;
178	* "validate": The customer has just finished editing the form page and is trying to submit it.
179	* This hook can be used to check or even modify the transaction object.
180	* Errors should be set with form_set_error().
181	* "review": The last page of the checkout process is being viewed before the order is placed.
182	* "review_validate": validation for review page. Called within the form validate hook so has same requirements.
183	* "review_save": save section of the review page. Called within the form submit hook and has same requirements.
184	*
185	*/
186
187
188
189	// thoughts.... probably should have a check somewhere to make sure php supports curl, think ubercard does?
190
191
192	/*
193	*
194	* some linkpoint response field notes
195	*
196	* r_avs The Address Verification System (AVS) response for this transaction. The first character indicates whether the contents of the addrnum tag match the address number on file for the billing address. The second character indicates whether the billing zip code matches the billing records. The third character is the raw AVS response from the card-issuing bank. The last character indicates whether the cvmvalue was correct and may be .M. for Match, .N. for No Match, or .Z. if the match could not determined. See the sections entitled Using Address Verification and Using the Card Code for additional information on using this information to help you combat fraud.
197	*
198	* r_ordernum The order number associated with this transaction.
199	*
200	* r_error Any error message associated with this transaction.
201	*
202	* r_approved The result of the transaction, which may be APPROVED, DECLINED, or FRAUD.
203	*
204	* r_code The approval code for this transaction.
205	*
206	* r_message Any message returned by the processor; e.g., .CALL VOICE CENTER..
207	*
208	* r_time The time and date of the transaction server response.
209	*
210	* r_ref The reference number returned by the credit card processor.
211	*
212	* r_tdate A server time-date stamp for this transaction. Used to uniquely identify a specific transaction where one order number may apply to several individual transactions. See the Transaction Details Data Fields section for further information and an example of tdate.
213	*
214	* r_tax The calculated tax for the order, when the ordertype is calctax.
215	*
216	* r_shipping The calculated shipping charges for the order, when the ordertype is calcshipping.
217	*
218	* r_score If LinkShieldTM is enabled on the account, the LinkShield fraud risk score will be returned in this field. A value of 0 indicates a low risk of fraud; a value of 99 indicates a high risk of fraud.
219	*
220	*/