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.

  • $_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

Products and Services Example

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

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:

If the payment is captured in this method, returns a ‘captured_payment’ array with the following information about the payment:

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:

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:

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:

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