Payment gateways are “methods” of accepting payments for purchases through Easy Digital Downloads. By default, the plugin comes with two payment gateways: PayPal Standard and Manual Payment. Due to the extensible nature of the plugin, add-on payment gateways can be created, of which there are quite a few available. We can have a gateway to process payments through Stripe, Moneybookers, or many, many others. In this tutorial, I’m going to walk you through the process of creating your own custom payment gateway.

Introduction

There are four primary sections to a payment gateway in Easy Digital Downloads:

  1. Registering the gateway
  2. Setting up the credit card form, if any
  3. Processing the payment
  4. Adding the gateway settings for API keys and such

We will go through the process step by step.

Registering the Gateway

By registering the payment gateway, we make it available for use. This process also makes the gateway appear in the Payment Gateways list, shown below:

Adding our own custom gateway is very simple, it is just one function attached to a filter. The structure of the function looks like this:

// registers the gateway
function pw_edd_register_gateway($gateways) {
	$gateways['gateway_id'] = array('admin_label' => 'Label Shown in the Admin', 'checkout_label' => __('Label Shown on Checkout', 'your_textdomain'));
	return $gateways;
}
add_filter('edd_payment_gateways', 'pw_edd_register_gateway');

Replace the place holders with actual values and we get this:

// registers the gateway
function pw_edd_register_gateway($gateways) {
	$gateways['sample_gateway'] = array('admin_label' => 'Sample Gateway', 'checkout_label' => __('Sample Gateway', 'pw_edd'));
	return $gateways;
}
add_filter('edd_payment_gateways', 'pw_edd_register_gateway');

That’s it. Your gateway will now be available in the list of Payment Gateways in the settings for Easy Digital Downloads. You can enable it and select it as your method of payment during checkout. It won’t function yet, since we haven’t setup the payment processing function, but it is there.

Setting Up (or disabling) the Credit Card Form

Some payment gateways, such as Stripe, accept credit card details on the checkout page, and other gateways, such as PayPal, redirect the user to a secure site where the payment is processed. Easy Digital Downloads can easily support both of these.

The main difference between these two kinds of payment gateways is that one requires a credit card form on the site, and the other doesn’t.

By default, Easy Digital Downloads will output a credit card form that looks like this:

If your payment gateway accepts credit cards, then this form will likely work just fine for you, but if you would like to use your own custom form (as the Stripe gateway does), then there is a simple way to set it up.

When loading the checkout page, EDD will look to see if the following action is registered:

edd_{gateway ID}_cc_form

If the action is registered, then whatever function (for outputting HTML) is hooked to the action will be executed, otherwise the default credit card form is loaded instead.

To completely disable the credit card form, all you have to do is register the edd_{gateway ID}_cc_form action (with your gateway ID) and attach a blank function, or one that returns nothing. A sample function for disabling the credit card form is shown below:

function pw_edd_sample_gateway_cc_form() {
	// register the action to remove default CC form
	return;
}
add_action('edd_sample_gateway_cc_form', 'pw_edd_sample_gateway_cc_form');

With this action registered, the checkout form will now look like this:

Disabling the credit card forms is something you will usually do when creating a gateway that accepts payment through the merchant site, such as PayPal or Moneybookers.

Now what if you want to customize the credit card forms? You simply register the action as you did above and add HTML output to your function, like so:

// setup a custom CC form for Sample Gateway
function pw_edd_sample_gateway_cc_form() {
	ob_start(); ?>
	<fieldset>
		<legend><?php _e('Credit Card Info', 'edd'); ?></legend>
		<p>
			<input type="text" autocomplete="off" name="card_name" class="card-name edd-input required" placeholder="<?php _e('Card name', 'pw_edd'); ?>"/>
			<label class="edd-label"><?php _e('Name on the Card', 'pw_edd'); ?></label>
		</p>
		<p>
			<input type="text" autocomplete="off" name="card_number" class="card-number edd-input required" placeholder="<?php _e('Card number', 'pw_edd'); ?>" />
			<label class="edd-label"><?php _e('Card Number', 'pw_edd'); ?></label>
		</p>
		<p>
			<input type="text" size="4" autocomplete="off" name="card_cvc" class="card-cvc edd-input required" placeholder="<?php _e('CVC', 'pw_edd'); ?>"/>
			<label class="edd-label"><?php _e('CVC', 'pw_edd'); ?></label>
		</p>
		<p class="card-expiration">
			<input type="text" size="2" name="card_exp_month" class="card-expiry-month edd-input required" placeholder="<?php _e('Month', 'pw_edd'); ?>"/>
			<span class="exp-divider"> / </span>
			<input type="text" size="4" name="card_exp_year" class="card-expiry-year edd-input required" placeholder="<?php _e('Year', 'pw_edd'); ?>"/>
			<label class="edd-label"><?php _e('Expiration (MM/YYYY)', 'pw_edd'); ?></label>
		</p>
	</fieldset>
	<?php
	echo ob_get_clean();
}
add_action('edd_sample_gateway_cc_form', 'pw_edd_sample_gateway_cc_form');

This is the exact HTML that the Stripe payment gateway uses.

Processing the Payment

When a purchase is made through a gateway, Easy Digital Downloads executes a gateway-specific function for processing the payment. The function that is executed is determined by a special hook, similar to the way the credit card form is outputted (or not).

function gateway_function_to_process_payment($purchase_data) {
	// payment processing happens here
}
add_action('edd_gateway_{gateway ID}', 'gateway_function_to_process_payment');

To setup the function that processes the purchase in your gateway, all you have to do is hook your function to this action: edd_gateway_{gateway ID}.

Inside of your hooked function, you can process the payment however you wish. Some gateways will redirect to the offsite merchant here, while others will use an API to process the payment without leaving the site.

The $purchase_data parameter contains all of the necessary information about the downloads being purchased. It also contains information about the buyer, such as email, user ID (if logged in), first name, and last name.

When processing the payment, there are a few things you need to take into account:

  • Is the plugin in Test mode?
  • Make sure you check for valid data in any credit card fields you have setup, and store the errors if there are any.
  • Setup and store the purchase data in EDD.
  • Process the payment or redirect to a merchant site.
  • Mark the payment as complete (if applicable).
  • Redirect back to checkout on error, or the thank you page on successful payment.

The first thing we do is check whether Easy Digital Downloads is being used in test mode. We do this with a simple conditional function:

/**********************************
* set transaction mode
**********************************/
 
if(edd_is_test_mode()) {
	// set test credentials here
} else {
	// set live credentials here
}

This conditional will allow you to properly setup your merchant API keys or redirect URLs. For example, in PayPal Standard, when the plugin is in test mode, the following URL is used:

https://www.sandbox.paypal.com/cgi-bin/webscr

But when in Live mode, this one is used:

https://www.paypal.com/cgi-bin/webscr

This makes it much easier for us to test our payment gateway to make sure it is working properly.

The next thing we do in our process purchase function is check for valid data. If your gateway accepts credit cards, then you need to make sure that the data entered is okay. You can do that easily like this:

// errors can be set like this
if(!isset($_POST['card_number'])) {
	// error code followed by error message
	edd_set_error('empty_card', __('You must enter a card number', 'edd'));
}

The edd_set_error(() function will store the error and display it on the checkout page.

After our data validation checks run, we do a quick test to see if any errors were recorded:

// check for any stored errors
$errors = edd_get_errors();
if(!$errors) {
	// no errors, so process the payment
} else {
	$fail = true; // errors were detected
}

If there are no errors detected, we move on to processing the payment, or redirecting to the off site merchant. If there are errors, then we set a flag which will cause the user to be redirected back to the purchase page.

Next, inside of the !$errors conditional, we need to retrieve the purchase summary. This is not required but is a good thing to do, as the summary contains basic information related to what items the user purchased.

$purchase_summary = edd_get_purchase_summary($purchase_data);

Remember, the $purchase_data is passed as a parameter to our payment processing function, and it contains all of the information about the purchase.

After the purchase summary is retrieved, we setup and store a pending purchase, which goes into the Payment History page. This particular step will very rarely differ between gateways, but, if for any reason, you can modify it if needed.

/**********************************
* setup the payment details
**********************************/
 
$payment = array( 
'price' => $purchase_data['price'], 
'date' => $purchase_data['date'], 
'user_email' => $purchase_data['user_email'],
'purchase_key' => $purchase_data['purchase_key'],
'currency' => $edd_options['currency'],
'downloads' => $purchase_data['downloads'],
'cart_details' => $purchase_data['cart_details'],
'user_info' => $purchase_data['user_info'],
'status' => 'pending'
);
 
// record the pending payment
$payment = edd_insert_payment($payment);

The edd_insert_payment() function will create the payment in Easy Digital Downloads, making it available in the Payment History. It will look like this:

Note that the payment status is “pending”. We only want to mark the payment as “complete” once we have a confirmed payment. Once the payment is marked as “complete”, the purchase receipt with download links is sent out, as is the admin sale notification email.

At this point we now either redirect to the off site merchant or process the payment onsite with a merchant API. Since the method for processing the payment itself can differ so much, I’m leaving that part up to you. If you are already looking to create a payment gateway for a particular merchant, then you probably are at least a little aware of how it works, but feel free to ask if you need help.

Once you have confirmed that the merchant payment was complete, you will update the status of the payment and send the buyer to the success page:

$merchant_payment_confirmed = false;
 
/**********************************
* Process the credit card here.
* If not using a credit card
* then redirect to merchant
* and verify payment with an IPN
**********************************/
 
// if the merchant payment is complete, set a flag
$merchant_payment_confirmed = true;		
 
if($merchant_payment_confirmed) { // this is used when processing credit cards on site
 
	// once a transaction is successful, set the purchase to complete
	edd_update_payment_status($payment, 'complete');
 
	// go to the success page			
	edd_send_to_success_page();
 
} else {
	$fail = true; // payment wasn't recorded
}

There’s just one part left, and that is redirecting back to the checkout page if there were any errors:

if( $fail !== false ) {
	// if errors are present, send the user back to the purchase page so they can be corrected
	edd_send_back_to_checkout('?payment-mode=' . $purchase_data['post_data']['edd-gateway']);
}

The complete payment processing function looks like this:

// processes the payment
function pw_edd_process_payment($purchase_data) {
 
	global $edd_options;
 
	/**********************************
	* set transaction mode
	**********************************/
 
	if(edd_is_test_mode()) {
		// set test credentials here
	} else {
		// set live credentials here
	}
 
	/**********************************
	* check for errors here
	**********************************/
 
	/*
	// errors can be set like this
	if(!isset($_POST['card_number'])) {
		// error code followed by error message
		edd_set_error('empty_card', __('You must enter a card number', 'edd'));
	}
	*/
 
	// check for any stored errors
	$errors = edd_get_errors();
	if(!$errors) {
 
		$purchase_summary = edd_get_purchase_summary($purchase_data);
 
		/**********************************
		* setup the payment details
		**********************************/
 
		$payment = array( 
			'price' => $purchase_data['price'], 
			'date' => $purchase_data['date'], 
			'user_email' => $purchase_data['user_email'],
			'purchase_key' => $purchase_data['purchase_key'],
			'currency' => $edd_options['currency'],
			'downloads' => $purchase_data['downloads'],
			'cart_details' => $purchase_data['cart_details'],
			'user_info' => $purchase_data['user_info'],
			'status' => 'pending'
		);
 
		// record the pending payment
		$payment = edd_insert_payment($payment);
 
		$merchant_payment_confirmed = false;
 
		/**********************************
		* Process the credit card here.
		* If not using a credit card
		* then redirect to merchant
		* and verify payment with an IPN
		**********************************/
 
		// if the merchant payment is complete, set a flag
		$merchant_payment_confirmed = true;		
 
		if($merchant_payment_confirmed) { // this is used when processing credit cards on site
 
			// once a transaction is successful, set the purchase to complete
			edd_update_payment_status($payment, 'complete');
 
			// go to the success page			
			edd_send_to_success_page();
 
		} else {
			$fail = true; // payment wasn't recorded
		}
 
	} else {
		$fail = true; // errors were detected
	}
 
	if( $fail !== false ) {
		// if errors are present, send the user back to the purchase page so they can be corrected
		edd_send_back_to_checkout('?payment-mode=' . $purchase_data['post_data']['edd-gateway']);
	}
}
add_action('edd_gateway_sample_gateway', 'pw_edd_process_payment');

Setting Up the Gateway Settings

In order for most payment gateways to function, you need to have the ability to store API keys or email addresses that are connected to the merchant account. Luckily, Easy Digital Downloads provides a very simple way of doing this.

All we have to do is setup an array of fields and pass it through a filter. When creating your settings, you have a variety of field types to choose from:

  • header – A section header. This just outputs a label.
  • checkbox – a simple check box field.
  • multicheck – a list of check boxes.
  • text – a simple text input field.
  • select – a drop down menu field.
  • rich_editor – a tinymce text editor field.

For our sample gateway, we are going to register three new setting fields: one for a section header, one for a live API key, and one for a test API key.

The function for registering the settings looks like this:

// adds the settings to the Payment Gateways section
function pw_edd_add_settings($settings) {
 
	$sample_gateway_settings = array(
		array(
			'id' => 'sample_gateway_settings',
			'name' => '<strong>' . __('Sample Gateway Settings', 'pw_edd') . '</strong>',
			'desc' => __('Configure the gateway settings', 'pw_edd'),
			'type' => 'header'
		),
		array(
			'id' => 'live_api_key',
			'name' => __('Live API Key', 'pw_edd'),
			'desc' => __('Enter your live API key, found in your gateway Account Settins', 'pw_edd'),
			'type' => 'text',
			'size' => 'regular'
		),
		array(
			'id' => 'test_api_key',
			'name' => __('Test API Key', 'pw_edd'),
			'desc' => __('Enter your test API key, found in your Stripe Account Settins', 'pw_edd'),
			'type' => 'text',
			'size' => 'regular'
		)
	);
 
	return array_merge($settings, $sample_gateway_settings);	
}
add_filter('edd_settings_gateways', 'pw_edd_add_settings');

$sample_gateway_settings is a multidimensional array (a separate array for each field). After the array of new fields is set up, we return the array through the array_merge() function, which combines the $settings (the existing plugin settings) with our new fields.

Our settings will look like this, in the Payment Gateways section:

Final Gateway Code

The final code for our add-on gateway looks like this:

<?php
/*
Plugin Name: Easy Digital Downloads - Sample Gateway
Plugin URL: http://easydigitaldownloads.com/extension/sample-gateway
Description: A sample gateway for Easy Digital Downloads
Version: 1.0
Author: Pippin Williamson
Author URI: https://pippinsplugins.com
Contributors: mordauk
*/
 
 
// registers the gateway
function pw_edd_register_gateway($gateways) {
	$gateways['sample_gateway'] = array('admin_label' => 'Sample Gateway', 'checkout_label' => __('Sample Gateway', 'pw_edd'));
	return $gateways;
}
add_filter('edd_payment_gateways', 'pw_edd_register_gateway');
 
function pw_edd_sample_gateway_cc_form() {
	// register the action to remove default CC form
	return;
}
add_action('edd_sample_gateway_cc_form', 'pw_edd_sample_gateway_cc_form');
 
// processes the payment
function pw_edd_process_payment($purchase_data) {
 
	global $edd_options;
 
	/**********************************
	* set transaction mode
	**********************************/
 
	if(edd_is_test_mode()) {
		// set test credentials here
	} else {
		// set live credentials here
	}
 
	/**********************************
	* check for errors here
	**********************************/
 
	/*
	// errors can be set like this
	if(!isset($_POST['card_number'])) {
		// error code followed by error message
		edd_set_error('empty_card', __('You must enter a card number', 'edd'));
	}
	*/
 
	// check for any stored errors
	$errors = edd_get_errors();
	if(!$errors) {
 
		$purchase_summary = edd_get_purchase_summary($purchase_data);
 
		/**********************************
		* setup the payment details
		**********************************/
 
		$payment = array( 
			'price' => $purchase_data['price'], 
			'date' => $purchase_data['date'], 
			'user_email' => $purchase_data['user_email'],
			'purchase_key' => $purchase_data['purchase_key'],
			'currency' => $edd_options['currency'],
			'downloads' => $purchase_data['downloads'],
			'cart_details' => $purchase_data['cart_details'],
			'user_info' => $purchase_data['user_info'],
			'status' => 'pending'
		);
 
		// record the pending payment
		$payment = edd_insert_payment($payment);
 
		$merchant_payment_confirmed = false;
 
		/**********************************
		* Process the credit card here.
		* If not using a credit card
		* then redirect to merchant
		* and verify payment with an IPN
		**********************************/
 
		// if the merchant payment is complete, set a flag
		$merchant_payment_confirmed = true;		
 
		if($merchant_payment_confirmed) { // this is used when processing credit cards on site
 
			// once a transaction is successful, set the purchase to complete
			edd_update_payment_status($payment, 'complete');
 
			// go to the success page			
			edd_send_to_success_page();
 
		} else {
			$fail = true; // payment wasn't recorded
		}
 
	} else {
		$fail = true; // errors were detected
	}
 
	if( $fail !== false ) {
		// if errors are present, send the user back to the purchase page so they can be corrected
		edd_send_back_to_checkout('?payment-mode=' . $purchase_data['post_data']['edd-gateway']);
	}
}
add_action('edd_gateway_sample_gateway', 'pw_edd_process_payment');
 
// adds the settings to the Payment Gateways section
function pw_edd_add_settings($settings) {
 
	$sample_gateway_settings = array(
		array(
			'id' => 'sample_gateway_settings',
			'name' => '<strong>' . __('Sample Gateway Settings', 'pw_edd') . '</strong>',
			'desc' => __('Configure the gateway settings', 'pw_edd'),
			'type' => 'header'
		),
		array(
			'id' => 'live_api_key',
			'name' => __('Live API Key', 'pw_edd'),
			'desc' => __('Enter your live API key, found in your gateway Account Settins', 'pw_edd'),
			'type' => 'text',
			'size' => 'regular'
		),
		array(
			'id' => 'test_api_key',
			'name' => __('Test API Key', 'pw_edd'),
			'desc' => __('Enter your test API key, found in your Stripe Account Settins', 'pw_edd'),
			'type' => 'text',
			'size' => 'regular'
		)
	);
 
	return array_merge($settings, $sample_gateway_settings);	
}
add_filter('edd_settings_gateways', 'pw_edd_add_settings');

Concluding Notes

Overall, the payment gateway process for Easy Digital Downloads is pretty simple. It may seem complex if you’re not familiar with this kind of system, but once you work with it a little, you’ll find it quite simple.

One very important thing to take note of is that when you are working with an offsite payment system, you will likely have to setup a “listener” function that will help you detect when payments are confirmed. If you are building such a system, then I would encourage you to look at the source code for the PayPal Standard gateway for a sample system.

[box style=notice]Build a complete payment gateway, let me host it, and earn 70% of every sale through Easy Digital Downloads.com[/box]

Download the Sample Gateway

The complete source code for the sample gateway can be download below.

Download Plugin
  1. Nikhil Vijay

    Hi Pippin,

    We are a payment gateway from India.We have developed plugin for EDD.I would like to know how to publish the same in EDD extensions officially.

    Thanks

  2. dev saini

    hello pippin.

    i m Dev Saini From INDIA . and i wanr to develop my own payment gateway for my ecomerce site. could u please show me the way

    • Ante

      You didn’t read with understanding, don’t u? Anyway, gr8 & awesome tutorial!

  3. Humberto Ojeda

    Hi very good colleagues afternoon forum members, I have a problem and hope you can help me, I’m doing a site and I am using Easy Digital Downloads, and I need to add a new currency for transactions, then how could solve?

    I want to add Bolivares currency, as it is for a Venezuelan site.

    I will use a platform or gateway other than paypal, this platform will make charges on VEF, CrowFounding am developing a system for a banking institution, its plugin parce me the most complete and am interested in using it, but I need the currency VEF to make transactions here in my country.

    I use a gateway used to Banesco because it is a crowdfunding project that will be used by the banking institution. However, in the short term will be used to Venezuela, and is handled bolivars, but long term could be used Paypal and spread to international levels.

    Please you can help me ??

  4. bosingwa

    hello itried this with pesapal and failed can you please help me

    • Pippin

      Sure, what part did you have trouble with?

  5. Humberto Ojeda

    Hi very good colleagues afternoon forum members, I have a problem and hope you can help me, I’m doing a site and I am using Easy Digital Downloads, and I need to add a new currency for transactions, then how could solve?

    I want to add Bolivares currency, as it is for a Venezuelan site.

    I will use a platform or gateway other than paypal, this platform will make charges on VEF, CrowFounding am developing a system for a banking institution, its plugin parce me the most complete and am interested in using it, but I need the currency VEF to make transactions here in my country.

    I use a gateway used to Banesco because it is a crowdfunding project that will be used by the banking institution. However, in the short term will be used to Venezuela, and is handled bolivars, but long term could be used Paypal and spread to international levels.

    Please you can help me ??

    Might you provide me an email to talk in a more private and quick way.

    I followed your tutorial and I have added the currency, but now I’m lockout in what is the payment process, since I can not find the way that pressing the “Submit” button through the gateway I want to implement.

    Could you help me with that Pippin ???

    • Humberto Ojeda

      Yeah, I did that, I have problems is when processing the data of the credit card in the submit button at the completion of purchase.

      I have this:

      and I need that information go to payment gateway to process the money.

      Could you please help me?

    • Humberto Ojeda

      Yeah, I did that, I have problems is when processing the data of the credit card in the submit button at the completion of purchase.

      I have this:

      and I need that information go to payment gateway to process the money.

      Could you please help me?

    • Pippin

      I’m not sure what the issue is you’re encountering, could you elaborate?

    • Pippin

      Sorry, your comments got flagged as spam so I missed them.

      Could you show me your complete code? Post it to pastebin.com and then share the link.

  6. Humberto Ojeda

    This is the code http://paste.ubuntu.com/8259736/

    my question is where i put the code or the instruction to sending data to gateway that i am using??

  7. Stefano

    Great tutorial, thank you!
    I’m developing a gateway for XPay, a very common credit card processor here in Italy.
    It basically is an offsite payment system.
    It would be great if you can show us the statement we should use to redirect to the merchant site.

    Thank you

    Stefano

  8. Eric Harris

    What about situations where the payment processor processes the payment and then sends an IPN notification only? When my processor sends a customer back to the site after a successful purchase, no data comes back with the redirect. Only to a secret URL

    • Pippin

      That is when you will need an IPN listener. You can look at how PayPal standard works in Easy Digitial Downloads core for an example.

  9. David Terrazas

    Sorry ahead of time if this is a stupid question…The Gateway Sample Code….does that go in function.php or does that code live in the plugins directory somewhere?

    I am simply trying to pass Item, Price amount and personal info to payment gateway. The gateway takes care of the CC numbers and the like. Then when done returns user to the site.

    So is this tutorial you have provided overkill for what I am trying to do. I am bound to our University’s gateway client Touch-Net so I don’t have any options there.

    Thanks

    David T.

  10. David Terrazas

    I have figured out that the code does indeed go into the function.php, so I have already answered my previous question.

    Thanks

    • Pippin

      Glad to hear it!

  11. Kivanc

    Hi Pippin!
    How can i use curl method to send an xml to the merchant site?

    • Pippin

      It’ll be the same way that you’d make any other cURL request.

  12. Marcio

    Hi Pippin?
    I’m doing some testing, I’m trying to create something using the “Boilerplate WordPress Plugin” from “Tom Macfarlin”, but I can’t register the edd_sample_gateway_cc_form action.
    example of code:
    $this-> loader-> add_action (‘ edd_sample_gateway_cc_form ‘, $plugin _ admin, ‘ pw_edd_sample_gateway_cc_form ‘);
    hints on how to use it? because that way nothing happens
    NOTE: I’m a beginner in php

    • Pippin

      Are you trying to display the CC form or remove it?

  13. Yogesh Gupta

    Can i integrate CommonWealth payment gateway in EDD?
    Please suggest.

  14. LEE

    Great, I think this is what I am looking for as, thank you….

  15. Tilak

    Hi Pippen,

    I want to integrate OMEGA payment gateway (omegap.com). Can you suggest, how it could be possible to add?

    • Pippin

      You will need to look and see if they have an API and then follow their API documentation to integrate it.

Error: Please enter a valid email address

Error: Invalid email