X-Git-Url: http://git.freeside.biz/gitweb/?p=Business-OnlineThirdPartyPayment.git;a=blobdiff_plain;f=notes_for_module_writers;fp=notes_for_module_writers;h=91c1acb544d31d1a4bd3538160e522aa49627ac4;hp=57bd0980c2a343bd6c057c65d0fba55645643f1e;hb=977ae07ace47748c3abaf508a09c8e5488989ed7;hpb=49e48c25beb6448dd41e072eefca9474b6f60ea6

diff --git a/notes_for_module_writers b/notes_for_module_writers
index 57bd098..91c1acb 100644
--- a/notes_for_module_writers
+++ b/notes_for_module_writers
@@ -7,27 +7,47 @@ NOTE:
     You should read the notes in Business::OnlinePayment first.
 
 Create a subclass of Business::OnlineThirdPartyPayment called
-Business::OnlinePayment::(processor name).  You should override at least
-the set_defaults, submit, and reference methods.
-
-See Business::OnlineThirdPartyPayment::Interswitchng as an example.
-
-submit: 
-  This method functions with both a "Authorize Only" and "Post Authorization"
-action.  The former must, at a minumum, ensure that popup_url will return
-an appropriate value when submit also sets is_successful.
-
-  Nothing has happened at this point other than verifying the data is valid
-and providing the caller with a redirection url.
-
-  When called with "Post Authorization" steps are taken to verify that funds
-have been authorized by the processor.
-
-reference:
-  This method is called with a hash of key/value pairs, typically as the
-result of a HTTP GET or POST, but by whatever mechanism the processor provides.
-The return value must be the unique reference provided to the "Authorize Only"
-submit.  Since the usage consists of submit(action=>'Authorize Only'),
-reference(key=>value...), submit(action=>'Post Authorization'), this may be
-the appropriate time to set the state of the object for some processors.
+Business::OnlineThirdPartyPayment::(processor name).  You should override at
+least the set_defaults, create, and execute methods.
+
+See Business::OnlineThirdPartyPayment::PayPal as an example.
+
+create(%content):
+This method's primary functions are:
+- to determine/create the URL the purchaser must visit to make payment, and
+- to assign a token to the transaction.
+
+%content will always include 'amount' (the amount of the payment) and 
+'description' (a text description of the product being purchased).
+
+If the processor requires the merchant to initiate the transaction (e.g.
+PayPal), then create() should do that, and store the transaction ID assigned
+by the processor in 'token'.  Otherwise, create() can simply assign a 
+semi-random, unique string to 'token', and additionally pass it to the 
+processor as the order number or other identifier.
+
+The URL the purchaser needs to visit should be assigned to the 'redirect'
+property of the object.  If the processor expects to receive the transaction
+parameters from the purchaser's browser in the form of a POST request,
+create() can store them in a hashref in the 'post_params' property.
+
+execute(%params):
+This method's primary function is to determine whether the transaction
+was successful.  The 'token' property should already be set to whatever it 
+was after the initial create().  %params is everything passed back by the 
+processor to the callback URL.
+
+If the merchant is required to confirm or "capture" the payment after 
+authorization, execute() should do that.  (PayPal again.)  Other processors
+(see B:OTP:FCMB for an example) provide a separate API to query the 
+transaction status; execute() should do that.  In either case, it should
+set the 'is_success' property to 0 or 1, and set 'error_message' if the 
+payment failed, or 'order_number' and 'authorization' if it succeeded.
+
+set_defaults(%arguments):
+This is called from the constructor.  The build_subs() method of 
+Business::OnlinePayment is available for creating accessor methods.
+In general, modules should look for the merchant ID in 'username', any
+password or shared secret in 'password', and the callback URL in
+'return_url'.