NAME

Business::OnlinePayment::InternetSecure - InternetSecure backend for Business::OnlinePayment

SYNOPSIS

  use Business::OnlinePayment;

  $txn = new Business::OnlinePayment 'InternetSecure',
  					merchant_id => '0000';

  $txn->content(
	action		=> 'Normal Authorization',

  	type		=> 'Visa',			# Optional
	card_number	=> '4111 1111 1111 1111',
	exp_date	=> '2004-07',
	cvv2		=> '000',			# Optional

	name		=> "Fr\x{e9}d\x{e9}ric Bri\x{e8}re",
	company		=> '',
	address		=> '123 Street',
	city		=> 'Metropolis',
	state		=> 'ZZ',
	zip		=> 'A1A 1A1',
	country		=> 'CA',
	phone		=> '(555) 555-1212',
	email		=> 'fbriere@fbriere.net',

	amount		=> 49.95,
	currency	=> 'CAD',
	taxes		=> 'GST PST',
	description	=> 'Test transaction',
	);

  $txn->submit;

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

DESCRIPTION

Business::OnlinePayment::InternetSecure is an implementation of Business::OnlinePayment that allows for processing online credit card payments through InternetSecure.

See Business::OnlinePayment for more information about the generic Business::OnlinePayment interface.

CREATOR

Object creation is done via Business::OnlinePayment; see its manpage for details. The merchant_id processor option is required, and corresponds to the merchant ID assigned to you by InternetSecure.

METHODS

Transaction setup and transmission

content( CONTENT )

Sets up the data prior to a transaction. CONTENT is an associative array (hash), containing some of the following fields:

action (required)

What to do with the transaction. Only Normal Authorization is supported at the moment.

type

Transaction type, being one of the following:

- Visa

- MasterCard

- American Express

- Discover

- JCB

(This is actually ignored for the moment, and can be left blank or undefined.)

card_number (required)

Credit card number. Spaces and dashes are automatically removed.

exp_date (required)

Credit card expiration date. Since Business::OnlinePayment does not specify any syntax, this module is rather lax regarding what it will accept. The recommended syntax is YYYY-MM, but forms such as MM/YYYY or MMYY are allowed as well.

cvv2

Three- or four-digit verification code printed on the card. This can be left blank or undefined, in which case no check will be performed. Whether or not a transaction will be declined in case of a mismatch depends on the merchant account configuration.

This number may be called Card Verification Value (CVV2), Card Validation Code (CVC2) or Card Identification number (CID), depending on the card issuer.

description

A short description of the transaction. See "Products list syntax" for an alternate syntax that allows a list of products to be specified.

amount (usually required)

Total amount to be billed, excluding taxes if they are to be added separately by InternetSecure.

This field is required if description is a string, but should be left undefined if description contains a list of products instead, as outlined in "Products list syntax".

currency

Currency of all amounts for this order. This can currently be either CAD (default) or USD.

taxes

Taxes to be added automatically to amount by InternetSecure. Available taxes are GST, PST and HST.

This argument can either be a single string of taxes concatenated with spaces (such as GST PST), or a reference to an array of taxes (such as [ "GST", "PST" ]).

name / company / address / city / state / zip / country / phone / email

Customer information. country should be a two-letter code taken from ISO 3166-1.

submit()

Submit the transaction to InternetSecure.

Post-submission methods

is_success()

Returns true if the transaction was submitted successfully.

result_code()

Response code returned by InternetSecure.

error_message()

Error message if the transaction was unsuccessful; undef otherwise. (You should not rely on this to test whether a transaction was successful; use is_success() instead.)

receipt_number()

Receipt number (a string, actually) of this transaction, unique to all InternetSecure transactions.

sales_number()

Sales order number of this transaction. This is a number, unique to each merchant, which is incremented by 1 each time.

uuid()

Universally Unique Identifier associated to this transaction. This is a 128-bit value returned as a 36-character string such as f81d4fae-7dec-11d0-a765-00a0c91e6bf6. See RFC 4122 for more details on UUIDs.

guid() is provided as an alias to this method.

authorization()

Authorization code for this transaction.

avs_response() / cvv2_response()

Results of the AVS and CVV2 checks. See the InternetSecure documentation for the list of possible values.

date()

Date and time of the transaction. Format is YYYY/MM/DD hh:mm:ss.

total_amount()

Total amount billed for this order, including taxes.

tax_amounts()

Returns a reference to a hash that maps taxes, which were listed under the taxes argument to submit(), to the amount that was calculated by InternetSecure.

cardholder()

Cardholder's name. This is currently a mere copy of the name field passed to submit().

card_type()

Type of the credit card used for the submitted order, being one of the following:

- Visa

- MasterCard

- American Express

- Discover

- JCB

NOTES

Products list syntax

Optionally, the description field of content() can contain a reference to an array of products, instead of a simple string. Each element of this array represents a different product, and must be a reference to a hash with the following fields:

amount (required)

Unit price of this product.

quantity

Ordered quantity of this product.

sku

Internal code for this product.

description

Description of this product

taxes

Taxes that should be automatically added to this product. If specified, this overrides the taxes field passed to content().

When using a products list, the amount field passed to content() should be left undefined.

Character encoding

When using non-ASCII characters, all data provided to contents() should have been decoded beforehand via the Encode module, unless your data is in ISO-8859-1 and you haven't meddled with the encoding pragma. (Please don't.)

InternetSecure currently does not handle characters outside of ISO-8859-1, so these will be replaced with ? before being transmitted.

EXPORT

None by default.

SEE ALSO

Business::OnlinePayment

AUTHOR

Frédéric Brière, <fbriere@fbriere.net>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Frédéric Brière

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.

cpanm Business::OnlinePayment::InternetSecure

perl -MCPAN -e shell
install Business::OnlinePayment::InternetSecure