File: //usr/local/ssl/local/share/man/man3/Business::OnlinePayment.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OnlinePayment 3"
.TH OnlinePayment 3 "2009-08-17" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Business::OnlinePayment \- Perl extension for online payment processing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Business::OnlinePayment;
.Ve
.PP
.Vb 9
\& 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();
.Ve
.PP
.Vb 5
\& if($transaction->is_success()) {
\& print "Card processed successfully: ", $transaction->authorization(), "\en";
\& } else {
\& print "Card was rejected: ", $transaction->error_message(), "\en";
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Business::OnlinePayment is a generic module for processing payments
through online credit card processors, electronic cash systems, etc.
.SH "METHODS AND FUNCTIONS"
.IX Header "METHODS AND FUNCTIONS"
.ie n .Sh "new($processor, %processor_options);"
.el .Sh "new($processor, \f(CW%processor_options\fP);"
.IX Subsection "new($processor, %processor_options);"
Create a new Business::OnlinePayment object, \f(CW$processor\fR 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.
.Sh "content(%content);"
.IX Subsection "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:
.PP
\fI\s-1PROCESSOR\s0 \s-1FIELDS\s0\fR
.IX Subsection "PROCESSOR FIELDS"
.IP "* login" 4
.IX Item "login"
Your login name to use for authentication to the online processor.
.IP "* password" 4
.IX Item "password"
Your password to use for authentication to the online processor.
.PP
\fI\s-1GENERAL\s0 \s-1TRANSACTION\s0 \s-1FIELDS\s0\fR
.IX Subsection "GENERAL TRANSACTION FIELDS"
.IP "* type" 4
.IX Item "type"
Transaction type, supported types are: \s-1CC\s0 (credit card), \s-1ECHECK\s0
(electronic check) and \s-1LEC\s0 (phone bill billing). Deprecated types
are: Visa, MasterCard, American Express, Discover, Check (not all
processors support all these transaction types).
.IP "* action" 4
.IX Item "action"
What to do with the transaction (currently available are: Normal
Authorization, Authorization Only, Credit, Post Authorization,
Recurring Authorization, Modify Recurring Authorization,
Cancel Recurring Authorization)
.IP "* description" 4
.IX Item "description"
A description of the transaction (used by some processors to send
information to the client, normally not a required field).
.IP "* amount" 4
.IX Item "amount"
The amount of the transaction, most processors don't want dollar signs
and the like, just a floating point number.
.IP "* invoice_number" 4
.IX Item "invoice_number"
An invoice number, for your use and not normally required, many
processors require this field to be a numeric only field.
.PP
\fI\s-1CUSTOMER\s0 \s-1INFO\s0 \s-1FIELDS\s0\fR
.IX Subsection "CUSTOMER INFO FIELDS"
.IP "* customer_id" 4
.IX Item "customer_id"
A customer identifier, again not normally required.
.IP "* name" 4
.IX Item "name"
The customer's name, your processor may not require this.
.IP "* first_name" 4
.IX Item "first_name"
.PD 0
.IP "* last_name" 4
.IX Item "last_name"
.PD
The customer's first and last name as separate fields.
.IP "* company" 4
.IX Item "company"
The customer's company name, not normally required.
.IP "* address" 4
.IX Item "address"
The customer's address (your processor may not require this unless you
are requiring \s-1AVS\s0 Verification).
.IP "* city" 4
.IX Item "city"
The customer's city (your processor may not require this unless you
are requiring \s-1AVS\s0 Verification).
.IP "* state" 4
.IX Item "state"
The customer's state (your processor may not require this unless you
are requiring \s-1AVS\s0 Verification).
.IP "* zip" 4
.IX Item "zip"
The customer's zip code (your processor may not require this unless
you are requiring \s-1AVS\s0 Verification).
.IP "* country" 4
.IX Item "country"
Customer's country.
.IP "* ship_first_name" 4
.IX Item "ship_first_name"
.PD 0
.IP "* ship_last_name" 4
.IX Item "ship_last_name"
.IP "* ship_company" 4
.IX Item "ship_company"
.IP "* ship_address" 4
.IX Item "ship_address"
.IP "* ship_city" 4
.IX Item "ship_city"
.IP "* ship_state" 4
.IX Item "ship_state"
.IP "* ship_zip" 4
.IX Item "ship_zip"
.IP "* ship_country" 4
.IX Item "ship_country"
.PD
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.
.IP "* phone" 4
.IX Item "phone"
Customer's phone number.
.IP "* fax" 4
.IX Item "fax"
Customer's fax number.
.IP "* email" 4
.IX Item "email"
Customer's email address.
.IP "* customer_ip" 4
.IX Item "customer_ip"
\&\s-1IP\s0 Address from which the transaction originated.
.PP
\fI\s-1CREDIT\s0 \s-1CARD\s0 \s-1FIELDS\s0\fR
.IX Subsection "CREDIT CARD FIELDS"
.IP "* card_number" 4
.IX Item "card_number"
Credit card number.
.IP "* cvv2" 4
.IX Item "cvv2"
\&\s-1CVV2\s0 number (also called \s-1CVC2\s0 or \s-1CID\s0) is a three\- or four-digit
security code used to reduce credit card fraud.
.IP "* expiration" 4
.IX Item "expiration"
Credit card expiration.
.IP "* track1" 4
.IX Item "track1"
Track 1 on the magnetic stripe (Card present only)
.IP "* track2" 4
.IX Item "track2"
Track 2 on the magnetic stripe (Card present only)
.IP "* recurring billing" 4
.IX Item "recurring billing"
Recurring billing flag
.PP
\fI\s-1ELECTRONIC\s0 \s-1CHECK\s0 \s-1FIELDS\s0\fR
.IX Subsection "ELECTRONIC CHECK FIELDS"
.IP "* account_number" 4
.IX Item "account_number"
Bank account number for electronic checks or electronic funds
transfer.
.IP "* routing_code" 4
.IX Item "routing_code"
Bank's routing code for electronic checks or electronic funds
transfer.
.IP "* account_type" 4
.IX Item "account_type"
Account type for electronic checks or electronic funds transfer. Can be
(case\-insensitive): \fBPersonal Checking\fR, \fBPersonal Savings\fR,
\&\fBBusiness Checking\fR or \fBBusiness Savings\fR.
.IP "* account_name" 4
.IX Item "account_name"
Account holder's name for electronic checks or electronic funds
transfer.
.IP "* bank_name" 4
.IX Item "bank_name"
Bank's name for electronic checks or electronic funds transfer.
.IP "* check_type" 4
.IX Item "check_type"
Check type for electronic checks or electronic funds transfer.
.IP "* customer_org" 4
.IX Item "customer_org"
Customer organization type.
.IP "* customer_ssn" 4
.IX Item "customer_ssn"
Customer's social security number. Typically only required for
electronic checks or electronic funds transfer.
.IP "* license_num" 4
.IX Item "license_num"
Customer's driver's license number. Typically only required for
electronic checks or electronic funds transfer.
.IP "* license_dob" 4
.IX Item "license_dob"
Customer's date of birth. Typically only required for electronic
checks or electronic funds transfer.
.PP
\fI\s-1RECURRING\s0 \s-1BILLING\s0 \s-1FIELDS\s0\fR
.IX Subsection "RECURRING BILLING FIELDS"
.IP "* interval" 4
.IX Item "interval"
Interval expresses the amount of time between billings: digits, whitespace
and units (currently \*(L"days\*(R" or \*(L"months\*(R" in either singular or plural form).
.IP "* start" 4
.IX Item "start"
The date of the first transaction (used for processors which allow delayed
start) expressed as \s-1YYYY\-MM\-DD\s0.
.IP "* periods" 4
.IX Item "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)
.Sh "\fIsubmit()\fP;"
.IX Subsection "submit();"
Submit the transaction to the processor for completion
.Sh "\fIis_success()\fP;"
.IX Subsection "is_success();"
Returns true if the transaction was submitted successfully, false if
it failed (or undef if it has not been submitted yet).
.Sh "\fIfailure_status()\fP;"
.IX Subsection "failure_status();"
If the transaction failed, it can optionally return a specific failure
status (normalized, not gateway\-specific). Currently defined statuses
are: \*(L"expired\*(R", \*(L"nsf\*(R" (non\-sufficient funds), \*(L"stolen\*(R", \*(L"pickup\*(R",
\&\*(L"blacklisted\*(R" and \*(L"declined\*(R" (card/transaction declines only, not
other errors).
.PP
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.
.Sh "\fIresult_code()\fP;"
.IX Subsection "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.
.Sh "\fItest_transaction()\fP;"
.IX Subsection "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).
.Sh "\fIrequire_avs()\fP;"
.IX Subsection "require_avs();"
Providing a true argument to this module will turn on address
verification (if the processor supports it).
.Sh "\fItransaction_type()\fP;"
.IX Subsection "transaction_type();"
Retrieve the transaction type (the 'type' argument to \fIcontents()\fR).
Generally only used internally, but provided in case it is useful.
.Sh "\fIerror_message()\fP;"
.IX Subsection "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.
.Sh "\fIauthorization()\fP;"
.IX Subsection "authorization();"
If the transaction has been submitted and accepted, this function will
provide you with the authorization code that the processor returned.
.Sh "\fIserver()\fP;"
.IX Subsection "server();"
Retrieve or change the processor submission server address (\s-1CHANGE\s0 \s-1AT\s0
\&\s-1YOUR\s0 \s-1OWN\s0 \s-1RISK\s0).
.Sh "\fIport()\fP;"
.IX Subsection "port();"
Retrieve or change the processor submission port (\s-1CHANGE\s0 \s-1AT\s0 \s-1YOUR\s0 \s-1OWN\s0
\&\s-1RISK\s0).
.Sh "\fIpath()\fP;"
.IX Subsection "path();"
Retrieve or change the processor submission path (\s-1CHANGE\s0 \s-1AT\s0 \s-1YOUR\s0 \s-1OWN\s0
\&\s-1RISK\s0).
.Sh "\fIfraud_score()\fP;"
.IX Subsection "fraud_score();"
Retrieve or change the fraud score from any Business::FraudDetect plugin
.Sh "\fIfraud_transaction_id()\fP;"
.IX Subsection "fraud_transaction_id();"
Retrieve or change the transaction id from any Business::FraudDetect plugin
.SH "AUTHORS"
.IX Header "AUTHORS"
Jason Kohles, email@jasonkohles.com
.PP
(v3 rewrite) Ivan Kohler <ivan\-business\-onlinepayment@420.am>
.PP
Phil Lobbes <phil at perkpartners dot com>
.SH "HOMEPAGE"
.IX Header "HOMEPAGE"
Homepage: http://420.am/business\-onlinepayment/
.PP
Development: http://420.am/business\-onlinepayment/ng.html
.SH "MAILING LIST"
.IX Header "MAILING LIST"
Please direct current development questions, patches, etc. to the mailing list:
http://420.am/cgi\-bin/mailman/listinfo/bop\-devel/
.SH "REPOSITORY"
.IX Header "REPOSITORY"
The code is available from our public \s-1CVS\s0 repository:
.PP
.Vb 4
\& export CVSROOT=":pserver:anonymous@cvs.freeside.biz:/home/cvs/cvsroot"
\& cvs login
\& # The password for the user `anonymous' is `anonymous'.
\& cvs checkout Business-OnlinePayment
.Ve
.PP
Or on the web:
.PP
.Vb 1
\& http://freeside.biz/cgi-bin/viewvc.cgi/Business-OnlinePayment/
.Ve
.PP
Many (but by no means all!) processor plugins are also available in the same
repository, see:
.PP
.Vb 1
\& http://freeside.biz/cgi-bin/viewvc.cgi/
.Ve
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
\&\s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1AND\s0 \s-1WITHOUT\s0 \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1WITHOUT\s0 \s-1LIMITATION\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0
\&\s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
http://420.am/business\-onlinepayment/
.PP
For verification of credit card checksums, see Business::CreditCard.