GFPaymentAddOnIntroductionGetting StartedCreating Plugin Settings for Payment FeedsCreating Feed Settings Fields for Payment FeedsProducts and Services ExampleSubscriptions ExampleHelper Functions for Adding/Removing/Replacing Default FieldsModifying Default FieldsBilling Info FieldsBilling Cycle IntervalsMain Functionalityredirect_url()Parametersauthorize()ParametersReturnscapture()ParametersReturnssubscribe()ParametersReturnscancel()callback()post_callback()
Introduction
The GFPaymentAddOn class provides basic functionality for developers when creating new add-ons for Gravity Forms that collect payments. It handles payments which redirect to a third-party website (e.g., PayPal Standard) and payments which are made using a credit card with the transaction hidden behind-the-scenes (e.g., Authorize.Net, PayPal Payments Pro, and Stripe). The GFPaymentAddOn class extends the GFFeedAddOn class which gives you the functionality from that class and also the functionality from the GFAddOn class.
The GFPaymentAddOn class uses functionality similar to the GFAddOn. View the GFAddOn』s documention for Initialization, Results Page, and Uninstalling for more information on how to use this functionality in the GFPaymentAddOn class.
Getting Started
These are the first steps you』ll need to take to create an add-on using the Payment Add-On Framework:
Include the Payment Add-On Framework files by calling the following:
GFForms::include_payment_addon_framework();
Inherit the Payment Add-On Framework by creating a new class which extends GFPaymentAddOn :
class GFPayPal extends GFPaymentAddOn {}
Add the class variables to configure the add-on. The list below are variables specific to the payment framework. There are other variables needed which are documented in the GFAddOn class variables section.
$_supports_callbacks boolean
If set to true, callbacks/webhooks/IPN will be enabled and the appropriate database table will be created.
$_requires_credit_card boolean
If set to true, the user will not be able to create feeds for a form until a credit card field has been added.
$redirect_url string
For payment add-ons that send users to an external website to submit payment (i.e. PayPal Standard), use this class variable to specify the URL of the payment page.
Example:
if ( method_exists( 'GFForms', 'include_payment_addon_framework' ) ) {
GFForms::include_payment_addon_framework();
class GFPayPal extends GFPaymentAddOn {
protected $_version = "2.3.7";
protected $_min_gravityforms_version = "1.8.12";
protected $_slug = 'gravityformspaypal';
protected $_path = 'gravityformspaypal/paypal.php';
protected $_full_path = __FILE__;
protected $_title = 'Gravity Forms PayPal Standard Add-On';
protected $_short_title = 'PayPal';
protected $_supports_callbacks = true;
protected $_requires_credit_card = false;
}
}
Creating Plugin Settings for Payment Feeds
Review the article Creating Plugin Settings for more details on adding plugin settings.
Creating Feed Settings Fields for Payment Feeds
The Payment Framework automatically adds key fields to the Feed Settings page. You may add the feed_settings_fields() function to your add-on and override the base function.
The key fields automatically added are as follows:
Feed Name
Text box labeled 「Name」 so you may uniquely identify your payment feed.
Transaction Type
Drop down populated with the types 「Products and Services」 and 「Subscriptions」.
Payment Amount
This is only available when the transaction type is 「Products and Services」.
Drop down populated with the option 「Form Total」. If there are products on the form, the product fields will also be populated in the drop down. Form Total is selected by default.
Subscription Settings
These are only available when the transaction type is 「Subscription」.
Recurring Amount
Drop down populated with the option 「Form Total」. If there are products on the form, the product fields will also be populated in the drop down.
Billing Cycle
The choices available are days (1-365), weeks (1-52), months (1-12), years (1-10).
Recurring Times
The choices available are infinite or 2-100. This is the number of times the payment will occur.
Setup Fee
When enabled, a drop down appears for you to select which product field is used as the setup fee. The 「Trial」 option is not available when this is enabled.
Trial
When enabled, a drop down appears for you to select which product field is used at the Trial amount. You also have to ability to manually enter an amount instead of using a product field on the form.
Billing Information
Email
Address
Address 2
City
State
Zip
Country
Options
Displays a 「Sample Option」 checkbox for you to modify to your needs.
Conditional Logic
Displays an 「Enable Condition」 checkbox which when clicked provides the functionality for selecting a conditional logic match using 「All」 or 「Any」 with the ability to select fields on the form, a condition (is, is not, greater than, less than, contains, starts with, ends with) and an input to set the matching data.
Products and Services Example
Subscriptions Example
Helper Functions for Adding/Removing/Replacing Default Fields
There are several helper functions that you may use to remove, modify, and add fields.
add_field_before()
add_field_after()
remove_field()
replace_field()
Modifying Default Fields
The default values for some of the fields may not be appropriate for your add-on. Below are a few you may modify.
Billing Info Fields
You may override the function billing_info_fields() to set your own fields for billing.
public function billing_info_fields() {
$fields = array(
array( 'name' => 'email', 'label' => __( 'Email', 'gravityforms' ), 'required' => false ),
array( 'name' => 'zip', 'label' => __( 'Zip', 'gravityforms' ), 'required' => false ),
);
return $fields;
}
Billing Cycle Intervals
You may override the function supported_billing_intervals() to set your own intervals to be used.
public function supported_billing_intervals() {
//authorize.net does not use years or weeks, override framework function
$billing_cycles = array(
'day' => array( 'label' => __( 'day(s)', 'gravityforms' ), 'min' => 7, 'max' => 365 ),
'month' => array( 'label' => __( 'month(s)', 'gravityforms' ), 'min' => 1, 'max' => 12 )
);
return $billing_cycles;
}
Main Functionality
Like the GFAddOn class, the Payment Framework contains many features that can be activated by overriding functions in the GFPaymentAddOn class. To override a function, add a function with the same name (and arguments) as the function in the base class.
redirect_url()
Override this method to specify a URL to the third party payment processor. Useful when developing a payment gateway that processes the payment outside of the website (i.e. PayPal Standard). Returns a full URL (including http:// or https://) to the payment processor.
protected function redirect_url( $feed, $submission_data, $form, $entry ) {}
Parameters
$feed Feed Object
Active payment feed containing all the configuration data. The properties will change dependent on the add-on.
$submission_data Submission Data
Contains form field data submitted by the user as well as payment information (i.e. payment amount, setup fee, line items, etc…)
$form Form Object
Current form array containing all form settings.
$entry Entry Object
Current entry array containing entry information (i.e data submitted by users).
authorize()
Override this method to add integration code to the payment processor in order to authorize a credit card with or without capturing payment. This method is executed during the form validation process and allows the form submission process to fail with a validation error if there is anything wrong with the payment/authorization. This method is only supported by single payments. For subscriptions or recurring payments, use the subscribe() method. Returns an array of the authorization information.
protected function authorize( $feed, $submission_data, $form, $entry ) {}
Parameters
$feed Feed Object
Active payment feed containing all the configuration data. The properties will change dependent on the add-on.
$submission_data Submission Data
Contains form field data submitted by the user as well as payment information (i.e. payment amount, setup fee, line items, etc…).
$form Form Object
Current form array containing all form settings.
$entry Entry Object
Current entry array containing entry information (i.e data submitted by users). Note: the entry hasn』t been saved to the database at this point, so this $entry object does not have the 『ID』 property and is only a memory representation of the entry.
Returns
An associative array with the following properties:
is_authorized boolean
error_message string
transaction_id string
If the payment is captured in this method, returns a 『captured_payment』 array with the following information about the payment:
captured_payment array
is_success – boolean
error_message – string
transaction_id – string
amount – float
capture()
Override this method to capture a single payment that has been authorized via the authorize() method. Use only with single payments. For subscriptions, use subscribe() instead. Return an array with the information about the captured payment.
protected function capture( $authorization, $feed, $submission_data, $form, $entry ) {}
Parameters
$authorization array
Contains the result of the authorize() function.
$feed Feed Object
Active payment feed containing all the configuration data. The properties will change dependent on the add-on.
$submission_data Submission Data
Contains form field data submitted by the user as well as payment information (i.e. payment amount, setup fee, line items, etc…).
$form Form Object
Current form array containing all form settings.
$entry Entry Object
Current entry array containing entry information (i.e data submitted by users).
Returns
Returns an associative array with the information about the captured payment in the following format:
is_success boolean
error_message string
transaction_id string
amount float
payment_method string
subscribe()
Override this method to add integration code to the payment processor in order to create a subscription. This method is executed during the form validation process and allows the form submission process to fail with a validation error if there is anything wrong when creating the subscription.
protected function subscribe( $feed, $submission_data, $form, $entry ) {}
Parameters
$feed Feed Object
Active payment feed containing all the configuration data. The properties will change dependent on the add-on.
$submission_data Submission Data
Contains form field data submitted by the user as well as payment information (i.e. payment amount, setup fee, line items, etc…).
$form Form Object
Current form array containing all form settings.
$entry Entry Object
Current entry array containing entry information (i.e data submitted by users). Note: the entry hasn』t been saved to the database at this point, so this $entry object does not have the 『ID』 property and is only a memory representation of the entry.
Returns
An associative array with the following properties:
is_success boolean
error_message string
subscription_id string
amount float
To implement an initial/setup fee for gateways that do not support setup fees as part of subscriptions, manually capture the funds for the setup fee as a separate transaction and send that payment information in the following property:
captured_payment array
name – string
is_success – boolean
error_message – string
subscription_id – string
amount – float
cancel()
Override this method to add integration code to the payment processor in order to cancel a subscription. This method is executed when a subscription is canceled from the Payment Gateway (i.e. Stripe or PayPal).
protected function cancel( $entry, $feed ) {
return false;
}
callback()
Override this method to add code to handle processing the callback/webhook/IPN request.
protected function callback() {}
Return an associative array with the following properties:
id string
The event ID.
type string
The action type. Possible values: complete_payment, refund_payment, fail_payment, add_pending_payment, void_authorization, create_subscription, cancel_subscription, expire_subscription, add_subscription_payment, fail_subscription_payment, or a custom event type.
amount integer|float
The transaction amount.
transaction_type string
The type of transaction which occurred.
transaction_id string
The transaction ID.
subscription_id string
The subscription ID.
entry_id integer
The ID of the entry which created the transaction.
payment_status string
The payment status.
note string
The note to be added to the entry.
callback string
The function to be used to process the custom event type.
post_callback()
Override this method to add code to handle post processing of the callback.
protected function post_callback( $callback_action, $result ) {}
