1 package FS::SelfService;
4 use vars qw($VERSION @ISA @EXPORT_OK $socket %autoload $tag);
10 use Storable qw(nstore_fd fd_retrieve);
14 @ISA = qw( Exporter );
16 $socket = "/usr/local/freeside/selfservice_socket";
17 $socket .= '.'.$tag if defined $tag && length($tag);
19 #maybe should ask ClientAPI for this list
21 'passwd' => 'passwd/passwd',
22 'chfn' => 'passwd/passwd',
23 'chsh' => 'passwd/passwd',
24 'login' => 'MyAccount/login',
25 'customer_info' => 'MyAccount/customer_info',
26 'invoice' => 'MyAccount/invoice',
27 'cancel' => 'MyAccount/cancel',
28 'payment_info' => 'MyAccount/payment_info',
29 'process_payment' => 'MyAccount/process_payment',
30 'list_pkgs' => 'MyAccount/list_pkgs',
31 'order_pkg' => 'MyAccount/order_pkg',
32 'cancel_pkg' => 'MyAccount/cancel_pkg',
33 'signup_info' => 'Signup/signup_info',
34 'new_customer' => 'Signup/new_customer',
36 @EXPORT_OK = keys %autoload;
38 $ENV{'PATH'} ='/usr/bin:/usr/ucb:/bin';
39 $ENV{'SHELL'} = '/bin/sh';
40 $ENV{'IFS'} = " \t\n";
43 $ENV{'BASH_ENV'} = '';
45 my $freeside_uid = scalar(getpwnam('freeside'));
46 die "not running as the freeside user\n" if $> != $freeside_uid;
48 foreach my $autoload ( keys %autoload ) {
59 $param->{_packet} = \''. $autoload{$autoload}. '\';
61 simple_packet($param);
71 socket(SOCK, PF_UNIX, SOCK_STREAM, 0) or die "socket: $!";
72 connect(SOCK, sockaddr_un($socket)) or die "connect: $!";
73 nstore_fd($packet, \*SOCK) or die "can't send packet: $!";
76 #shoudl trap: Magic number checking on storable file failed at blib/lib/Storable.pm (autosplit into blib/lib/auto/Storable/fd_retrieve.al) line 337, at /usr/local/share/perl/5.6.1/FS/SelfService.pm line 71
78 #block until there is a message on socket
79 # my $w = new IO::Select;
81 # my @wait = $w->can_read;
82 my $return = fd_retrieve(\*SOCK) or die "error reading result: $!";
83 die $return->{'_error'} if defined $return->{_error} && $return->{_error};
90 FS::SelfService - Freeside self-service API
94 # password and shell account changes
95 use FS::SelfService qw(passwd chfn chsh);
97 # "my account" functionality
98 use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );
100 my $rv = login( { 'username' => $username,
102 'password' => $password,
106 if ( $rv->{'error'} ) {
107 #handle login error...
110 my $session_id = $rv->{'session_id'};
113 my $customer_info = customer_info( { 'session_id' => $session_id } );
115 #payment_info and process_payment are available in 1.5+ only
116 my $payment_info = payment_info) { 'session_id' => $session_id } );
118 #!!! process_payment example
120 #!!! list_pkgs example
122 #!!! order_pkg example
124 #!!! cancel_pkg example
126 # signup functionality
127 use FS::SelfService qw( signup_info new_customer );
129 my $signup_info = signup_info;
131 $rv = new_customer( {
134 'company' => $company,
135 'address1' => $address1,
136 'address2' => $address2,
140 'country' => $country,
141 'daytime' => $daytime,
145 'payinfo' => $payinfo,
147 'paydate' => $paydate,
148 'payname' => $payname,
149 'invoicing_list' => $invoicing_list,
150 'referral_custnum' => $referral_custnum,
151 'pkgpart' => $pkgpart,
152 'username' => $username,
153 '_password' => $password,
155 'agentnum' => $agentnum,
159 my $error = $rv->{'error'};
160 if ( $error eq '_decline' ) {
170 Use this API to implement your own client "self-service" module.
172 If you just want to customize the look of the existing "self-service" module,
175 =head1 PASSWORD, GECOS, SHELL CHANGING FUNCTIONS
187 =head1 "MY ACCOUNT" FUNCTIONS
193 Creates a user session. Takes a hash reference as parameter with the
206 Returns a hash reference with the following keys:
212 Empty on success, or an error message on errors.
216 Session identifier for successful logins
220 =item customer_info HASHREF
222 Returns general customer information.
224 Takes a hash reference as parameter with a single key: B<session_id>
226 Returns a hash reference with the following keys:
240 Array reference of hash references of open inoices. Each hash reference has
241 the following keys: invnum, date, owed
245 An HTML fragment containing shipping and billing addresses.
249 =item invoice HASHREF
251 Returns an invoice. Takes a hash reference as parameter with two keys:
252 session_id and invnum
254 Returns a hash reference with the following keys:
260 Empty on success, or an error message on errors
274 Cancels this customer.
276 Takes a hash reference as parameter with a single key: B<session_id>
278 Returns a hash reference with a single key, B<error>, which is empty on
279 success or an error message on errors.
281 =item payment_info HASHREF
283 Returns information that may be useful in displaying a payment page.
285 Takes a hash reference as parameter with a single key: B<session_id>.
287 Returns a hash reference with the following keys:
293 Empty on success, or an error message on errors
301 Exact name on credit card (CARD/DCRD)
315 Customer's current default payment type.
319 For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
323 For CARD/DCRD payment types, the card number
327 For CARD/DCRD payment types, expiration month
331 For CARD/DCRD payment types, expiration year
333 =item cust_main_county
335 County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see L<FS::cust_main_county>). Note these are not FS::cust_main_county objects, but hash references of columns and values.
339 Array reference of all states in the current default country.
343 Hash reference of card types; keys are card types, values are the exact strings
344 passed to the process_payment function
348 Unique transaction identifier (prevents multiple charges), passed to the
349 process_payment function
353 =item process_payment HASHREF
355 Processes a payment and possible change of address or payment type. Takes a
356 hash reference as parameter with the following keys:
364 If true, address and card information entered will be saved for subsequent
369 If true, future credit card payments will be done automatically (sets payby to
370 CARD). If false, future credit card payments will be done on-demand (sets
371 payby to DCRD). This option only has meaning if B<save> is set true.
391 Card expiration month
399 Unique transaction identifier, returned from the payment_info function.
400 Prevents multiple charges.
404 Returns a hash reference with a single key, B<error>, empty on success, or an
405 error message on errors
409 Returns package information for this customer.
411 Takes a hash reference as parameter with a single key: B<session_id>
413 Returns a hash reference containing customer package information. The hash reference contains the following keys:
417 =item cust_pkg HASHREF
419 Array reference of hash references, each of which has the fields of a cust_pkg record (see L<FS::cust_pkg>). Note these are not FS::cust_pkg objects, but hash references of columns and values.
425 Orders a package for this customer.
427 Takes a hash reference as parameter with the following keys:
437 optional svcpart, required only if the package definition does not contain
438 one svc_acct service definition with quantity 1 (it may contain others with
451 Returns a hash reference with a single key, B<error>, empty on success, or an
452 error message on errors. The special error '_decline' is returned for
453 declined transactions.
457 Cancels a package for this customer.
459 Takes a hash reference as parameter with the following keys:
469 Returns a hash reference with a single key, B<error>, empty on success, or an
470 error message on errors.
474 =head1 SIGNUP FUNCTIONS
480 Returns a hash reference containing information that may be useful in
481 displaying a signup page. The hash reference contains the following keys:
485 =item cust_main_county
487 County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see L<FS::cust_main_county>). Note these are not FS::cust_main_county objects, but hash references of columns and values.
491 Available packages - array reference of hash references, each of which has the fields of a part_pkg record (see L<FS::part_pkg>). Each hash reference also has an additional 'payby' field containing an array reference of acceptable payment types specific to this package (see below and L<FS::part_pkg/payby>). Note these are not FS::part_pkg objects, but hash references of columns and values. Requires the 'signup_server-default_agentnum' configuration value to be set.
495 Array reference of hash references, each of which has the fields of an agent record (see L<FS::agent>). Note these are not FS::agent objects, but hash references of columns and values.
497 =item agentnum2part_pkg
499 Hash reference; keys are agentnums, values are array references of available packages for that agent, in the same format as the part_pkg arrayref above.
503 Access numbers - array reference of hash references, each of which has the fields of an svc_acct_pop record (see L<FS::svc_acct_pop>). Note these are not FS::svc_acct_pop objects, but hash references of columns and values.
505 =item security_phrase
507 True if the "security_phrase" feature is enabled
511 Array reference of acceptable payment types for signup
515 =item CARD (credit card - automatic)
517 =item DCRD (credit card - on-demand - version 1.5+ only)
519 =item CHEK (electronic check - automatic)
521 =item DCHK (electronic check - on-demand - version 1.5+ only)
523 =item LECB (Phone bill billing)
525 =item BILL (billing, not recommended for signups)
527 =item COMP (free, definately not recommended for signups)
529 =item PREPAY (special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL)
535 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
539 Hash reference of message catalog values, to support error message customization. Currently available keys are: passwords_dont_match, invalid_card, unknown_card_type, and not_a (as in "Not a Discover card"). Values are configured in the web interface under "View/Edit message catalog".
551 =item new_customer HASHREF
553 Creates a new customer. Takes a hash reference as parameter with the
558 =item first - first name (required)
560 =item last - last name (required)
562 =item ss (not typically collected; mostly used for ACH transactions)
566 =item address1 (required)
570 =item city (required)
574 =item state (required)
578 =item daytime - phone
584 =item payby - CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
586 =item payinfo - Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
588 =item paycvv - Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
590 =item paydate - Expiration date for CARD/DCRD
592 =item payname - Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
594 =item invoicing_list - comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses),
596 =item referral_custnum - referring customer number
598 =item pkgpart - pkgpart of initial package
604 =item sec_phrase - security phrase
606 =item popnum - access number (index, not the literal number)
608 =item agentnum - agent number
612 Returns a hash reference with the following keys:
616 =item error Empty on success, or an error message on errors. The special error '_decline' is returned for declined transactions; other error messages should be suitable for display to the user (and are customizable in under Sysadmin | View/Edit message catalog)
627 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>