1 package Business::OnlineThirdPartyPayment;
6 use base qw(Business::OnlinePayment);
11 $VERSION = eval $VERSION; # modperlstyle: convert the string into a number
19 order_number => undef,
20 authorization => undef,
21 error_message => undef,
22 test_transaction => undef,
28 my($class,$processor,%data) = @_;
30 croak("unspecified processor") unless $processor;
32 my $subclass = "${class}::$processor";
34 croak("unknown processor $processor ($@)") if $@;
36 my $self = bless {processor => $processor}, $subclass;
37 $self->build_subs(keys %fields);
39 if($self->can("set_defaults")) {
40 $self->set_defaults(%data);
45 my $value = $data{$_};
47 $self->build_subs($key);
60 Business::OnlineThirdPartyPayment - Common interface to browser-based
61 online payment processors
65 use Business::OnlineThirdPartyPayment;
68 my %processor_info = (
69 'return_url' => 'https://www.example.com/payment/return',
70 'cancel_url' => 'https://www.example.com/payment/cancel',
71 # ... other processor-specific values
74 my $txn = Business::OnlineThirdPartyPayment->new('MyBank', %processor_info);
76 $txn->create( customer_id => 4030,
77 invoice_number => 10318,
80 description => 'Internet Services',
83 if ( $txn->is_success} ) {
84 store_payment_id($txn->token); # keep it somewhere
85 print CGI->redirect( $txn->redirect );
87 die $txn->error_message;
91 # then, at /payment/return...
92 my $txn = Business::OnlineThirdPartyPayment->new('MyBank', %processor_info);
93 $txn->token( get_payment_id($cgi) ); # probably from a session cookie
94 my %params = $cgi->Vars;
96 $txn->execute(%params);
98 if ( $txn->is_success ) {
99 store_payment_success($txn->order_number, $txn->authorization);
100 print "Your payment was successful!\n";
102 store_payment_failure($txn->order_number, $txn->error_message);
103 print "Your payment failed.\n";
108 Business::OnlineThirdPartyPayment is a generic module for processing payments
109 through online credit card processors, electronic cash systems, etc. through
110 which the payer's web browser is redirected.
114 =head2 new($module, %processor_options)
116 Class method. Create a Business::OnlineThirdPartyPayment object.
117 $module is required, and defines the gateway module to use. The
118 other options are processor-specific, but should always include:
122 =item return_url - The callback URL to redirect the user to after completing
125 =item cancel_url - The URL to redirect the user to if they choose not to
126 complete the payment.
130 =head2 create(%content)
132 Tell the gateway module to start a transaction. This may involve
133 communicating with the gateway, or it may happen entirely locally.
134 %content is a hash containing some of the following:
136 =head3 TRANSACTION FIELDS
140 =item amount - The amount of the transaction, as a decimal number. Required.
142 =item description - A description of the purchase. Required.
144 =item invoice_number - Your invoice number, if this payment is associated
145 with a specific invoice.
147 =item currency - Currency, specified as an ISO 4217 three-letter code, such
148 as USD, CAD, EUR, AUD, DKK, GBP, JPY, NZD, etc.
150 =item customer_id - The customer number, if any.
152 =item email - Customer's email address.
154 =item customer_ip - IP address from which the transaction originated.
158 For additional fields, see L<Business::OnlinePayment> and the specific
159 processor module used.
161 C<create()> sets properties of the transaction object to indicate the
162 result. These will always include:
166 =item is_success - 1 if the transaction was created successfully, 0
169 =item error_message - a text description of any error that occurred.
170 Since the payer hasn't provided a payment account or any other
171 information at this stage, this is probably not meaningful to them.
173 =item token - a reference string that will be used to identify
174 this transaction later. If is_success is true, you I<must> store this
175 value in your merchant system and pass it to execute() later. Merchant
176 systems should allow at least 256 characters for this string.
178 =item statustext - a freeform text field for any state information
179 that the gateway needs to receive to complete the transaction.
181 =item redirect - a URL to redirect the payer to.
183 =item post_params - the content of an HTTP POST request to send to the
184 URL. Since HTTP redirects can't include POST content, in this case the
185 front-end system must provide another way (a self-submitting form) to
186 induce the purchaser's browser to make the request.
190 =head2 execute(%params)
192 Complete the transaction. This should be called from the web server
193 (from 'return_url'). %params must contain any query parameters passed
194 in the redirect, and token should be set on the object.
196 execute() will set the transaction fields to indicate the result:
200 =item is_success: 1 if the payment was successful, 0 if it was not.
202 =item error_message: An error message describing the reason for failure.
203 Unlike the message returned from C<create()>, this probably is meaningful
204 to the user, though the gateway may already have shown it to them.
206 =item order_number: The transaction ID number assigned by the processor.
208 =item authorization: The credit card or other authorization number
209 returned by the gateway. This may be needed to refund the payment or
210 for other customer service issues.
214 If C<is_success> is true, the merchant system should record this as
215 a successful payment and apply it to the customer's account.
219 Mark Wells <mark@freeside.biz>, based in part on code by Jeff Finucane.
223 Copyright (c) 1999-2004 Jason Kohles.
224 Copyright (c) 2007-2013 Freeside Internet Services, Inc.
226 All rights reserved. This program is free software; you can redistribute
227 it and/or modify it under the same terms as Perl itself.
231 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
232 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
233 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
237 L<Business::OnlinePayment>, http://420.am/business-onlinepayment/