The Fluent Forms BasePaymentMethod Class provides developers with a simple way to add new Payment methods easily. The BaseProcessor Class is also required for the payment method background processing. The BasePaymentMethod class mainly works for displaying and storing the payment method settings, while the BaseProcessor class process and finalize the payments.

The API Functions are automatically included when Fluent Forms Pro is Booted. The BaseFieldManager class is located in src/Payments/PaymentMethods/BasePaymentMethod.php .

Notice: Please do not initiate this class directly. You should extend this class to add start adding a new payment method

Methods

__construct()

<?php

use FluentFormPro\Payments\PaymentMethods\BasePaymentMethod;

class MyCustomPaymentMethod extends BasePaymentMethod
{    
     /*
     * Extend your payment method with a payment key identifier
     */
     public function __construct()
     {
         parent::__construct('myCustomPaymentKey');
     }

This is an example of how you can extend the BasePaymentMethod. This key will be used to identify the payment later on for the payment actions.

init()

This is the main function that will run all the required actions for this payment settings and processing. These hooks will be called dynamically during the payment processing & settings after the payment method setup is completed.

 public function init()
    {
        add_filter('fluentform/payment_method_settings_validation_'.$this->key, array($this, 'validateSettings'), 10, 2);

        if(!$this->isEnabled()) {
            return;
        }

        add_filter('fluentform/transaction_data_' . $this->key, array($this, 'modifyTransaction'), 10, 1);

        add_filter(
            'fluentform/available_payment_methods',
            [$this, 'pushPaymentMethodToForm']
        );
    }

pushPaymentMethodToForm($methods)

This method will push the payment method with existing $methods to form the editor. So it can be added to your fluentform. Here is the format you need to follow to add the method. The $methods parameter is available with the fluentform/available_payment_methods hook.

/*
* @param $methods - Payment Methods Array data
*/    
public function pushPaymentMethodToForm($methods)
{
    $methods[$this->key] = [
        'title' => __('CustomPayment Method', 'fluentformpro'),
        'enabled' => 'yes',
        'method_value' => $this->key,
        'settings' => [
            'option_label' => [
                 'type' => 'text',
                 'template' => 'inputText',
                 'value' => 'Pay with MyCustomPaymentMethod ',
                 'label' => 'Method Label'
             ]
         ]
    ];
    return $methods;
}

modifyTransaction($transaction)

This method modifies a transaction record with the payment method dashboard entry URL. Use this to link the transaction with your payment method’s dashboard transaction page using the $transaction->charge_id charge id. The $transaction parameter is available with the ‘fluentform_transaction_data_'{$key} hook.

/*
* @param $transaction - Transaction Data array
*/
public function modifyTransaction($transaction)
{
   if ($transaction->charge_id) {
        $transaction->action_url =  'https://dashboard.mypaymentsitedemo.com/app/payments/'.$transaction->charge_id;
    }
    return $transaction;
}

getGlobalFields()

This method will return all the admin settings for the current payment method. You can add your own settings also here. At the end of this page, you will see an example with the settings format.

 abstract public function getGlobalFields();

getGlobalSettings()

This method should return the saved data from the database. It will be based on the settings that were provided by getGlobalFields() method. You can get your settings like this get_option(‘fluentform_payment_settings_{key}’, []);

abstract public function getGlobalSettings();

Further read

Validate settings of payment method

If you want to validate the payment admin settings use this hook

add_filter('fluentform/payment_method_settings_validation_{key}', function ($errors, $settings) {
        if(!($settings['test_api_key']) && !($settings['live_api_key'])) {
             $errors['test_api_key'] = __('API Key is required', 'fluentformpro');
        }
        return $errors;
}, 10, 2);

All Together

Your ideal implementation should look like this with validation.

class MyCustomPaymentMethod extends BasePaymentMethod
{
    public function __construct()
    {
        parent::__construct('myCustomPaymentKey');
    }

    public function init()
    {  
        add_filter('fluentform/payment_method_settings_validation_'.$this->key, array($this, 'validateSettings'), 10, 2);

        add_filter('fluentform/transaction_data_' . $this->key, array($this, 'modifyTransaction'), 10, 1);

        add_filter(
            'fluentform/available_payment_methods',
            [$this, 'pushPaymentMethodToForm']
        );
    }

    public function pushPaymentMethodToForm($methods)
    {
        $methods[$this->key] = [
            'title' => __('CustomPayment Method', 'fluentformpro'),
            'enabled' => 'yes',
            'method_value' => $this->key,
            'settings' => [
                'option_label' => [
                    'type' => 'text',
                    'template' => 'inputText',
                    'value' => 'Pay with MyCustomPaymentMethod ',
                    'label' => 'Method Label'
                ]
            ]
        ];

        return $methods;
    }

    public function validateSettings($errors, $settings)
    {
        if(!($settings['test_api_key']) && !($settings['live_api_key'])) {
            $errors['test_api_key'] = __('API Key is required', 'fluentformpro');
        }
        return $errors;
    }

    public function modifyTransaction($transaction)
    {
        return $transaction;
    }

    public function getGlobalFields()
    {
        return [
            'label' => 'MyCustom Payment Settings',
            'fields' => [
                [
                    'settings_key' => 'is_active',
                    'type' => 'yes-no-checkbox',
                    'label' => 'Status',
                    'checkbox_label' => 'Enable MyCustom Payment Payment Method'
                ],
                [
                    'settings_key' => 'payment_mode',
                    'type' => 'input-radio',
                    'label' => 'Payment Mode',
                    'options' => [
                        'test' => 'Test Mode',
                        'live' => 'Live Mode'
                    ],
                    'info_help' => 'Select the payment mode. for testing purposes you should select Test Mode otherwise select Live mode.',
                    'check_status' => 'yes'
                ],
                [
                    'settings_key' => 'test_api_key',
                    'type' => 'input-text',
                    'data_type' => 'password',
                    'placeholder' => 'Test API Key',
                    'label' => 'Test API Key',
                    'inline_help' => 'Provide your test api key for your test payments',
                    'check_status' => 'yes'
                ],
                [
                    'settings_key' => 'live_api_key',
                    'type' => 'input-text',
                    'data_type' => 'password',
                    'label' => 'Live API Key',
                    'placeholder' => 'Live API Key',
                    'inline_help' => 'Provide your live api key for your live payments',
                    'check_status' => 'yes'
                ]
            ]
        ];
    }

    public function getGlobalSettings()
    {
        return get_option('fluentform/payment_settings_'.$this->key, []);
    }
}

Final Note

It’s highly recommended to explore our source files and try to understand the procedure. Once you understand it’s very easy to implement your own custom payment method.

If you have any questions please feel free to reach out to our facebook community group

For example for the phone field use this hook: fluentform/validate_input_item_phone

add_filter('fluentform/validate_input_item_{input_key}', function ($errorMessage, $field, $formData, $fields, $form) {
    
	$fieldName       = 'phone';
	$target_form_id  = 13;

	if($target_form_id !=  $form->id){ return $errorMessage; }
   	
	
	if ($inputValue = \FluentForm\Framework\Helpers\ArrayHelper::get($formData, $fieldName)) {
		$exist = wpFluent()->table('fluentform_entry_details')
			->where('form_id', $form->id)
			->where('field_name', $fieldName)
			->where('field_value', $inputValue)
			->first();
	
		if ($exist) {
			 $errorMessage = "Error ! This field needs to be unique.";
			 return [$errorMessage];
		}
	}
   	
    return $errorMessage;

}, 10, 5);

Use this code in the theme function.php file or any PHP code snippet plugin.

Feel free to share any insights or if you have a topic in mind you would like to see documentation and example code about it. For more discussion, join our Facebook group Fluent Forms Community.

We used regular expressions here to check password strength for example minimum eight-character, must include one uppercase and one lowercase character. You can add more or remove them as you need. You can check live and get code from your regular expression from here.

Use the following code snippet in the theme function.php file or in any PHP snippet plugin. Make sure the password field input name is password or you can change it and add your form ID. That is all.

add_filter('fluentform/validate_input_item_input_password', function($errorMessage, $field, $formData, $fields, $form){
    
    $target_form_id = 9;
    if($form->id != $target_form_id){
        return;
    }
    
    $password =  $formData['password'];
    $errorMessage = '';
    
    //numbers
    $pattern = "/[0-9]/";
    $match = preg_match($pattern,$password);
    
    if (!$match){
        
        $errorMessage= "You need atleast 1 number!";
        return [$errorMessage];
    }
    
    // 8 charcter min
    $pattern = "/(?=.{8,})/";
    $match = preg_match($pattern,$password);
    
    //preg_match($pattern, $password, $matches, PREG_OFFSET_CAPTURE, 0);
    if (!$match){
        
        $errorMessage= "You need minimum 8 charcter!";
        return [$errorMessage];
    }

    // small and capital
    $pattern = "/(?=.*[a-z])(?=.*[A-Z])/";
    $match = preg_match($pattern,$password);
    if (!$match){

        $errorMessage= "You need one to 1 smaller and 1 upper charcter!";
        return [$errorMessage];
    }

    // special charcter
    $pattern = "/(?=.*[^\w\d])/";
    $match = preg_match($pattern,$password);
    if (!$match){

        $errorMessage= "You need one to 1 special charcter !";
        return [$errorMessage];
    }
    
    return ;
    
    
},10,5);

Feel free to share any insights or if you have a topic in mind you would like to see documentation and example code about it. For more discussion, join our Facebook group Fluent Forms Community.

Using this filter you can create an email confirmation field. By default email input name attribute is ’email’ and if you add another email input its name is ’email_1′. So in this example, we have used these two names for two email fields, to make sure these match. Here is the following code :

 add_filter('fluentform/validate_input_item_input_email', function($errorMessage, $field, $formData, $fields, $form) {

    $target_form_id = 8;
    if($form->id != $target_form_id ) {
     return $errorMessage ;
    }
    
    
    if( $formData['email'] !=  $formData['email_1']  ){
        $errorMessage =  ['Error! Email does not match'];
    }
    
    return $errorMessage;
}, 10, 5);

Just change your form ID and place this code in your function.php file. You can do this for other fields as well such as the password fields using their respective validation filters. For the password field, the filter will be ‘fluentform/validate_input_item_input_password’ and the name attributes password fields which are by default ‘password’ and ‘password_1’.

Check all the input filter hooks in this page fluentform/validate_input_item_input_text.

If you are an advanced user open the file app/Modules/SubmissionHandler/SubmissionHandler.php file and check the submit() method to see the full implementation.

Server Side Lifecycle

The following steps completed one by one

1. Prepare the submitted the data
2. Validate the data
3. Prepare to insert data
4. Insert the data & initiate integrations and notifications
5. Send the response to the browser as a JSON response

Step 1: Preparing the Data

In this step, Fluent Forms set up the form data, available inputs, and submitted data from the browser. No major hooks fired in this step.

// Parse the url encoded data from the request object.
parse_str($this->app->request->get('data'), $data);

// Merge it back again to the request object.
$this->app->request->merge(['data' => $data]);

$formId = intval($this->app->request->get('form_id'));

$this->setForm($formId);

// Parse the form and get the flat inputs with validations.
$fields = FormFieldsParser::getInputs($this->form, ['rules', 'raw']);

// Sanitize the data properly.
$this->formData = fluentFormSanitizer($data, null, $fields);

Step 2: Validate the data

In this step, Fluent Forms validate the submitted data. If there has been any error or validation failure then it sends an error response to the client with in details errors object as JSON.

private function validate(&$fields)
{
    // Validate the form restrictions
    $this->validateRestrictions($fields);
    // Validate the form nonce. By default it does not verify as many people use caching
    $this->validateNonce();
    // If recaptcha enabled then it verify it.
    $this->validateReCaptcha();

    // Validate the required fields and offer each element to do their own validation. 
    // Please check the source code to get elements level validation filter hook.
}

Step 3: Prepare insert data

In this step, Fluent Forms prepare the data to insert into the database. You can use the following hooks to alter/format the data as per your need.

• fluentform/insert_response_data -> Use this to filter the actual response from the client
• fluentform/filter_insert_data -> The full entry. You don’t need to use this for almost 99% of cases.

Please check the corresponding filter hook doc for more information and its structure.

Step 4: Insert the data

In this step Fluent Forms provide an action hook before inserting data, inserting the data, and as well as after the submission hook. It’s an important hook for developers to do extended validations and post custom integrations.

Before Insert Action Hook: fluentform/before_insert_submission

After Insert Action Hook: fluentform/submission_inserted

If you want to do extended validation please use the fluentform/before_insert_submission hook. Check the corresponding hook documentation for more details.

Step 5: Send a response

This is the final step as everything is done and all the integrations and notifications are being processed. Fluent Forms finds the appropriate confirmation and send a response accordingly. You can use fluentform/submission_confirmation filter to alter the confirmation programmatically.

Server Side Hooks List for Submission

The hooks are fired as below (Step by Step)

• fluentform/insert_response_data [filter]
• fluentform/filter_insert_data [filter]
• fluentform/before_insert_submission [action]
• fluentform/submission_inserted [action]
• fluentform/submission_confirmation [filter]
• fluentform/before_submission_confirmation [action]

Client Side Submission Lifecycle

When you click the submit button the following steps are completed step by step

1. Validate the data
   • If validation is OK go to step 2
   • If validation failed, Stop and show the error messages
2. prepare form data
3. add loading icon to submit button
4. make the Ajax call to the server and wait for the server’s response
   • If the response success then go to step 5
   • If the response is failed, stop and trigger jQuery “fluentform_submission_failed” event to the jquery form object with the response
5. Trigger jQuery event “fluentform_submission_success” in the $form jQuery object with the response
6. Show a success message and redirect the user if confirmation is set so.
7. remove submit button loading.

var $inputs = $formSubmission
    .find(':input').filter(function (i, el) {
        return !$(el).closest('.has-conditions').hasClass('ff_excluded');
    });

validate($inputs);

var formData = {
    data: $inputs.serialize(),
    action: 'fluentform_submit',
    form_id: $formSubmission.data('form_id')
};

$(formSelector + '_success').remove();
$(formSelector + '_errors').html('');
$formSubmission.find('.error').html('');

$formSubmission
    .find('.ff-btn-submit')
    .addClass('disabled')
    .attr('disabled', 'disabled')
    .parent()
    .append('<div class="ff-loading"></div>');

$.post(fluentFormVars.ajaxUrl, formData)
    .then(function (res) {
        $theForm.trigger('fluentform_submission_success', {
            form: $theForm,
            response: res
        });

        if ('redirectUrl' in res.data.result) {
            if (res.data.result.message) {
                $('<div/>', {
                    'id': formId + '_success',
                    'class': 'ff-message-success'
                })
                    .html(res.data.result.message)
                    .insertAfter($theForm);
                $theForm.find('.ff-el-is-error').removeClass('ff-el-is-error');
            }

            location.href = res.data.result.redirectUrl;
            return;
        } else {
            $('<div/>', {
                'id': formId + '_success',
                'class': 'ff-message-success'
            })
                .html(res.data.result.message)
                .insertAfter($theForm);

            $theForm.find('.ff-el-is-error').removeClass('ff-el-is-error');

            if (res.data.result.action == 'hide_form') {
                $theForm.hide();
            } else {
                $theForm[0].reset();
            }
        }
    })
    .fail(function (res) {
        $theForm.trigger('fluentform_submission_failed', {
            form: $formSubmission,
            response: res
        });

        showErrorMessages(res.responseJSON.errors);
        scrollToFirstError(350);

        if ($theForm.find('.fluentform-step').length) {
            var step = $theForm
                .find('.error')
                .not(':empty:first')
                .closest('.fluentform-step');

            let goBackToStep = step.index();
            updateSlider(goBackToStep, 350, false);
        }
    })
    .always(function (res) {
        $formSubmission
            .find('.ff-btn-submit')
            .removeClass('disabled')
            .attr('disabled', false)
            .siblings('.ff-loading')
            .remove();
        // reset reCaptcha if available.
        if (window.grecaptcha) {
            grecaptcha.reset(
                getRecaptchaClientId(formData.form_id)
            );
        }
    });