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:
- Registering the gateway
- Setting up the credit card form, if any
- Processing the payment
- 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:
1 2 3 4 5 6 | // 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:
1 2 3 4 5 6 | // 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:
1 2 3 4 5 | 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | // 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).
1 2 3 4 | 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:
1 2 3 4 5 6 7 8 9 | /********************************** * 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:
1 2 3 4 5 | // 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:
1 2 3 4 5 6 7 | // 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.
1 | $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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | /********************************** * 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | $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:
1 2 3 4 | 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 | // 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | // 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | <?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: http://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.
Download the Sample Gateway
The complete source code for the sample gateway can be download below.
Download Plugin
Thanks for this. Much appreciated. It makes a great demonstration of creating an add-on for digital downloads.
Thanks. This is just one example of the add-ons you can create for EDD. I will be publishing many more similar tutorials for other aspects of Easy Digital Downloads.
I am using the version
i dont have the manual payment version. 1.2.2
how can i get this option enabled again?
thanks for your reply.
i am using offline payment normally… with able to verify payment, and enabled download for user…
This is not the place to ask this question. Please post it in the Easy Digital Downloads support forum.
Hi,
Thank you for this plugin!
The only problem that I encountered in the customization are in the following:
1. purchase_data <= 0 automatically renders to manual gateway even with the customized already set.
2. if the $_GET payment-mode is set but still with the cart amount == 0, it will still use the manual gateway.
3. if the $_GET payment-mode is set, there's no way to have this variable set in the Checkout Page field chosen in General Settings
Cart amount == 0 is for freebies.
Maybe a different approach is to have the default 'manual' configurable to the preferred gateway.
1. Yes, that is the intended behavior. It emulates a “free” purchase and bypasses the funds transfer.
2. That is also intended behavior for the same reason.
3. This parameter is set automatically if there is an error and the page needs to reload, or when the payment gateway is first selected.
Hi, Can I set a new order always ‘pending’ ?
Yes, when you do edd_insert_payment(), set “status” => “pending” in the arguments.
when I paste this code i have result how ‘test gateway’… but I want new order always pending;
I mean… add to cart – fill out the form – custom finally page; and admin must change order status;
is it possible ?
Yes, if you do exactly as I said, that is the default behavior.
when I fill out the form I get mail with info about download file (automatic order status complete)
Ok show me your complete gateway code. Please paste it to snippi.com and share the link.
http://snippi.com/s/f8as1q2
This is the line that completes the purchase:
Remove that and it will remain pending.
thank you for help
Sir i have a payment gateway code … this is first time i m doing this….
Please help me to make it work , i am in need very badly…
Can i send u the code???
Please make a help , this is gonna decide my future
:’(
I am doing payment gateway integration for very first time…
This is a task which will decide my future, is there any one who can help me plzzzzz
I have the code and i just don’t know wat to do with it
I need more details than that to help you out.
What payment system are you working with?
Hello,
Has anyone implemented this for PesaPal?
http://developer.pesapal.com/
Just asking, before working on it myself )
Great work by the way, Pippin, thanks!
Kamiel
Not that I’m aware of!