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:

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:

URL parameter	Layout	Readonly?	Comments
email	inline, checkout	✅	On checkout forms, the email address is read-only by default.
cardholdersName	inline	✅
customerId	checkout	𐄂	Selects the customer, freezes the email field.
price	inline, checkout	𐄂	The value is the Stripe price ID of the product to be selected.
coupon	inline, checkout	𐄂	The value is the name of a coupon or promotional code.
amount	inline, checkout	✅	Sets the custom payment amount. The value is the payment amount in cents.
customField	inline, checkout	✅	The parameter name is numbered, eg. customField1, customField2, etc.
billingName	inline	✅
billingAddress	inline	✅
billingAddress2	inline	✅
billingCity	inline	✅
billingZip	inline	✅
billingState	inline	✅
billingCountryCode	inline	✅	The two-letter ISO country code in uppercase.
shippingName	inline	✅
shippingAddress	inline	✅
shippingAddress2	inline	✅
shippingCity	inline	✅
shippingZip	inline	✅
shippingState	inline	✅
shippingCountryCode	inline	✅	The two-letter ISO country code in uppercase.

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 &#39;fullstripe_form_field_configuration&#39; 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[&#39;formName&#39;];
	
	if ( $formName === &#39;payment&#39; ) {
		WPFS_API_v2::setIsFormFieldConfigurable( $result, &#39;cardholdersName&#39;, true );

		WPFS_API_v2::setIsFormFieldConfigurable( $result, &#39;email&#39;, true );
		WPFS_API_v2::setIsFormFieldReadonly( $result, &#39;email&#39;, true );		
	}
	
	return $result;
}

add_filter(&#39;fullstripe_form_field_configuration&#39;, &#39;formFieldConfiguration&#39;, 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.