OnlinePayment(3pm)					User Contributed Perl Documentation					OnlinePayment(3pm)

NAME

       Business::OnlinePayment - Perl extension for online payment processing

SYNOPSIS

	 use Business::OnlinePayment;

	 my $transaction = new Business::OnlinePayment($processor, %processor_info);
	 $transaction->content(
			       type	   => 'Visa',
			       amount	   => '49.95',
			       card_number => '1234123412341238',
			       expiration  => '0100',
			       name	   => 'John Q Doe',
			      );
	 $transaction->submit();

	 if($transaction->is_success()) {
	   print "Card processed successfully: ", $transaction->authorization(), "
";
	 } else {
	   print "Card was rejected: ", $transaction->error_message(), "
";
	 }

DESCRIPTION

       Business::OnlinePayment is a generic module for processing payments through online credit card processors, electronic cash systems, etc.

CONSTRUCTOR

   new($processor, %processor_options)
       Create a new Business::OnlinePayment object, $processor is required, and defines the online processor to use.  If necessary, processor
       options can be specified, currently supported options are 'Server', 'Port', and 'Path', which specify how to find the online processor
       (https://server:port/path), but individual processor modules should supply reasonable defaults for this information, override the defaults
       only if absolutely necessary (especially path), as the processor module was probably written with a specific target script in mind.

TRANSACTION SETUP METHODS

   content(%content)
       The information necessary for the transaction, this tends to vary a little depending on the processor, so we have chosen to use a system
       which defines specific fields in the frontend which get mapped to the correct fields in the backend.  The currently defined fields are:

       PROCESSOR FIELDS

       login
	   Your login name to use for authentication to the online processor.

       password
	   Your password to use for authentication to the online processor.

       REQUIRED TRANSACTION FIELDS

       type
	   Transaction type, supported types are: CC (credit card), ECHECK (electronic check) and LEC (phone bill billing).  Deprecated types are:
	   Visa, MasterCard, American Express, Discover, Check.  Not all processors support all transaction types.

       action
	   What action being taken by this transaction. Currently available are:

	   Normal Authorization
	   Authorization Only
	   Post Authorization
	   Void
	   Credit
	   Recurring Authorization
	   Modify Recurring Authorization
	   Cancel Recurring Authorization
       amount
	   The amount of the transaction.  No dollar signs or currency identifiers, just a whole or floating point number (i.e. 26, 26.1 or
	   26.13).

       OPTIONAL TRANSACTION FIELDS

       description
	   A description of the transaction (used by some processors to send information to the client, normally not a required field).

       invoice_number
	   An invoice number, for your use and not normally required, many processors require this field to be a numeric only field.

       po_number
	   Purchase order number (normally not required).

       tax Tax amount (portion of amount field, not added to it).

       freight
	   Freight amount (portion of amount field, not added to it).

       duty
	   Duty amount (portion of amount field, not added to it).

       tax_exempt
	   Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).

       currency
	   Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR, AUD, DKK, GBP, JPY, NZD, etc.

       CUSTOMER INFO FIELDS

       customer_id
	   A customer identifier, again not normally required.

       name
	   The customer's name, your processor may not require this.

       first_name
       last_name
	   The customer's first and last name as separate fields.

       company
	   The customer's company name, not normally required.

       address
	   The customer's address (your processor may not require this unless you are requiring AVS Verification).

       city
	   The customer's city (your processor may not require this unless you are requiring AVS Verification).

       state
	   The customer's state (your processor may not require this unless you are requiring AVS Verification).

       zip The customer's zip code (your processor may not require this unless you are requiring AVS Verification).

       country
	   Customer's country.

       ship_first_name
       ship_last_name
       ship_company
       ship_address
       ship_city
       ship_state
       ship_zip
       ship_country
	   These shipping address fields may be accepted by your processor.  Refer to the description for the corresponding non-ship field for
	   general information on each field.

       phone
	   Customer's phone number.

       fax Customer's fax number.

       email
	   Customer's email address.

       customer_ip
	   IP Address from which the transaction originated.

       CREDIT CARD FIELDS

       card_number
	   Credit card number.

       expiration
	   Credit card expiration.

       cvv2
	   CVV2 number (also called CVC2 or CID) is a three- or four-digit security code used to reduce credit card fraud.

       card_token
	   If supported by your gateway, you can pass a card_token instead of a card_number and expiration.

       track1
	   Track 1 on the magnetic stripe (Card present only)

       track2
	   Track 2 on the magnetic stripe (Card present only)

       recurring_billing
	   Recurring billing flag

       ELECTRONIC CHECK FIELDS

       account_number
	   Bank account number

       routing_code
	   Bank's routing code

       account_type
	   Account type.  Can be (case-insensitive): Personal Checking, Personal Savings, Business Checking or Business Savings.

       account_name
	   Account holder's name.

       bank_name
	   Bank name.

       bank_city
	   Bank city.

       bank_state
	   Bank state.

       check_type
	   Check type.

       customer_org
	   Customer organization type.

       customer_ssn
	   Customer's social security number.

       license_num
	   Customer's driver's license number.

       license_dob
	   Customer's date of birth.

       RECURRING BILLING FIELDS

       interval
	   Interval expresses the amount of time between billings: digits, whitespace and units (currently "days" or "months" in either singular
	   or plural form).

       start
	   The date of the first transaction (used for processors which allow delayed start) expressed as YYYY-MM-DD.

       periods
	   The number of cycles of interval length for which billing should occur (inclusive of 'trial periods' if the processor supports
	   recurring billing at more than one rate)

   test_transaction()
       Most processors provide a test mode, where submitted transactions will not actually be charged or added to your batch, calling this
       function with a true argument will turn that mode on if the processor supports it, or generate a fatal error if the processor does not
       support a test mode (which is probably better than accidentally making real charges).

   require_avs()
       Providing a true argument to this module will turn on address verification (if the processor supports it).

TRANSACTION SUBMISSION METHOD

   submit()
       Submit the transaction to the processor for completion

TRANSACTION RESULT METHODS

   is_success()
       Returns true if the transaction was submitted successfully, false if it failed (or undef if it has not been submitted yet).

   error_message()
       If the transaction has been submitted but was not accepted, this function will return the provided error message (if any) that the
       processor returned.

   failure_status()
       If the transaction failed, it can optionally return a specific failure status (normalized, not gateway-specific).  Currently defined
       statuses are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup", "blacklisted" and "declined" (card/transaction declines only,
       not other errors).

       Note that (as of Aug 2006) this is only supported by some of the newest processor modules, and that, even if supported, a failure status is
       an entirely optional field that is only set for specific kinds of failures.

   authorization()
       If the transaction has been submitted and accepted, this function will provide you with the authorization code that the processor returned.
       Store this if you would like to run inquiries or refunds on the transaction later.

   order_number()
       The unique order number for the transaction generated by the gateway.  Store this if you would like to run inquiries or refunds on the
       transaction later.

   card_token()
       If supported by your gateway, a card_token can be used in a subsequent transaction to refer to a card number.

   fraud_score()
       Retrieve or change the fraud score from any Business::FraudDetect plugin

   fraud_transaction_id()
       Retrieve or change the transaction id from any Business::FraudDetect plugin

   response_code()
   response_headers()
   response_page()
       These three fields are set by some processors (especially those which use HTTPS) when the transaction fails at the communication level
       rather than as a transaction.

       response_code is the HTTP response code and message, i.e.  '500 Internal Server Error'.

       response_headers is a hash reference of the response headers

       response_page is the raw content.

   result_code()
       Returns the precise result code that the processor returned, these are normally one letter codes that don't mean much unless you understand
       the protocol they speak, you probably don't need this, but it's there just in case.

   avs_code()
   cvv2_response()
MISCELLANEOUS INTERNAL METHODS

   transaction_type()
       Retrieve the transaction type (the 'type' argument to contents()).  Generally only used internally, but provided in case it is useful.

   server()
       Retrieve or change the processor submission server address (CHANGE AT YOUR OWN RISK).

   port()
       Retrieve or change the processor submission port (CHANGE AT YOUR OWN RISK).

   path()
       Retrieve or change the processor submission path (CHANGE AT YOUR OWN RISK).

HELPER METHODS FOR GATEWAY MODULE AUTHORS

   build_subs( @sub_names )
       Build setter/getter subroutines for new return values.

   get_fields( @fields )
       Get the named fields if they are defined.

   remap_fields( %map )
       Remap field content (and stuff it back into content).

   required_fields( @fields )
       Croaks if any of the required fields are not present.

   dump_contents
   silly_bool( $value )
       Returns 0 if the value starts with y, Y, t or T.  Returns 1 if the value starts with n, N, f or F.  Otherwise returns the value itself.

       Use this for handling boolean content like tax_exempt.

AUTHORS

       (v2 series)

       Jason Kohles, email@jasonkohles.com

       (v3 rewrite)

       Ivan Kohler <ivan-business-onlinepayment@420.am>

       Phil Lobbes <phil at perkpartners dot com>

COPYRIGHT

       Copyright (c) 1999-2004 Jason Kohles Copyright (c) 2004 Ivan Kohler Copyright (c) 2007-2011 Freeside Internet Services, Inc.

       All rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

HOMEPAGE

       Homepage:  http://420.am/business-onlinepayment/

       Development:  http://420.am/business-onlinepayment/ng.html

MAILING LIST

       Please direct current development questions, patches, etc. to the mailing list: http://420.am/cgi-bin/mailman/listinfo/bop-devel/

REPOSITORY

       The code is available from our public CVS repository:

	 export CVSROOT=":pserver:anonymous@cvs.freeside.biz:/home/cvs/cvsroot"
	 cvs login
	 # The password for the user `anonymous' is `anonymous'.
	 cvs checkout Business-OnlinePayment

       Or on the web:

	 http://freeside.biz/cgi-bin/viewvc.cgi/Business-OnlinePayment/

       Many (but by no means all!) processor plugins are also available in the same repository, see:

	 http://freeside.biz/cgi-bin/viewvc.cgi/

DISCLAIMER

       THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
       MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       http://420.am/business-onlinepayment/

       For verification of credit card checksums, see Business::CreditCard.

perl v5.12.4							    2011-08-19							OnlinePayment(3pm)