Freeside:4:Documentation:Developer/FS/SelfService
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 ); #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 #ordering a package with an svc_acct service my $rv = order_pkg( { 'session_id' => $session_id, 'pkgpart' => $pkgpart, 'svcpart' => $svcpart, 'username' => $username, 'domsvc' => $domsvc, #svcnum of svc_domain '_password' => $password, } ); #!!! ordering a package with an svc_domain service example #!!! ordering a package with an svc_phone service example #!!! ordering a package with an svc_external service example #!!! ordering a package with an svc_pbx service #ordering a package with no service my $rv = order_pkg( { 'session_id' => $session_id, 'pkgpart' => $pkgpart, 'svcpart' => 'none', } ); #quoting a package, then ordering after confirmation my $rv = quotation_new({ 'session_id' => $session_id }); my $qnum = $rv->{quotationnum}; # add packages to the quotation $rv = quotation_add_pkg({ 'session_id' => $session_id, 'quotationnum' => $qnum, 'pkgpart' => $pkgpart, 'quantity' => $quantity, # defaults to 1 }); # repeat until all packages are added # view the pricing information $rv = quotation_info({ 'session_id' => $session_id, 'quotationnum' => $qnum, }); print "Total setup charges: ".$rv->{total_setup}."\n". "Total recurring charges: ".$rv->{total_recur}."\n"; # quotation_info also provides a detailed breakdown of charges, in # $rv->{sections}. # ask customer for confirmation, then: $rv = quotation_order({ 'session_id' => $session_id, 'quotationnum' => $qnum, }); #!!! cancel_pkg example # signup functionality use FS::SelfService qw( signup_info new_customer new_customer_minimal ); 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 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 reference 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
- list_payby HASHREF
- Returns a list of all stored customer payment information (credit cards and electronic check accounts). Takes a hash reference with a single key, session_id.
- Returns a hash reference with the following keys:
- error
- Empty on success, or an error message on errors
- payby
- Reference to array of hash references with the following keys:
- custpaybynum
- :; weight
- Numeric weighting. Stored payment information with a lower weight is attempted first.
- payby
- CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD (on-demand credit card) or DCHK (on-demand electronic check).
- paymask
- Masked credit card number (or, masked account and routing numbers)
- paydate
- Credit card expiration date
- payname
- Exact name on card (or bank name, for electronic checks)
- paystate
- For electronic checks, bank state
- paytype
- For electronic checks, account type (Personal/Business, Checking/Savings)
- insert_payby HASHREF
- Adds new stored payment information for this customer. Takes a hash reference with the following keys:
- session_id
- ; weight
- Numeric weighting. Stored payment information with a lower weight is attempted first.
- payby
- CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD (on-demand credit card) or DCHK (on-demand electronic check).
- payinfo
- Credit card number (or electronic check "account@routing")
- paycvv
- CVV2 number / security code
- paydate
- Credit card expiration date
- payname
- Exact name on card (or bank name, for electronic checks)
- paystate
- For electronic checks, bank state
- paytype
- For electronic checks, account type (i.e. "Personal Savings", "Personal Checking", "Business Checking")A
- payip
- Optional IP address from which payment was submitted
- If there is an error, returns a hash reference with a single key, error, otherwise returns a hash reference with a single key, custpaybynum.
- update_payby HASHREF
- Updates stored payment information for this customer. Takes a hash reference with the following keys:
- custpaybynum
- ID of stored payment information to update
- session_id
- ; weight
- Numeric weighting. Stored payment information with a lower weight is attempted first.
- payby
- CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD (on-demand credit card) or DCHK (on-demand electronic check).
- payinfo
- Credit card number (or electronic check "account@routing")
- paycvv
- CVV2 number / security code
- paydate
- Credit card expiration date
- payname
- Exact name on card (or bank name, for electronic checks)
- paystate
- For electronic checks, bank state
- paytype
- For electronic checks, account type (i.e. "Personal Savings", "Personal Checking", "Business Checking")A
- payip
- Optional IP address from which payment was submitted
- All keys except sessionid and custpaybynum are optional; if omitted, the previous values in the record will be preserved.
- If there is an error, returns a hash reference with a single key, error, otherwise returns a hash reference with a single key, custpaybynum.
- delete_payby HASHREF
- Removes stored payment information. Takes a hash reference with two keys, session_id and custpaybynum. Returns a hash reference with a single key, error, which is an error message or empty for successful removal.
- 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
- 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
- Account (svc_acct) services also have the following keys:
- 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).
- quantity
- Quantity for this package order (default 1).
- 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.
- provision_acct
- Provisions an account (svc_acct).
- Takes a hash reference as parameter with the following keys:
- session_id
- Session identifier
- pkgnum
- pkgnum of package into which this service is provisioned
- svcpart
- svcpart or service definition to provision
- username
- ; domsvc:; _password; provision_phone
- Provisions a phone number (svc_phone).
- Takes a hash reference as parameter with the following keys:
- session_id
- Session identifier
- pkgnum
- pkgnum of package into which this service is provisioned
- svcpart
- svcpart or service definition to provision
- countrycode
- ; phonenum:; address1:; address2:; city:; county:; state:; zip:; country
- E911 Address (optional)
- provision_pbx
- Provisions a customer PBX (svc_pbx).
- Takes a hash reference as parameter with the following keys:
- session_id
- Session identifier
- pkgnum
- pkgnum of package into which this service is provisioned
- svcpart
- svcpart or service definition to provision
- id
- ; title:; max_extensions:; max_simultaneous:; ip_addr; provision_external
- Provisions an external service (svc_external).
- Takes a hash reference as parameter with the following keys:
- session_id
- Session identifier
- pkgnum
- pkgnum of package into which this service is provisioned
- svcpart
- svcpart or service definition to provision
- id
- ; title
"MY ACCOUNT" CONTACT FUNCTIONS
- contact_passwd
- Changes the password for the currently-logged in contact.
- Takes a hash reference as parameter with the following keys:
- session_id
- ; new_password
- Returns a hash reference with a single parameter, error, which contains an error message, or empty on success.
- list_contacts
- Takes a hash reference as parameter with a single key, session_id.
- Returns a hash reference with two parameters: error, which contains an error message, or empty on success, and contacts, a list of contacts.
- contacts is an array reference of hash references (i.e. an array of structs, in XML-RPC). Each hash reference (struct) has the following keys:
- contactnum; class
- Contact class name (contact type).
- first
- First name
- last
- Last name
- title
- Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.")
- emailaddress
- Comma-separated list of email addresses
- comment; selfservice_access
- Y when enabled
- edit_contact
- Updates information for the currently-logged in contact, or (optionally) the specified contact.
- Takes a hash reference as parameter with the following keys:
- session_id
- ; contactnum
- If already logged in as a contact, this is optional.
- first
- ; last:; emailaddress
- Returns a hash reference with a single parameter, error, which contains an error message, or empty on success.
- new_contact
- Creates a new contact.
- Takes a hash reference as parameter with the following keys:
- session_id
- ; first:; last:; emailaddress:; classnum
- Optional contact classnum (TODO: or name)
- comment
- ; selfservice_access
- Y to enable self-service access
- _password
- Returns a hash reference with a single parameter, error, which contains an error message, or empty on success.
- delete_contact
- Deletes a contact. (Note: Cannot at this time delete the currently-logged in contact.)
- Takes a hash reference as parameter with the following keys:
- session_id
- ; contactnum
- Returns a hash reference with a single parameter, error, which contains an error message, or empty on success.
"MY ACCOUNT" QUOTATION FUNCTIONS
All of these functions require the user to be logged in, and the 'session_id' key to be included in the argument hashref.`
- list_quotations HASHREF
- Returns a hashref listing this customer's active self-service quotations. Contents are:
- quotations
- an arrayref containing an element for each quotation.
- quotationnum
- the primary key
- _date
- the date it was started
- num_pkgs
- the number of packages
- total_setup
- the sum of setup fees
- total_recur
- the sum of recurring charges
- quotation_new HASHREF
- Creates an empty quotation and returns a hashref containing 'quotationnum', the primary key of the new quotation.
- quotation_delete HASHREF
- Disables (does not really delete) a quotation. Takes the following arguments:
- session_id
- ; quotationnum - the quotation to delete
- Returns 'error' => a string, which will be empty on success.
- quotation_info HASHREF
- Returns total and detailed pricing information on a quotation.
- Takes the following arguments:
- session_id
- ; quotationnum - the quotation to return
- Returns a hashref containing:
- - total_setup, the total of setup fees (and their taxes) - total_recur, the total of all recurring charges (and their taxes) - sections, an arrayref containing an element for each quotation section. - description, a line of text describing the group of charges - subtotal, the total of charges in this group (if appropriate) - detail_items, an arrayref of line items - pkgnum, the reference number of the package - description, the package name (or tax name) - quantity - amount, the amount charged If the detail item represents a subtotal, it will instead contain: - total_item: description of the subtotal - total_amount: the subtotal amount
- quotation_print HASHREF
- Renders the quotation as HTML or PDF. Takes the following arguments:
- session_id
- ; quotationnum - the quotation to return:; format - 'html' or 'pdf'
- Returns a hashref containing 'document', the contents of the file.
- quotation_add_pkg HASHREF
- Adds a package to a quotation. Takes the following arguments:
- session_id
- ; pkgpart - the package to add:; quotationnum - the quotation to add it to:; quantity - the package quantity (defaults to 1):; address1, address2, city, state, zip, country - address fields to set the service location
- Returns 'error' => a string, which will be empty on success.
- quotation_remove_pkg HASHREF
- Removes a package from a quotation. Takes the following arguments:
- session_id
- ; pkgnum - the primary key (quotationpkgnum) of the package to remove:; quotationnum - the quotation to remove it from
- Returns 'error' => a string, which will be empty on success.
- quotation_order HASHREF
- Converts the packages in a quotation into real packages. Takes the following arguments:
- Takes the following arguments:
- session_id
- ; quotationnum - the quotation to order
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_minimal HASHREF
- Creates a new customer.
- Current differences from new_customer: An address is not required. promo_code and reg_code are not supported. If invoicing_list and _password is passed, a contact will be created with self-service access (no pkgpart or username is necessary). No initial billing is run (this may change in a future version).
- 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
- Address line one
- address2
- Address line two
- city
- City
- county
- County
- state
- State
- zip
- 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)
- 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
SEE ALSO
freeside-selfservice-clientd, freeside-selfservice-server
POD ERRORS
Hey! The above document had some coding errors, which are explained below:
- Around line 1503:
- Unknown directive: =over4
- Around line 1535:
- '=item' outside of any '=over'
- Around line 1612:
- You forgot a '=back' before '=head2'
- Around line 1757:
- '=item' outside of any '=over'