This filter is called in two situations:
- A field error has been generated server-side.
- A pre_processor callback of a processor returned an array.
Triggering A Redirect From A Processor
Some type sof payment processors require a redirect to their site to enter credentials. In the pre_process callback for your processor you would find the URL, then you would place that URL in the gloabl variable $transadata, which is cached between sessions automatically by Caldera Forms. Your pre_process callback must return an array to trigger this filter.
In your pre_process callback that would look like this:
That would cause the caldera_forms_submit_return_redirect to be triggered, which you can hook into like this.
Setting the return URL for your payment processor is important. You must return to the same URL as your form is loaded on, with the same query vars, plus the process ID as the cf_tp var. This is necessary to ensure that when the payment processor sends the user back to your site Caldera Forms continues the same form submission instead of starting a new one. Here is how you can build your return URL:
Where Does This Code Go?
When using WordPress hooks to customize Caldera Forms or other plugins you should not modify the plugin files, or you will lose your changes when you update the plugin. Instead you should create a small plugin to hold the custom code. It's easy, learn how here.
Technically you can add the custom code to your theme's functions.php, but then you will not be able to change your theme and keep these customizations.