Stripe - Setup Documentation

This page describes how to setup the Stripe.com add-on payment gateway, available here.

API Keys

In order to use the Stripe payment gateway extension, you must first have a Stripe.com account. It's free to create a Stripe account, and testing it is also free.Once you have purchased the Stripe Payment Gateway, install it just like any other WordPress plugin. After it is installed and activated, go to Downloads → Settings → Payment Gateways, and enable the gateway:

Next, scroll down to where it says "Stripe Settings". You'll find four fields in which you will need to enter your Stripe.com API keys. To obtain these keys, go to your  Stripe.com Dashboard and click on "Your Account" and then choose "Account Settings".

This will open a new window, from here choose "API Keys" and enter the four keys found on that page into the Easy Digital Download's "Stripe Settings" section.

Now click "Save Changes". Your Easy Digital Downloads store is now connected to your Stripe account and can process sales.

Additional settings

There are additional settings to configure below.

Billing Address Display

This drop down field will allow you to select which billing details are collected. There are three options:

  • Full address - This will result in a complete address form with street, city, country, state / province, and zip / postal code being displayed.
  • Zip / Postal Code and Country only - This will result in a simplified address form being displayed that asks only for zip / postal code and country.
  • No address fields - This will result in no address fields being displayed.

Taxes note: if you have taxes enabled, only the full address option may be used as those fields are required for accurately calculating taxation amounts.

Fraud note: collecting a full billing address can help reduce fraudulent charges. It is recommended that minimum zip / postal code and country be collected.

Preapprove Only?
Check this if you would like to preapprove payments but not charge until the payment status gets set to "Complete". If you choose this option, Stripe will not charge the customer right away after checkout, and the payment status will be set to "preapproved" in Easy Digital Downloads. You (as the admin) can then manually change the status to "Complete" by going to Dashboard → Downloads → Payment History → Find the payment in question and view it → C hange the status to "Complete" on the side of the screen under "Status". Once you change it to "Complete" the customer will be charged. Note that most typical stores will not need this option.

Stripe Checkout Options

With Stripe, there are two ways to collect credit / debit card details from customers:
  1. The standard, on-site credit card form shown in the main Easy Digital Downloads checkout form.
  2. The modal payment window offered through Stripe called Stripe Checkout.

Both options are fully supported and screenshots of what each looks like can be seen below.

Standard, on-site form:

Stripe Checkout modal:

Enable Stripe Checkout

This option lets you enable / disable the Stripe Checkout modal on the main EDD checkout page.

Complete Purchase Text

This option allows you to define the text that is shown on the checkout page's submit button when using Stripe Checkout. This is the button customer's click to open the Stripe Checkout payment window where they will enter their card details.

Checkout Logo

Stripe Checkout can display a logo image at the top of the modal payment window. Upload the logo (if any) you would like displayed here.

Enable Billing Address

When using Stripe Checkout, the modal payment window can be configured to only ask for  the card number, expiration date, and security code, or it can be set to also collect and validate the billing address for the card. If you would like to collect and validate the billing address (this is more secure), check this option.

Buy Now Buttons Through Stripe Checkout

The  Stripe Checkout system allows you to embed a purchase form directly on any page so that when a custom clicks on the purchase button, they are immediately presented with a secure credit/debit card form:

Screenshot from 2014-10-23 14:06:39

To enable Stripe Checkout for a Download product, go to the Edit screen and select Buy Now from the Button Behavior drop down:

Screenshot from 2014-10-23 14:08:18

Once set to Buy Now purchase buttons for this product will automatically use the Stripe Checkout pop up.

If you are using the  [purchase_link] shortcode to add a purchase button to a page, simple add direct="true" to the shortcode to specify it as a Buy Now button.

[purchase_link id="56" direct="true"]

Important notes about Buy Now buttons with Stripe Checkout:

  • Stripe Checkout is the name of a specific Stripe implementation that uses a modal pop-up window for checkout, and does NOT use the normal Checkout Page
  • SinceBuy Now buttons bypasses the checkout screen, taxes cannot be collected
  • Discount codes cannot be used with Buy Now buttons
  • The Recurring Payments extension does not support the Stripe Checkout with Buy Now buttons even though the official Stripe Checkout docs say that Stripe Checkout itself supports recurring payments. You can, however, use Stripe Checkout with Recurring Payments on the main EDD checkout page.

Automatic Refund Processing

The Stripe payment gateway can automatically detect refunded purchases in your Stripe account. When a refund is detected, the corresponding purchase in EDD is also marked as refunded.

To enable automatic refund processing, you must add a new Webhook URL for your site in your Stripe Dashboard → Settings → Webhooks. The URL should be set to:

https://example.com/?edd-listener=stripe

Recurring Payments Integration

This payment gateway has complete support for the  Recurring Payments extension. See the Recurring Payments Stripe set up documentation for configuration instructions.

System Requirements

In order for Stripe to work you must have the Multibyte String PHP extension installed on your server.