GFPaymentAddOn

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:

1. Include the Payment Add-On Framework files by calling the following:

   GFForms::include_payment_addon_framework();

2. Inherit the Payment Add-On Framework by creating a new class which extends GFPaymentAddOn :

   class GFPayPal extends GFPaymentAddOn {}

3. 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.

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 ) {}

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 ) {}

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 ) {}

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 ) {}

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:

post_callback()

Override this method to add code to handle post processing of the callback.

protected function post_callback( $callback_action, $result ) {}