Freeside:1.7:Documentation:Developer/FS/SelfService
From Freeside
Contents
NAME
FS::SelfService - Freeside self-service API
SYNOPSIS
# password and shell account changes
use FS::SelfService qw(passwd chfn chsh);
# "my account" functionality
use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );
my $rv = login( { 'username' => $username,
'domain' => $domain,
'password' => $password,
}
);
if ( $rv->{'error'} ) {
#handle login error...
} else {
#successful login
my $session_id = $rv->{'session_id'};
}
my $customer_info = customer_info( { 'session_id' => $session_id } );
#payment_info and process_payment are available in 1.5+ only
my $payment_info = payment_info( { 'session_id' => $session_id } );
#!!! process_payment example
#!!! list_pkgs example
#!!! order_pkg example
#!!! cancel_pkg example
# signup functionality
use FS::SelfService qw( signup_info new_customer );
my $signup_info = signup_info;
$rv = new_customer( {
'first' => $first,
'last' => $last,
'company' => $company,
'address1' => $address1,
'address2' => $address2,
'city' => $city,
'state' => $state,
'zip' => $zip,
'country' => $country,
'daytime' => $daytime,
'night' => $night,
'fax' => $fax,
'payby' => $payby,
'payinfo' => $payinfo,
'paycvv' => $paycvv,
'paystart_month' => $paystart_month
'paystart_year' => $paystart_year,
'payissue' => $payissue,
'payip' => $payip
'paydate' => $paydate,
'payname' => $payname,
'invoicing_list' => $invoicing_list,
'referral_custnum' => $referral_custnum,
'pkgpart' => $pkgpart,
'username' => $username,
'_password' => $password,
'popnum' => $popnum,
'agentnum' => $agentnum,
}
);
my $error = $rv->{'error'};
if ( $error eq '_decline' ) {
print_decline();
} elsif ( $error ) {
reprint_signup();
} else {
print_success();
}
DESCRIPTION
Use this API to implement your own client "self-service" module.
If you just want to customize the look of the existing "self-service" module, see XXXX instead.
PASSWORD, GECOS, SHELL CHANGING FUNCTIONS
- passwd; chfn; chsh
"MY ACCOUNT" FUNCTIONS
- login HASHREF
- Creates a user session. Takes a hash reference as parameter with the following keys:
- username
- ; domain:; password
- Returns a hash reference with the following keys:
- error
- Empty on success, or an error message on errors.
- session_id
- Session identifier for successful logins
- customer_info HASHREF
- Returns general customer information.
- Takes a hash reference as parameter with a single key: session_id
- Returns a hash reference with the following keys:
- name
- Customer name
- balance
- Balance owed
- open
- Array reference of hash references of open inoices. Each hash reference has the following keys: invnum, date, owed
- small_custview
- An HTML fragment containing shipping and billing addresses.
- The following fields are also returned: first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax payby payinfo payname month year invoicing_list postal_invoicing; edit_info HASHREF
- Takes a hash reference as parameter with any of the following keys:
- first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax payby payinfo paycvv payname month year invoicing_list postal_invoicing
- If a field exists, the customer record is updated with the new value of that field. If a field does not exist, that field is not changed on the customer record.
- Returns a hash reference with a single key, error, empty on success, or an error message on errors
- invoice HASHREF
- Returns an invoice. Takes a hash reference as parameter with two keys: session_id and invnum
- Returns a hash reference with the following keys:
- error
- Empty on success, or an error message on errors
- invnum
- Invoice number
- invoice_text
- Invoice text
- list_invoices HASHREF
- Returns a list of all customer invoices. Takes a hash references with a single key, session_id.
- Returns a hash reference with the following keys:
- error
- Empty on success, or an error message on errors
- invoices
- Reference to array of hash references with the following keys:
- invnum
- Invoice ID
- _date
- Invoice date, in UNIX epoch time
- cancel HASHREF
- Cancels this customer.
- Takes a hash reference as parameter with a single key: session_id
- Returns a hash reference with a single key, error, which is empty on success or an error message on errors.
- payment_info HASHREF
- Returns information that may be useful in displaying a payment page.
- Takes a hash reference as parameter with a single key: session_id.
- Returns a hash reference with the following keys:
- error
- Empty on success, or an error message on errors
- balance
- Balance owed
- payname
- Exact name on credit card (CARD/DCRD)
- address1
- ; address2:; city:; state:; zip:; payby
- Customer's current default payment type.
- card_type
- For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
- payinfo
- For CARD/DCRD payment types, the card number
- month
- For CARD/DCRD payment types, expiration month
- year
- For CARD/DCRD payment types, expiration year
- cust_main_county
- County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see FS::cust_main_county). Note these are not FS::cust_main_county objects, but hash references of columns and values.
- states
- Array reference of all states in the current default country.
- card_types
- Hash reference of card types; keys are card types, values are the exact strings passed to the process_payment function
- paybatch
- Unique transaction identifier (prevents multiple charges), passed to the process_payment function
- process_payment HASHREF
- Processes a payment and possible change of address or payment type. Takes a hash reference as parameter with the following keys:
- session_id
- ; save
- If true, address and card information entered will be saved for subsequent transactions.
- auto
- If true, future credit card payments will be done automatically (sets payby to CARD). If false, future credit card payments will be done on-demand (sets payby to DCRD). This option only has meaning if save is set true.
- payname
- ; address1:; address2:; city:; state:; zip:; payinfo
- Card number
- month
- Card expiration month
- year
- Card expiration year
- paybatch
- Unique transaction identifier, returned from the payment_info function. Prevents multiple charges.
- Returns a hash reference with a single key, error, empty on success, or an error message on errors
- list_pkgs
- Returns package information for this customer.
- Takes a hash reference as parameter with a single key: session_id
- Returns a hash reference containing customer package information. The hash reference contains the following keys:
- cust_pkg HASHREF
- Array reference of hash references, each of which has the fields of a cust_pkg record (see FS::cust_pkg) as well as the fields below. Note these are not the internal FS:: objects, but hash references of columns and values.
- all fields of part_pkg (XXXpare this down to a secure subset)
- ; part_svc - An array of hash references, each of which has the following keys:::; all fields of part_svc (XXXpare this down to a secure subset)::; avail:; error
- Empty on success, or an error message on errors.
- order_pkg
- Orders a package for this customer.
- Takes a hash reference as parameter with the following keys:
- session_id
- ; pkgpart:; svcpart
- optional svcpart, required only if the package definition does not contain one svc_acct service definition with quantity 1 (it may contain others with quantity >1)
- username
- ; _password:; sec_phrase:; popnum
- Returns a hash reference with a single key, error, empty on success, or an error message on errors. The special error '_decline' is returned for declined transactions.
- cancel_pkg
- Cancels a package for this customer.
- Takes a hash reference as parameter with the following keys:
- session_id
- ; pkgpart
- Returns a hash reference with a single key, error, empty on success, or an error message on errors.
SIGNUP FUNCTIONS
- signup_info HASHREF
- Takes a hash reference as parameter with the following keys:
- session_id - Optional agent/reseller interface session
- Returns a hash reference containing information that may be useful in displaying a signup page. The hash reference contains the following keys:
- cust_main_county
- County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see FS::cust_main_county). Note these are not FS::cust_main_county objects, but hash references of columns and values.
- part_pkg
- Available packages - array reference of hash references, each of which has the fields of a part_pkg record (see 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 "payby" in FS/part pkg|FS::part_pkg#payby|"payby" in FS::part_pkg). 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, or an agentnum specified explicitly via reseller interface session_id in the options.
- agent
- Array reference of hash references, each of which has the fields of an agent record (see FS::agent). Note these are not FS::agent objects, but hash references of columns and values.
- agentnum2part_pkg
- 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.
- svc_acct_pop
- Access numbers - array reference of hash references, each of which has the fields of an svc_acct_pop record (see FS::svc_acct_pop). Note these are not FS::svc_acct_pop objects, but hash references of columns and values.
- security_phrase
- True if the "security_phrase" feature is enabled
- payby
- Array reference of acceptable payment types for signup
- CARD (credit card - automatic)
- :; DCRD (credit card - on-demand - version 1.5+ only)::; CHEK (electronic check - automatic)::; DCHK (electronic check - on-demand - version 1.5+ only)::; LECB (Phone bill billing)::; BILL (billing, not recommended for signups)::; COMP (free, definately not recommended for signups)::; PREPAY (special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL):; cvv_enabled
- True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
- msgcat
- 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".
- statedefault
- Default state
- countrydefault
- Default country
- new_customer HASHREF
- Creates a new customer. Takes a hash reference as parameter with the following keys:
- first - first name (required)
- ; last - last name (required):; ss (not typically collected; mostly used for ACH transactions):; company:; address1 (required):; address2:; city (required):; county:; state (required):; zip (required):; daytime - phone:; night - phone:; fax - phone:; payby - CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see "signup_info" (required):; payinfo - Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL:; paycvv - Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch):; paydate - Expiration date for CARD/DCRD:; payname - Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK:; 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),:; referral_custnum - referring customer number:; pkgpart - pkgpart of initial package:; username:; _password:; sec_phrase - security phrase:; popnum - access number (index, not the literal number):; agentnum - agent number
- Returns a hash reference with the following keys:
- 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); regionselector HASHREF | LIST
- Takes as input a hashref or list of key/value pairs with the following keys:
- selected_county
- ; selected_state:; selected_country:; prefix - Specify a unique prefix string if you intend to use the HTML output multiple time son one page.:; onchange - Specify a javascript subroutine to call on changes:; default_state:; default_country:; locales - An arrayref of hash references specifying regions. Normally you can just pass the value of the cust_main_county field returned by signup_info.
- Returns a list consisting of three HTML fragments for county selection, state selection and country selection, respectively.
- expselect PREFIX [ DATE ]
- Takes as input a unique prefix string and the current expiration date, in yyyy-mm-dd or m-d-yyyy format
- Returns an HTML fragments for expiration date selection.
- popselector HASHREF | LIST
- Takes as input a hashref or list of key/value pairs with the following keys:
- popnum
- ; pops - An arrayref of hash references specifying access numbers. Normally you can just pass the value of the svc_acct_pop field returned by signup_info.
- Returns an HTML fragment for access number selection.
RESELLER FUNCTIONS
Note: Resellers can also use the signup_info and new_customer functions with their active session, and the customer_info and order_pkg functions with their active session and an additional custnum parameter.
- agent_login; agent_info; agent_list_customers
