This add-on is operated by Spreedly

An independent credit card vault in the cloud connected to 70+ payment gateways.


Last Updated: 07 May 2015

Table of Contents

Spreedly is an add-on for connecting to a Software-as-a-Service billing solution that serves two major functions for companies and developers.

  • First, it reduces your PCI Compliance requirement by pushing the card data handling and storage outside of your application. This is possible by having your customers POST their credit card info to the Spreedly service while embedding a transparent redirect URL back to your application (see the build payment form docs for more information).
  • Second, it removes any possibility of your gateway locking you in by owning your customer billing data (yes, this happens). By allowing you to charge any card against whatever gateways you as a company have signed up for, you retain all of your customer data and can switch between gateways as you please. Also, expanding internationally won’t require an additional technical integration with yet another gateway.

Spreedly is accessible via an API and has supported client libraries for Ruby.

Installing the add-on

Spreedly can be installed using the Heroku UI or via the CLI:

$ heroku addons:create spreedlycore:developer
-----> Adding spreedlycore to glowing-bull-311... done, v18 (free)
-----> Successfully provisioned Spreedly.

Once Spreedly has been added your API login and secret will be available in the app configuration. These items will be used when making requests against the Spreedly API. Check to make sure the addon was successfully installed by running heroku config.

$ heroku config | grep SPREEDLYCORE
SPREEDLYCORE_API_SECRET:      => dTmEGwJSMdabbrREzimp1QZDzZeyl99PpgP84kLTwPl9Pm5hpYzK4NmMSySvhuLN

After installing Spreedly the application should be configured to fully integrate with the add-on. You may notice some other ENV variables defined. They’re in place for backward compatibility reasons. You can safely disregard them.

Using with Rails

Add the spreedly gem

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Spreedly gem.

gem 'spreedly'

Update application dependencies with bundler.

$ bundle install

You can see docs for the spreedly gem on Github.

Deploy the updated Gemfile to Heroku:

$ git add .
$ git commit -m "Added spreedly gem"
$ git push
$ git push heroku master

-----> Heroku receiving push
-----> Launching... done, v3
       http://glowing-bull-311.herokuapp.com deployed to Heroku

To git@heroku.com:glowing-bull-311.git
 * [new branch]      master -> master


Create a test gateway

Drop into console and create a test gateway to run test transactions against

$ heroku run console
Running console attached to terminal... up, run.1

gateway = env.add_gateway(:test)
puts "Test gateway token is #{gateway.token}"

To use the test gateway in Heroku while you’re developing, just set its token in the Heroku environment:

$ heroku config:set SPREEDLYCORE_GATEWAY_TOKEN=test_gateway_token

Add a payment form

After a test gateway is created, payment forms must be created or modified to post the credit card data directly to Spreedly. Spreedly will receive your customer’s credit card data, and immediately transfer them back to the location you define inside the web payments form. The user won’t know that they’re being taken offsite to record to the card data, and you as the developer will be left with a token identifier. The token identifier is used to make your charges against, and to access the customer’s non-sensitive billing information.

<form action="https://core.spreedly.com/v1/payment_methods" method="POST">
      <input name="redirect_url" type="hidden" value="http://example.com/transparent_redirect_complete" />
      <input name="environment_key" type="hidden" value="<%= ENV['SPREEDLYCORE_ENVIRONMENT_KEY'] %>" />
      <label for="credit_card_first_name">First name</label>
      <input id="credit_card_first_name" name="credit_card[first_name]" type="text" />

      <label for="credit_card_last_name">Last name</label>
      <input id="credit_card_last_name" name="credit_card[last_name]" type="text" />

      <label for="credit_card_number">Card Number</label>
      <input autocomplete="off" id="credit_card_number" name="credit_card[number]" type="text" />

      <label for="credit_card_verification_value">Security Code</label>
      <input autocomplete="off" id="credit_card_verification_value" name="credit_card[verification_value]" type="text" />

      <label for="credit_card_month">Expires on</label>
      <input id="credit_card_month" name="credit_card[month]" type="text" />
      <input id="credit_card_year" name="credit_card[year]" type="text" />

      <button type='submit'>Submit Payment</button>

Take special note of the environment_key and redirect_url params hidden in the form, as Spreedly will use both of these fields to authenticate the developer’s account and to send the customer back to the right location in your app. You can also find more docs on the Spreedly site.

A note about test card data

Users of the free tier of the addon will only be permitted to deal with test credit card data.

Do not use real credit card data until your application is live.

  • Visa
    • Good Card - 4111111111111111
    • Failed Card - 4012888888881881
  • MasterCard
    • Good Card - 5555555555554444
    • Failed Card - 5105105105105100
  • American Express
    • Good Card - 378282246310005
    • Failed Card - 371449635398431
  • Discover
    • Good Card - 6011111111111117
    • Failed Card - 6011000990139424

Submit a test card as a payment method

Load your payment form and use one of the test credit cards above to submit a payment method to Spreedly. The payment details will be recorded, and you will be transferred back to your application with an additional URL parameter corresponding to the newly-created payment method’s token.

At this point, you have a payment method token and a gateway token. Once you have these two tokens, there are all kinds of things you can do. You also find additional docs to use the gem for purchases, authorizations, captures, refunds, etc.

Creating and using a real gateway

When you’re ready for primetime, you’ll need to complete a couple more steps to start processing real transactions.

  1. First, you’ll need to upgrade your plan on the Heroku site to the Starter or Pro plan.
  2. Second, you’ll need to acquire a gateway that you can plug into the back of Spreedly. Any of the major players will work, and you’re not at risk of lock-in because Spreedly happily plays middle man. Please consult our list of supported gateways to see exactly what information you’ll need to pass to Spreedly when creating your gateway profile.

For this example, an Authorize.net account that only has a login and password credential will be used. First, changed the Spreedly addon to the paid tier.

$ heroku addons:upgrade spreedlycore:starter

Then, drop into a heroku console to create your production gateway

gateway = env.add_gateway(:authorize_net, login: 'my_authorize_login', password: 'my_authorize_password')
puts "Authorize.net gateway token is #{gateway.token}"

Now you have an Authorize.net gateway token you can process against.


We’re happy to answer any questions you might have at support@spreedly.com.

Full documentation

Full documentation is available via the Spreedly website: