This article walks you through how to integrate a custom GiveWP payment gateway add-on.

Properly Naming your GiveWP Gateway Add-on

Official GiveWP add-ons are named according to the predictable structure GiveWP-[Addon Name]. For example, the Square add-on is named GiveWP - Square.

Add-ons not managed by the GiveWP team make that clear by not leading with the brand name. Instead, they are named [Add-on Name] for GiveWP or [Add-on Name] add-on for GiveWP.

For example, a GiveWP add-on for the payment gateway Instamojo would be named Instamojo for GiveWP or Instamojo add-on for GiveWP.

The name goes in a comment in the readme.txt file in the root of your plugin’s file structure, as well as the main plugin PHP file.

Registering Your Custom Payment Gateway

Once you’ve chosen a name, next you need to register the custom payment gateway as a GiveWP gateway. This is done by calling a function on the give_payment_gateways filter, like so:

Registering a custom GiveWP gateway

/**
 * Register payment method.
 *
 * @since 1.0.0
 *
 * @param array $gateways List of registered gateways.
 *
 * @return array
 */

// change the prefix insta_for_give here to avoid collisions with other functions
function insta_for_give_register_payment_method( $gateways ) {
  
  // Duplicate this section to add support for multiple payment method from a custom payment gateway.
  $gateways['instamojo'] = array(
    'admin_label'    => __( 'Instamojo - Credit Card', 'instamojo-for-give' ), // This label will be displayed under Give settings in admin.
    'checkout_label' => __( 'Credit Card', 'instamojo-for-give' ), // This label will be displayed on donation form in frontend.
  );
  
  return $gateways;
}

add_filter( 'give_payment_gateways', 'insta_for_give_register_payment_method' );

The code above adds the gateway to the list of available gateways in the GiveWP Gateway settings.

Instamojo now appears atop the list of available gateways in the GiveWP settings.
The new gateway has been added to the list of available gateways!

Adding a Settings Page for Your Custom Payment Gateway

Though it’s been registered as a gateway in the settings, your custom gateway is not actually doing anything yet. That’s where the settings page comes in.

You can add a dedicated settings section within the Payment Gateways tab for your custom payment gateway by following these two steps:

  1. Register a settings section
  2. Adding fields to that settings section

Register a Settings Section

To register a settings section, you’ll need to set the name/slug of the payment gateway section as instamojo-settings which is used to display the setting fields on that specific payment gateway section. The filter to use is give_get_sections_gateways.

Registering a Settings Page for your Custom Gateway

/**
 * Register Section for Payment Gateway Settings.
 *
 * @param array $sections List of payment gateway sections.
 *
 * @since 1.0.0
 *
 * @return array
 */

// change the insta_for_give prefix to avoid collisions with other functions.
function insta_for_give_register_payment_gateway_sections( $sections ) {
	
	// `instamojo-settings` is the name/slug of the payment gateway section.
	$sections['instamojo-settings'] = __( 'Instamojo', 'instamojo-for-give' );

	return $sections;
}

add_filter( 'give_get_sections_gateways', 'insta_for_give_register_payment_gateway_sections' );

This code registers a settings section on the Payment Gateways tab at Donations > Settings > Payment Gateways. In the next section, we’ll populate that section with some options.

Adding fields to the settings section

While adding the fields to the Instamojo Gateway settings section, match the case name with the section name/slug you created (in the example, it’s instamojo-settings) and then create an array of setting fields as shown below.

Register the Payment Gateway Tab Settings Section

/**
 * Register Admin Settings.
 *
 * @param array $settings List of admin settings.
 *
 * @since 1.0.0
 *
 * @return array
 */
// change the insta_for_give prefix to avoid collisions with other functions.
function insta_for_give_register_payment_gateway_setting_fields( $settings ) {

	switch ( give_get_current_setting_section() ) {

		case 'instamojo-settings':
			$settings = array(
				array(
					'id'   => 'give_title_instamojo',
					'type' => 'title',
				),
			);

            $settings[] = array(
				'name' => __( 'API Key', 'give-square' ),
				'desc' => __( 'Enter your API Key, found in your Instamojo Dashboard.', 'instamojo-for-give' ),
				'id'   => 'insta_for_give_instamojo_api_key',
				'type' => 'text',
		    );

			$settings[] = array(
				'id'   => 'give_title_instamojo',
				'type' => 'sectionend',
			);

			break;

	} // End switch().

	return $settings;
}

// change the insta_for_give prefix to avoid collisions with other functions.
add_filter( 'give_get_settings_gateways', 'insta_for_give_register_payment_gateway_setting_fields' );

Each settings field is a nested array containing the name, description, id, and type of each field. When a user saves values in this section it saves them to the GiveWP settings (stored in the WordPress options table where you can access them via functions like give_get_option()) and is used to configure the API call to the gateway as well as how the Payment fields are configured on the page.

There are 17 available field types to choose from:

  • text
  • email
  • number
  • password
  • colorpicker
  • hidden
  • textarea
  • radio_inline
  • radio
  • select
  • multiselect
  • checkbox
  • multicheck
  • file
  • media
  • wysiwyg
  • api_key

With the sample snippet above, you will see the following on the new Instamojo Gateway settings section:

screenshot highlighting the new Instamojo section on the Payment Gateways tab.
The new settings section with a field for adding in the Instamojo API key

Processing the Donation at the New Gateway

So far, the code you’ve added does the following:

  1. Registers the Payment Gateway on the Payment Gateways Tab
  2. Adds a settings section to that same tab
  3. Populates the settings section with fields that when saved save into the GiveWP settings and are retrievable.
  4. Adds Credit Card fields to the forms when the new gateway is selected.

The details for actually processing the card will vary by gateway, and you should consult the PHP SDK and API docs for the gateway. There are a few GiveWP-specific tricks for setting up that API call though, and the following snippet shows those.

Submit the donation to the Gateway

/**
 * Process Square checkout submission.
 *
 * @param array $posted_data List of posted data.
 *
 * @since  1.0.0
 * @access public
 *
 * @return void
 */

// change the insta_for_give prefix to avoid collisions with other functions.
function insta_for_give_process_instamojo_donation( $posted_data ) {



	// Make sure we don't have any left over errors present.
	give_clear_errors();

	// Any errors?
	$errors = give_get_errors();

	// No errors, proceed.
	if ( ! $errors ) {

		$form_id         = intval( $posted_data['post_data']['give-form-id'] );
		$price_id        = ! empty( $posted_data['post_data']['give-price-id'] ) ? $posted_data['post_data']['give-price-id'] : 0;
		$donation_amount = ! empty( $posted_data['price'] ) ? $posted_data['price'] : 0;

		// Setup the payment details.
		$donation_data = array(
			'price'           => $donation_amount,
			'give_form_title' => $posted_data['post_data']['give-form-title'],
			'give_form_id'    => $form_id,
			'give_price_id'   => $price_id,
			'date'            => $posted_data['date'],
			'user_email'      => $posted_data['user_email'],
			'purchase_key'    => $posted_data['purchase_key'],
			'currency'        => give_get_currency( $form_id ),
			'user_info'       => $posted_data['user_info'],
			'status'          => 'pending',
			'gateway'         => 'instamojo',
		);

		// Record the pending donation.
		$donation_id = give_insert_payment( $donation_data );

		if ( ! $donation_id ) {

			// Record Gateway Error as Pending Donation in Give is not created.
			give_record_gateway_error(
				__( 'Instamojo Error', 'instamojo-for-give' ),
				sprintf(
				/* translators: %s Exception error message. */
					__( 'Unable to create a pending donation with Give.', 'instamojo-for-give' )
				)
			);

			// Send user back to checkout.
			give_send_back_to_checkout( '?payment-mode=instamojo' );
			return;
		}

		// Do the actual payment processing using the custom payment gateway API. To access the GiveWP settings, use give_get_option() 
                // as a reference, this pulls the API key entered above: give_get_option('insta_for_give_instamojo_api_key')

	} else {

		// Send user back to checkout.
		give_send_back_to_checkout( '?payment-mode=instamojo' );
	} // End if().
}

// change the insta_for_give prefix to avoid collisions with other functions.
add_action( 'give_gateway_instamojo', 'insta_for_give_process_instamojo_donation' );

Before making the API call to the gateway, GiveWP sets up the donation and sets it as pending. The top portion of the snippet above shows some best practices for that, including clearing existing errors, checking for new errors, and sending the donor back to the form (which also displays the errors to the donor so that they can re-submit).

Once all the data is validated and error free, you come to the section of code that you’ll need to configure yourself to actually call the payment gateway API to process the transaction.

There are some hidden gems in this snippet to reference to see how GiveWP processes the data and saves it to the database. You’ll want to check out our GitHub Repo (we develop in the open!) to see how you might leverage those functions to customize your new Gateway add-on.

Another best practice here is to check out how the core GiveWP product handles gateways. There are 4 included donations in GiveWP out of the box: Test, Offline, PayPal Standard, and Stripe. You can poke around the /includes/gateways gateway to see how the GiveWP developers do it.

Testing Your New Gateway

Don’t forget that once you’ve created a new gateway, if you plan to distribute or sell that code to others to use, you should take into account the many existing add-ons like Recurring Donations, Tributes, Fee Recovery, Form Field Manager, and Currency Switcher.

Each of these add-ons extend GiveWP in ways that can have an effect on the functionality of your new gateway, so be sure to test alongside them. The best way to do that is by purchasing a Plus Plan to get access to all of them.

Need a Custom Gateway Built?

If you need a custom gateway built for your organization and don’t want to build it yourself, we recommend you contact Mehul Gohil — he’s the developer behind many of the official GiveWP gateways and does excellent work.