Difference between revisions of "Freeside:1.9:Documentation:Developer/FS/SelfService"
From Freeside
(import from POD) |
m (Edit via perl MediaWiki framework (1.13)) |
||
(26 intermediate revisions by the same user not shown) | |||
Line 65: | Line 65: | ||
'invoicing_list' => $invoicing_list, | 'invoicing_list' => $invoicing_list, | ||
'referral_custnum' => $referral_custnum, | 'referral_custnum' => $referral_custnum, | ||
+ | 'agentnum' => $agentnum, | ||
'pkgpart' => $pkgpart, | 'pkgpart' => $pkgpart, | ||
+ | |||
'username' => $username, | 'username' => $username, | ||
'_password' => $password, | '_password' => $password, | ||
'popnum' => $popnum, | 'popnum' => $popnum, | ||
− | ' | + | #OR |
+ | 'countrycode' => 1, | ||
+ | 'phonenum' => $phonenum, | ||
+ | 'pin' => $pin, | ||
} | } | ||
); | ); | ||
Line 92: | Line 97: | ||
; login HASHREF | ; login HASHREF | ||
:Creates a user session. Takes a hash reference as parameter with the following keys: | :Creates a user session. Takes a hash reference as parameter with the following keys: | ||
− | :; username:; domain:; password | + | :; username |
+ | ::Username | ||
+ | :; domain | ||
+ | ::Domain | ||
+ | :; password | ||
+ | ::Password | ||
+ | |||
:Returns a hash reference with the following keys: | :Returns a hash reference with the following keys: | ||
:; error | :; error | ||
Line 112: | Line 123: | ||
:; small_custview | :; small_custview | ||
::An HTML fragment containing shipping and billing addresses. | ::An HTML fragment containing shipping and billing addresses. | ||
− | :; The following fields are also returned | + | :; 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: | :Takes a hash reference as parameter with any of the following keys: | ||
Line 160: | Line 173: | ||
:; payname | :; payname | ||
::Exact name on credit card (CARD/DCRD) | ::Exact name on credit card (CARD/DCRD) | ||
− | :; address1:; address2:; city:; state:; zip:; payby | + | :; address1 |
+ | ::Address line one | ||
+ | :; address2 | ||
+ | ::Address line two | ||
+ | :; city | ||
+ | ::City | ||
+ | :; state | ||
+ | ::State | ||
+ | :; zip | ||
+ | ::Zip or postal code | ||
+ | :; payby | ||
::Customer's current default payment type. | ::Customer's current default payment type. | ||
:; card_type | :; card_type | ||
Line 176: | Line 199: | ||
:; card_types | :; card_types | ||
::Hash reference of card types; keys are card types, values are the exact strings passed to the process_payment function | ::Hash reference of card types; keys are card types, values are the exact strings passed to the process_payment function | ||
− | |||
− | |||
; process_payment HASHREF | ; process_payment HASHREF | ||
:Processes a payment and possible change of address or payment type. Takes a hash reference as parameter with the following keys: | :Processes a payment and possible change of address or payment type. Takes a hash reference as parameter with the following keys: | ||
− | :; session_id:; save | + | :; session_id |
+ | ::Session identifier | ||
+ | :; amount | ||
+ | ::Amount | ||
+ | :; save | ||
::If true, address and card information entered will be saved for subsequent transactions. | ::If true, address and card information entered will be saved for subsequent transactions. | ||
:; auto | :; 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. | ::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 | + | :; payname |
+ | ::Name on card | ||
+ | :; address1 | ||
+ | ::Address line one | ||
+ | :; address2 | ||
+ | ::Address line two | ||
+ | :; city | ||
+ | ::City | ||
+ | :; state | ||
+ | ::State | ||
+ | :; zip | ||
+ | ::Zip or postal code | ||
+ | :; payinfo | ||
::Card number | ::Card number | ||
:; month | :; month | ||
Line 190: | Line 227: | ||
:; year | :; year | ||
::Card expiration year | ::Card expiration year | ||
− | |||
− | |||
− | :Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors | + | :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_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 | ; list_pkgs | ||
− | :Returns package information for this customer. | + | :Returns package information for this customer. For more detail on services, see [[#list_svcs|"list_svcs"]]. |
:Takes a hash reference as parameter with a single key: '''session_id''' | :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: | :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 | :; cust_pkg HASHREF | ||
::Array reference of hash references, each of which has the fields of a cust_pkg record (see [[Freeside:1.9:Documentation:Developer/FS/cust pkg|FS::cust_pkg]]) as well as the fields below. Note these are not the internal FS:: objects, but hash references of columns and values. | ::Array reference of hash references, each of which has the fields of a cust_pkg record (see [[Freeside:1.9:Documentation:Developer/FS/cust pkg|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 [[Freeside:1.9:Documentation:Developer/FS/part svc|FS::part_svc]]) | ||
+ | ::; pkgnum | ||
+ | :::Customer package (see [[Freeside:1.9:Documentation:Developer/FS/cust pkg|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 | ; order_pkg | ||
:Orders a package for this customer. | :Orders a package for this customer. | ||
:Takes a hash reference as parameter with the following keys: | :Takes a hash reference as parameter with the following keys: | ||
− | :; session_id:; pkgpart:; svcpart | + | :; session_id |
− | ::optional | + | ::Session identifier |
− | :; username:; _password:; sec_phrase:; popnum | + | :; pkgpart |
+ | ::Package to order (see [[Freeside:1.9:Documentation:Developer/FS/part pkg|FS::part_pkg]]). | ||
+ | :; svcpart | ||
+ | ::Service to order (see [[Freeside:1.9:Documentation:Developer/FS/part svc|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. | ||
+ | |||
: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. | :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. | ||
+ | ; 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.) | ||
+ | ; 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 | ; cancel_pkg | ||
:Cancels a package for this customer. | :Cancels a package for this customer. | ||
:Takes a hash reference as parameter with the following keys: | :Takes a hash reference as parameter with the following keys: | ||
− | :; session_id:; pkgpart | + | :; 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. | :Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors. | ||
Line 238: | Line 407: | ||
:; payby | :; payby | ||
::Array reference of acceptable payment types for signup | ::Array reference of acceptable payment types for signup | ||
− | ::; CARD | + | ::; 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) | ::True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch) | ||
:; msgcat | :; msgcat | ||
Line 248: | Line 433: | ||
; new_customer HASHREF | ; new_customer HASHREF | ||
:Creates a new customer. Takes a hash reference as parameter with the following keys: | :Creates a new customer. Takes a hash reference as parameter with the following keys: | ||
− | :; first | + | :; 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|"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: | :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 | + | :; 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: | :Takes as input a hashref or list of key/value pairs with the following keys: | ||
− | :; selected_county:; selected_state:; selected_country:; prefix | + | :; 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. | :Returns a list consisting of three HTML fragments for county selection, state selection and country selection, respectively. | ||
; expselect PREFIX [ DATE ] | ; expselect PREFIX [ DATE ] | ||
Line 260: | Line 521: | ||
; popselector HASHREF | LIST | ; popselector HASHREF | LIST | ||
:Takes as input a hashref or list of key/value pairs with the following keys: | :Takes as input a hashref or list of key/value pairs with the following keys: | ||
− | :; popnum:; pops | + | :; 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. | :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 [[Freeside:1.9:Documentation:Developer/FS/part svc|FS::part_svc]]) | ||
+ | |||
+ | :Returns an HTML fragment for DID selection. | ||
==RESELLER FUNCTIONS== | ==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. | 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 | + | 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== | ==BUGS== | ||
==SEE ALSO== | ==SEE ALSO== | ||
− | [[Freeside:1.9:Documentation:Developer/freeside-selfservice-clientd|freeside-selfservice-clientd]], [[Freeside:1.9:Documentation:Developer/freeside-selfservice-server|freeside-selfservice-server]] | + | [[Freeside:1.9:Documentation:Developer/bin/freeside-selfservice-clientd|freeside-selfservice-clientd]], [[Freeside:1.9:Documentation:Developer/bin/freeside-selfservice-server|freeside-selfservice-server]] |
Latest revision as of 13:16, 7 February 2009
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, '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; chfn; chsh
"MY ACCOUNT" FUNCTIONS
- login HASHREF
- Creates a user session. Takes a hash reference as parameter with the following keys:
- 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
- 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_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).
- 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.
- 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.
- 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.)
- 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.
- 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.