Freeside:3:Documentation:Developer/FS/SelfService

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 );

 #new-style login with an email address and password
 # can also be used for svc_acct login, set $emailaddress to username@domain
 my $rv = login ( { 'email'    => $emailaddress,
                    'password' => $password,
                  },
                );
 if ( $rv->{'error'} ) {
   #handle login error...
 } else {
   #successful login
   $session_id = $rv->{'session_id'};
 }

 #classic svc_acct-based login with separate username and password
 my $rv = login( { 'username' => $username,
                   'domain'   => $domain,
                   'password' => $password,
                 }
               );
 if ( $rv->{'error'} ) {
   #handle login error...
 } else {
   #successful login
   $session_id = $rv->{'session_id'};
 }

 #svc_phone login with phone number and PIN
 my $rv = login( { 'username' => $phone_number,
                   'domain'   => 'svc_phone',
                   'password' => $pin,
                 }
               );
 if ( $rv->{'error'} ) {
   #handle login error...
 } else {
   #successful login
   $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,
                       'agentnum'         => $agentnum,
                       'pkgpart'          => $pkgpart,

                       'username'         => $username,
                       '_password'        => $password,
                       'popnum'           => $popnum,
                       #OR
                       'countrycode'      => 1,
                       'phonenum'         => $phonenum,
                       'pin'              => $pin,
                     }
                   );
 
 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

Changes the password for an existing user in svc_acct. Takes a hash reference with the following keys:

username: Username of the account (required)
domain: Domain of the account (required)
old_password: Old password (required)
new_password: New password (required)
new_gecos: New gecos
new_shell: New Shell
chfn: ; chsh

"MY ACCOUNT" FUNCTIONS

login HASHREF

Creates a user session. Takes a hash reference as parameter with the following keys:

email: Email address (username@domain), instead of username and domain. Required for contact-based self-service login, can also be used for svc_acct-based login.
username: Username
domain: Domain
password: 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: Address line one
address2: Address line two
city: City
state: State
zip: Zip or postal code
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

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: Session identifier
amount: Amount
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: Name on card
address1: Address line one
address2: Address line two
city: City
state: State
zip: Zip or postal code
country: Two-letter country code
payinfo: Card number
month: Card expiration month
year: Card expiration year

Returns a hash reference with a single key, error, empty on success, or an error message on errors.
process_payment_order_pkg: Combines the process_payment and order_pkg functions in one step. If the payment processes sucessfully, the package is ordered. Takes a hash reference as parameter with the keys of both methods.

Returns a hash reference with a single key, error, empty on success, or an error message on errors.
process_payment_change_pkg: Combines the process_payment and change_pkg functions in one step. If the payment processes sucessfully, the package is ordered. Takes a hash reference as parameter with the keys of both methods.

Returns a hash reference with a single key, error, empty on success, or an error message on errors.
process_payment_order_renew: Combines the process_payment and order_renew functions in one step. If the payment processes sucessfully, the renewal is processed. Takes a hash reference as parameter with the keys of both methods.

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. For more detail on services, see "list_svcs".

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:

custnum

Customer number

error

Empty on success, or an error message on errors.

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.

part_pkg fields

All fields of part_pkg for this specific cust_pkg (be careful with this information - it may reveal more about your available packages than you would like users to know in aggregate)

part_svc

An array of hash references indicating information on unprovisioned services available for provisioning for this specific cust_pkg. Each has the following keys:

part_svc fields: All fields of part_svc (be careful with this information - it may reveal more about your available packages than you would like users to know in aggregate)

cust_svc

An array of hash references indicating information on the customer services already provisioned for this specific cust_pkg. Each has the following keys:

label: Array reference with three elements: The first element is the name of this service. The second element is a meaningful user-specific identifier for the service (i.e. username, domain or mail alias). The last element is the table name of this service.

svcnum: Primary key for this service
svcpart: Service definition (see FS::part_svc)
pkgnum: Customer package (see FS::cust_pkg)
overlimit: Blank if the service is not over limit, or the date the service exceeded its usage limit (as a UNIX timestamp).

list_svcs: Returns service 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:

custnum

Customer number

svcs

An array of hash references indicating information on all of this customer's services. Each has the following keys:

svcnum: Primary key for this service
label: Name of this service
value: Meaningful user-specific identifier for the service (i.e. username, domain, or mail alias).

Account (svc_acct) services also have the following keys:

username: Username
email: username@domain
seconds: Seconds remaining
upbytes: Upload bytes remaining
downbytes: Download bytes remaining
totalbytes: Total bytes remaining
recharge_amount: Cost of a recharge
recharge_seconds: Number of seconds gained by recharge
recharge_upbytes: Number of upload bytes gained by recharge
recharge_downbytes: Number of download bytes gained by recharge
recharge_totalbytes: Number of total bytes gained by recharge

order_pkg: Orders a package for this customer.

Takes a hash reference as parameter with the following keys:

session_id: Session identifier
pkgpart: Package to order (see FS::part_pkg).
quantity: Quantity for this package order (default 1).
locationnum: Optional locationnum for this package order, for existing locations.

Or, for new locations, pass the following fields: address1*, address2, city*, county, state*, zip*, country. (* = required in this case)
address1: ; address 2:; city:; :; svcpart; Service to order (see FS::part_svc).

Normally optional; required only to provision a non-svc_acct service, or if the package definition does not contain one svc_acct service definition with quantity 1 (it may contain others with quantity >1). A svcpart of "none" can also be specified to indicate that no initial service should be provisioned.

Fields used when provisioning an svc_acct service:

username: Username
_password: Password
sec_phrase: Optional security phrase
popnum: Optional Access number number

Fields used when provisioning an svc_domain service:

domain: Domain

Fields used when provisioning an svc_phone service:

phonenum: Phone number
pin: Voicemail PIN
sip_password: SIP password

Fields used when provisioning an svc_external service:

id: External numeric ID.
title: External text title.

Fields used when provisioning an svc_pbx service:

id: Numeric ID.
name: Text name.

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.
change_pkg: Changes a package for this customer.

Takes a hash reference as parameter with the following keys:

session_id: Session identifier
pkgnum: Existing customer package.
pkgpart: New package to order (see FS::part_pkg).

Returns a hash reference with the following keys:

error: Empty on success, or an error message on errors.
pkgnum: On success, the new pkgnum

renew_info: Provides useful info for early renewals.

Takes a hash reference as parameter with the following keys:

session_id: Session identifier

Returns a hash reference. On errors, it contains a single key, error, with the error message. Otherwise, contains a single key, dates, pointing to an array refernce of hash references. Each hash reference contains the following keys:

bill_date: (Future) Bill date. Indicates a future date for which billing could be run. Specified as a integer UNIX timestamp. Pass this value to the order_renew function.
bill_date_pretty: (Future) Bill date as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)
amount: Base amount which will be charged if renewed early as of this date.
renew_date: Renewal date; i.e. even-futher future date at which the customer will be paid through if the early renewal is completed with the given bill-date. Specified as a integer UNIX timestamp.
renew_date_pretty: Renewal date as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)
pkgnum: Package that will be renewed.
expire_date: Expiration date of the package that will be renewed.
expire_date_pretty: Expiration date of the package that will be renewed, as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)

order_renew: Renews this customer early; i.e. runs billing for this customer in advance.

Takes a hash reference as parameter with the following keys:

session_id: Session identifier
date: Integer date as returned by the renew_info function, indicating the advance date for which to run billing.

Returns a hash reference with a single key, error, empty on success, or an error message on errors.
cancel_pkg: Cancels a package for this customer.

Takes a hash reference as parameter with the following keys:

session_id: Session identifier
pkgpart: pkgpart of package to cancel

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, definitely 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: Company name
address1 (required): Address line one
address2: Address line two
city (required): City
county: County
state (required): State
zip (required): Zip or postal code
daytime: Daytime phone number
night: Evening phone number
fax: Fax number
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
agentnum: Agent number
pkgpart: pkgpart of initial package
username: Username
_password: Password
sec_phrase: Security phrase
popnum: Access number (index, not the literal number)
countrycode: Country code (to be provisioned as a service)
phonenum: Phone number (to be provisioned as a service)
pin: Voicemail PIN

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 Configuration | View/Edit message catalog)

regionselector HASHREF | LIST

Takes as input a hashref or list of key/value pairs with the following keys:

selected_county: Currently selected county
selected_state: Currently selected state
selected_country: Currently 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 state
default_country: 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.

location_form HASHREF | LIST

Takes as input a hashref or list of key/value pairs with the following keys:

session_id: Current customer session_id
no_asterisks: Omit red asterisks from required fields.
address1_label: Label for first address line.

Returns an HTML fragment for a location form (address, city, state, zip, country)
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: Access number number
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.

domainselector HASHREF | LIST

Takes as input a hashref or list of key/value pairs with the following keys:

pkgnum: Package number
domsvc: Service number of the selected item.

Returns an HTML fragment for domain selection.

didselector HASHREF | LIST

Takes as input a hashref or list of key/value pairs with the following keys:

field: Field name for the returned HTML fragment.
svcpart: Service definition (see FS::part_svc)

Returns an HTML fragment for DID 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.

For the most part, development of the reseller web interface has been superceded by agent-virtualized access to the backend.

agent_login: Agent login
agent_info: Agent info
agent_list_customers: List agent's customers.

BUGS

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 357:: You forgot a '=back' before '=head1'

Freeside:3:Documentation:Developer/FS/SelfService

Contents

NAME

SYNOPSIS

DESCRIPTION

PASSWORD, GECOS, SHELL CHANGING FUNCTIONS

"MY ACCOUNT" FUNCTIONS

SIGNUP FUNCTIONS

RESELLER FUNCTIONS

BUGS

SEE ALSO

POD ERRORS

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools