March 23, 2015 - Shortcodes, Tech-Admin

Used to create a confirmation screen that allows a visitor to proceed to the TouchNet payment system. The system can use a custom Formidable "View" or will use a default generic view.

The Form "TouchNet payment button setup values" will (eventually) give a third option for passing in Payment Confirmation screen parameters, but for now, custom views and/or passed-in values will be used.

See the end-user instruction for creating a form and/or view.

The shortcode attributes can pass in any value that is contained in the confirmation form view, so the tag:

[touchnet_pay due=700]

Would replace the "[due]" placeholder in the view with "700". Note that the passed-in attributes are processed first, and since the placeholders are removed and replaced with the passed-in values, any other values (i.e. from the submitted data) cannot be placed into the view.

Tech docs

In the "View" paramenter, "frm_key" is the "Form Key" assigned in building the form. The whole parameter is the field key of the corresponding field.

"View" parameter TouchNet "Post" parameter decsription
frm_key_name BILL_NAME Used to pass the billing name.
frm_key_email BILL_EMAIL_ADDRESS Used to pass the billing email address.
frm_key_address BILL_STREET1 Used to pass the billing street address 1.
frm_key_address2 BILL_STREET2 Used to pass the billing street address 2.
frm_key_city BILL_CITY Used to pass the billing city.
frm_key_state BILL_STATE Used to pass the billing state.
frm_key_zip BILL_POSTAL_CODE Used to pass the billing postal code.
frm_key_country BILL_COUNTRY Used to pass the billing country.
form_key (internal pre-set) EXT_TRANS_ID Used as a cross reference between the external site and a uPay site.
frm_key_label EXT_TRANS_ID_LABEL Used to describe the EXT_TRANS_ID value on the payment receipt.
{calculated from
"frm_key_total" - "frm_key_payment"}
AMT Used to pass the amount to be paid.
frm_key_upay_id* UPAY_SITE_ID Used to select the uPay site.
frm_key_{item}_cost For an itemized list of charges
frm_key_{item}_qty To specify the quantity of the "item" ordered
frm_key_discount *** Not yet implemented - possible future feature If zero or not set, no discount
If contains "%" then a percentage off
otherwise, a dollars off discount
page_title The title, same as the form "Build" title (usually displayed in <h3> tag)
reg_link_class Used to hide the "Back" link if there is no link (set to 'frm-hide' or 'frm-show')
reg_page URL of registration page, defaults to referrer if current host (see more below)
go_back Text of link to go back to registration page, defaults to "Go back to the registration page"
url payment site address

 

* Note: The UPAY_SITE_ID can be set in the form if the default confirmation view is used, or it can be set in the shortcode as a "upay_id" attribute or in the custom view conformation screen.

The Formidable object $frm_entry->getOne($key, true); is used to retrieve the submission, with a similar fetch to get the "template" to display the amount owed, the button that sends the info to the correct uPay site, etc.

 Calculating values

Formidable has the ability to calculate values for form fields. It is recommended that this feature be used to calculate the amount for the "total" field. The total can be calculated by the [touchnet_pay] shortcode by using attributes or View fields that have form field keys ("View" parameter, above) that contain the following:

  • *_cost - the cost of an item/option
  • *_qty - how many of the item/option
  • *_total - the total amount of the transaction
  • *_payment - how much has already been received
  • due - the balance owed
  • *_discount is reserved for future use. For now, discounts can be calculated within Formidable.
reg_page link

A link back to the registration page can be generated automatically, only if the payment confirmation screen is reached from a page on InsideLaw. Since links to the payment confirmation screen might be from email, etc., there may be cases where the reg_page needs to be set in the View or the submitted data. If the page linked from is on InsideLaw, placeholder "[reg_link_class]" will be set to "frm-show" otherwise will be set to "frm-hide". See Display Control, below.

Display Control

Elements of your Payment Confirmation screen can be hidden on the screen or printed version using the following CSS classes:

  • frm-show - normal display (inherits visibility from "parent" element)
  • frm-hide - not shown at all (for "go back" links)
  • frm-printonly - to only show if printed
  • frm-noprint  - to show only on screen, but not printouts
  • frm-lbl - right-justified, bold
  • frm-number - right-justified (script attempts to format numbers as currency)

The CSS is inserted by the [touchnet_pay] shortcode itself.

Issues

So far, I cannot figure out a way for a person who is not logged in to return to their original form and edit/add/remove. The [allow_form_edit] shortcode allows for non-loggedin users to edit previous entries with teh use of an entry key.

In order to invite users back to update a previously filled form. We need a way to send out mass emails with user specific entry keys.

The 'Return to registration page' button doesn't work if the user isn't logged in. Had to use JavaScript instead in those circumstance.

Security is by obscurity

The Shortcodes UI PHP script must block all-numeric keys, as the $frm_entry->getOne($key, true); function will accept either the (random alpha-numeric) key or the (serial numeric) ID - leaving it much easier to snoop into other's orders/registrations. As far as I can tell, the "key" always contains alpha characters and is 6+ characters long (around 2 billion possible). Assuming there are 15,000 registration on file, the odds of randomly revealing one is about 145,000 to one, meaning that someone would need to try about 70,000 times to have a 50:50 chance of revealing one record. These are conservative, worst-case scenario numbers - in practice, the keys are often more than 6 characters long and we will likely never have as many as 15k entries on file at any given time.

InWork

In addition to avoiding the easy-to-guess serial numeric IDs, the $_GET['entry'] must be sanitized in general:

$key = sanitize_text_field( $_GET['entry'] );
if ( ctype_digit( $key ) ) { // don't allow purely numeric keys
 $key = '';
 $_GET['entry'] = '';
}

For a simple form, the output of "getOne" (important fields only shown) looks something like:

 

stdClass Object
(
 [id] => 3219
 [item_key] => qox9gl
 [name] => ABAC
 [description] => a:2:{s:7:"browser";s:105:"Mozilla/5.0 (X11; Linux ...Safari/537.36";s:8:"referrer";s:40:"https://insidelaw.gsu.edu/a-test-page/
";}
 [ip] => 131.96.253.112
 [form_id] => 23
 [post_id] => 0
 [user_id] => 2
...
 [form_name] => SIPJF School
 [form_key] => 31a5nf
 [metas] => Array
 (
   [jsm8uq] => ABAC
   [rqrr1q] => 8
   [p7nkx2] => 25
   [sipjf_sch_total] => 200
   [yy4v4q] => 2
 )
)

The [form_key] value is used to fetch the "template" - e.g. $frm_entry->getOne($form_key, true);

Want to be able to specify all  the parameters on our system, via post variables as follows:

TouchNet "Post" parameter  Function
CONTINUE_LINK_TEXT Used to pass the text for the continue link.
SUCCESS_LINK Used to pass a new url for the success link.
SUCCESS_LINK_TEXT Used to pass the text for the success link.
ERROR_LINK Used to pass a new url for the error link.
ERROR_LINK_TEXT Used to pass the text for the error link.
CANCEL_LINK Used to pass a new url for the cancel button.
CANCEL_LINK_TEXT Used to pass the text for the success button.
DEBIT_ACCT_CODE Used to pass an override value for the debit accounting code (which is configured in Payment Gateway as the Host Payment Method ID).

Accounting Code:       
2009 Corp. Intellectual  
Center for Metro Growth  
College of Law Revenue  
Conflict Mgmt Higher Ed  
IP Community Service Gala  
IP Job Fair  
Law Alumni Events  
Law Review Subscription  
Law Review Symposium  
Public Int. Law Assoc  
Registration Payments  
SOLO Practice Workshop  
Study Abroad - Int'l Comm  
Study Abroad - Istanbul  
Study Space Program  
[common] Temp. Marketplace Code  
CREDIT_ACCT_AMT If passing multiple accounting codes, used to pass the amount that associated to the corresponding credit account code (CREDIT_ACCT_CODE). Must have a corresponding credit account code (Example: CREDIT_ACCT_CODE). Additional credit account amounts may be passed using the same naming convention (Example: CREDIT_ACCT_AMT_2).
CREDIT_ACCT_CODE Overrides the uPay accounting code set at the site level. Must be populated if multiple account codes are passed.
CREDIT_ACCT_AMT_2 If passing multiple accounting codes, used to pass the amount that associated to the corresponding credit account code (CREDIT_ACCT_CODE_2). Must have a corresponding credit account code (Example: CREDIT_ACCT_CODE_2). Additional credit account amounts may be passed using the same naming convention (Example: CREDIT_ACCT_AMT_3).
CREDIT_ACCT_CODE_2 If passing multiple accounting codes, used to pass additional accounting codes. Must have a corresponding amount (Example: CREDIT_ACCT_AMT_2). Additional credit account codes may be passed using the same naming convention (Example: CREDIT_ACCT_CODE_3).
ADD_ON_OFFER_CREDIT_ACCT_CODE Used to pass an override value for the Additional Donation accounting code (only used if Additional Donation is enabled).

Change Log

July 8, 2015 added a 'start a new registration' button. (Edited both default generic view and shortcode)

Comments are closed.