perldoc > Business::OnlinePayment

man perldoc info pydoc3 ri search

📛 NAME

Business::OnlinePayment - Perl extension for online payment processing 💳

🚀 Quick Reference

Use Case	Command	Description
Create processor object	my $tx = new Business::OnlinePayment($processor, %options);	Instantiate gateway
Set transaction details	$tx->content(type => 'CC', amount => '49.95', …);	Define payment info
Enable test mode	$tx->test_transaction(1);	No real charges
Require AVS	$tx->require_avs(1);	Address verification
Submit payment	$tx->submit();	Process transaction
Check success	$tx->is_success();	True if approved
Get error	$tx->error_message();	Human-friendly decline reason
Authorization code	$tx->authorization();	Gateway approval code
Order number	$tx->order_number();	Gateway-generated order ID
Partial auth amount	$tx->partial_auth_amount();	Amount if less than requested
Fraud score	$tx->fraud_score();	From fraud detection plugin

📋 SYNOPSIS

use Business::OnlinePayment;

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

eval { $transaction->submit(); };

if ( $@ ) {
  print "$processor error: $@\n";
} else {
  if ( $transaction->is_success() ) {
    print "Card processed successfully: ". $transaction->authorization()."\n";
  } else {
    print "Card was rejected: ". $transaction->error_message(). "\n";
  }
}

📖 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. Optional processor options are Server, Port, and Path, which specify how to reach the processor (https://server:port/path). Individual processor modules supply reasonable defaults; override only if absolutely necessary (especially path), as the processor module was written with a specific target script in mind.

⚙️ TRANSACTION SETUP METHODS

📦 content(%content)

The information necessary for the transaction. This varies by processor; a system of defined frontend fields maps to the correct backend fields.

🔑 PROCESSOR FIELDS

• login – 🔐 Your login name for authentication to the online processor.
• password – 🔒 Your password for authentication to the online processor.

✅ REQUIRED TRANSACTION FIELDS

• type – 🏷️ Transaction type. Supported: CC (credit card), ECHECK (electronic check), LEC (phone bill billing). Deprecated: Visa, MasterCard, American Express, Discover, Check. Not all processors support all types.
• action – 🎬 Action taken. Available: Normal Authorization, Authorization Only, Post Authorization, Reverse Authorization, Void, Credit, Tokenize, Recurring Authorization, Modify Recurring Authorization, Cancel Recurring Authorization.
• amount – 💲 The transaction amount. No dollar signs or currency identifiers; a whole or floating point number (e.g. 26, 26.1, 26.13).

📋 OPTIONAL TRANSACTION FIELDS

• partial_auth – 🪙 If set to true, enables partial authorization handling (see partial_auth_amount()). If not set, a partial auth is immediately reversed/voided.
• description – 📝 A description of the transaction (used by some processors to send info to the client; normally not required).
• invoice_number – 🧾 An invoice number for your use. Many processors require this to be numeric only.
• po_number – 📄 Purchase order number (normally not required).
• tax – 🧾 Tax amount (portion of amount, not added to it).
• freight – 🚚 Freight amount (portion of amount, not added to it).
• duty – 🛃 Duty amount (portion of amount, not added to it).
• tax_exempt – ✴️ Tax exempt flag (TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
• currency – 💱 ISO 4217 three‑letter code (e.g., USD, CAD, EUR, AUD, DKK, GBP, JPY, NZD).

👤 CUSTOMER INFO FIELDS

• customer_id – 🆔 A customer identifier, normally not required.
• name – 👤 The customer's full name.
• first_name, last_name – 📛 Customer's first and last name as separate fields.
• company – 🏢 Customer's company name, not normally required.
• address – 🏠 Customer's address (often required for AVS).
• city – 🌆 Customer's city (often required for AVS).
• state – 🗺️ Customer's state (often required for AVS).
• zip – 📮 Customer's zip code (often required for AVS).
• country – 🌍 Customer's country.
• ship_first_name, ship_last_name, ship_company, ship_address, ship_city, ship_state, ship_zip, ship_country – 📦 Shipping address fields (may be accepted by your processor).
• 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, MM/YY.
• cvv2 – 🔐 CVV2/CVC2/CID security code (3‑4 digits).
• card_token – 🎫 If supported by your gateway, pass a token instead of 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 (case‑insensitive): Personal Checking, Personal Savings, Business Checking, Business Savings.
• nacha_sec_code – 📄 NACHA SEC Code for US ACH: PPD (signed form), CCD (business), WEB (online box), TEL (recorded call).
• 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 – 🪪 Driver's license number.
• license_dob – 🎂 Customer's date of birth.

🔁 FOLLOW‑UP TRANSACTION FIELDS

Used in Post Authorization, Reverse Authorization, Void, Credit transactions:

• authorization
• order_number
• txn_date

🔂 RECURRING BILLING FIELDS

• interval – ⏱️ Time between billings (digits + unit, e.g. 1 month or 30 days).
• start – 📅 Date of first transaction, YYYY‑MM‑DD (for delayed start).
• periods – 🔢 Number of cycles (including trial periods if the processor supports multiple rates).

🧪 test_transaction()

Most processors provide a test mode where submitted transactions are not actually charged. Call with a true argument to enable (if supported); otherwise a fatal error is thrown to prevent accidental real charges.

📍 require_avs()

Provide a true argument to turn on Address Verification (if the processor supports it).

📤 TRANSACTION SUBMISSION METHOD

📨 submit()

Submit the transaction to the processor for completion. If a gateway communication error or other "meta" issue occurs, submit throws a fatal exception (catch with eval {}).

📊 TRANSACTION RESULT METHODS

✅ is_success()

Returns true if the transaction was approved by the gateway, false if submitted but not approved, or undef if not yet submitted.

🪙 partial_auth_amount()

If the transaction was a partial authorization (successful but less than the requested amount), returns the actual amount processed. Empty or 0 when is_success is true indicates a normal full authorization.

❌ error_message()

If the transaction was submitted but not accepted, returns the processor‑provided error message (if any).

🚫 failure_status()

If the transaction failed, may return a normalized failure status (not gateway‑specific). Currently defined: "expired", "nsf" (non‑sufficient funds), "stolen", "pickup", "blacklisted", "declined" (card/transaction declines only). Not all processors support this, and it may not be set for all declines.

🆔 authorization()

If submitted and accepted, returns the authorization code from the processor. Store this for later inquiries or refunds.

📋 order_number()

The unique order number for the transaction generated by the gateway. Store for later inquiries or refunds.

🎫 card_token()

If supported by your gateway, a card_token that can be used in a subsequent transaction in place of a full card number.

📅 txn_date()

Transaction date as returned by the gateway. Required by some gateways for follow‑up transactions.

🕵️ 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()

Set by some processors (especially HTTPS) when a transaction fails at the communication level. response_code is the HTTP response code and message (e.g. "500 Internal Server Error"), response_headers is a hash reference of response headers, response_page is the raw content.

🔢 result_code()

Returns the precise result code from the processor (often one‑letter codes). Use only if you understand the protocol.

🔍 avs_code() / cvv2_response()

Address verification and CVV2 response values, as returned by the gateway.

🔧 MISCELLANEOUS INTERNAL METHODS

🏷️ transaction_type()

Retrieve the transaction type (the type argument to contents()). Generally used internally.

🌐 server() / port() / path()

Retrieve or change the processor submission server address, port, or 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

Dump the current contents (debugging aid).

🔘 silly_bool($value)

Returns 1 if the value starts with y, Y, t, or T; 0 if it starts with n, N, f, or F; otherwise the value itself. Use for handling boolean content like tax_exempt.

🧑‍💻 AUTHORS

(v2 series) Jason Kohles, email AT jasonkohles.com
(v3 rewrite) Ivan Kohler <ivan-business-onlinepayment AT 420.am>
Phil Lobbes <phil at perkpartners dot com>

©️ COPYRIGHT

Copyright (c) 1999-2004 Jason Kohles
Copyright (c) 2004 Ivan Kohler
Copyright (c) 2007-2018 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://perl.business/onlinepayment
Development: http://perl.business/onlinepayment/ng.html

📧 MAILING LIST

Direct development questions, patches, etc. to: http://mail.freeside.biz/cgi-bin/mailman/listinfo/bop-devel/

📦 REPOSITORY

Code available from public git:

git clone git://git.freeside.biz/Business-OnlinePayment.git

Or on the web:

• http://git.freeside.biz/gitweb/?p=Business-OnlinePayment.git
• http://git.freeside.biz/cgit/Business-OnlinePayment.git

Many processor plugins are also available in the same repository:

• http://git.freeside.biz/gitweb/
• http://git.freeside.biz/cgit/

⚠️ 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://perl.business/onlinepayment

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

📛 NAME 🚀 Quick Reference 📋 SYNOPSIS 📖 DESCRIPTION 🏗️ CONSTRUCTOR ⚙️ TRANSACTION SETUP METHODS 📤 TRANSACTION SUBMISSION METHOD 📊 TRANSACTION RESULT METHODS 🔧 MISCELLANEOUS INTERNAL METHODS 🛠️ HELPER METHODS FOR GATEWAY MODULE AUTHORS 🧑‍💻 AUTHORS ©️ COPYRIGHT 🌐 HOMEPAGE 📧 MAILING LIST 📦 REPOSITORY ⚠️ DISCLAIMER 👀 SEE ALSO