Pre-fill form fields via URL parameters

Imagine the following business cases:

• A promotional email is sent to the customer linking a payment form on your website where the coupon is already applied.
• An email is sent to the customer linking your invoice payment form, and the email address, payment amount, and invoice reference number fields of the form are already filled in.
• A payment flow starts with user registration, then it lets the customer enter order-specific data on the next page, and finally the payment form is on the last page with email address and cardholder’s name prefilled.

WP Full Pay can be integrated into these and similar payment flows by using URL parameters and filter hooks.

In this article, we’ll describe the integration capabilities, starting from simple examples going to the more complex use cases.

How to enable pre-filling form fields?

Pre-filling form fields is disabled by default.

Enable pre-filling fields globally

Pre-filling all fields of all forms can be enabled on the “Full Pay → Settings → Forms → Options” page in WP admin:

Enable pre-filling form fields piecemeal

You have to implement the fullstripe_form_field_configuration filter.

Use the following API functins in conjunction with the filter to specify which fields can be set via URL parameters, and which fields will become read-only once set:

• setIsFormFieldConfigurable()
• isFormFieldConfigurable()
• setFormFieldValue()
• getFormFieldValue()
• setIsFormFieldReadonly()
• isFormFieldReadonly()

Pre-fill form fields via URL parameters

Which fields can be pre-filled

The following table summarizes which fields can be prefilled.

There are fields which are available only in one layout (inline or checkout), or on a certain form type. Some fields can be made readonly, others cannot. The table below documents all these attributes:

Pre-fill example with URL parameters

Here is an URL example of pre-filling the email, and cardholder’s name fields via URL parameters:

https://example.com/pay?email=john.doe@example.com&cardholdersName=John

When the page is loaded, here is how the form looks:

Pre-fill example with a filter hook

Let’s say you don’t want to enable pre-filling form fields globally.

You’d like to implement the following rule set:

• Only fields of the form named ‘payment’ can be pre-filled.
• Only the email address and cardholder’s name fields can be prefilled.
• Once the email address is pre-filled, it should become read-only.

Here is the filter hook implementation:

<?php
/**
 * A 'fullstripe_form_field_configuration' filter hook example for WP Full Pay.
 *
 * @param array $config The field configuration returned by the previous filter instance.
 * @param array $params with the following keys:
 *   formName               => Name of the form.
 *   formType               => Type of the form. Possible values:
 *                             	inline_payment
 * 				checkout_payment
 * 				inline_subscription
 * 				checkout_subscription
 * 				inline_donation
 *				checkout_donation
 *				inline_save_card
 * 				checkout_save_card
 *
 * @return array Field configuration
 */
function formFieldConfiguration( $config, $params ) {
	$result = $config;
	$formName = $params['formName'];
	
	if ( $formName === 'payment' ) {
		WPFS_API_v2::setIsFormFieldConfigurable( $result, 'cardholdersName', true );

		WPFS_API_v2::setIsFormFieldConfigurable( $result, 'email', true );
		WPFS_API_v2::setIsFormFieldReadonly( $result, 'email', true );		
	}
	
	return $result;
}

add_filter('fullstripe_form_field_configuration', 'formFieldConfiguration', 10, 2 );

Important notes:

• Use the setIsFormFieldConfigurable() API function to enable pre-filling a field.
• Use the setIsFormFieldReadonly() API function to make a read-only once it is prefilled.