Notice: As of Aug 30, 2022, this wrapper is no longer updated or maintained.

Chargify API wrapper for Ruby (using ActiveResource)

This is a community-maintained Ruby wrapper for the Chargify API that leverages ActiveResource.

Though we do not proactively maintain it, Chargify is happy to review pull requests and manage the release process for the gem. We encourage community contributions to make the wrapper even more comprehensive and powerful.

If you notice an endpoint or method that is missing, please feel free to add it by submitting a pull request. We appreciate your support!

Note: we have bumped to v1.0.0 to indicate a backwards incompatible change to the responses from Chargify::Subscription.charge and Chargify::Subscription.migrate. Please see the HISTORY.md for more information.

Please see important compatibility information at the bottom of this file.

Installation

This library can be installed as a gem. It is hosted on Rubygems.

You can install this library as a gem using the following command:

$ gem install chargify_api_ares

Usage

Simply require this library before you use it:

require 'chargify_api_ares'

If you're using Rails 3.x, you could include this gem in your Gemfile.

gem 'chargify_api_ares'

Install the gem using the following command: $ bundle install

If you're using Rails 2 you could include this gem in your configuration, i.e. in environment.rb

config.gem 'chargify_api_ares'

To configure api key, site, domain, and protocol you can do the following. Please note that this step is required.

Most common usage

  Chargify.configure do |c|
    c.api_key   = "your_key_goes_here"
    c.subdomain = "test-site"
  end

Overriding the endpoint

  Chargify.configure do |c|
    c.api_key   = "your_key_goes_here"
    c.site      = "https://test-site.some-domain.com"
  end

Available configuration options

Name	Description	Default	Required
api_key	The api_key credentials that are used to access your chargify account.	N/A	Yes
subdomain	The subdomain (site name) of the chargify endpoint you are trying to interact with	test	Yes (unless site was used)
domain	The domain of the endpoint, in which you want to interact with.	chargify.com	No
protocol	The endpoint protocol that you wish to use (http / https)	https	No
site	This is meant to override all three of the previous settings eg: http://foo.bar.com	N/A	No
format	The format of the request and response type that you want to deal with	xml	No
timeout	The time in seconds for a request to be valid. Will raise a timeout error if exceeds time limit.	N/A	No

Now you'll have access to classes the interact with the Chargify API, such as:

• Chargify::Product
• Chargify::Customer
• Chargify::Subscription

It allows you to interface with the Chargify API using simple ActiveRecord-like syntax, i.e.:

Chargify::Subscription.create(
  :customer_reference => 'moklett',
  :product_handle => 'chargify-api-ares-test',
  :credit_card_attributes => {
    :first_name => "Michael",
    :last_name => "Klett",
    :expiration_month => 1,
    :expiration_year => 2010,
    :full_number => "1234-1234-1234-1234"
  }
)

subscription.credit_card_attributes = { :expiration_year => 2013 }
subscription.save

subscription.cancel

Note

Updating nested resources is not supported nor recommended. If you wish to update a subscriptions customer please do so by updating the customer object itself.

Bad:

subscription = Chargify::Subscription.find(123)
subscription.customer.first_name = 'fred'
subscription.customer.save

Good:

subscription = Chargify::Subscription.find(123)
customer     = Chargify::Customer.find(subscription.customer.id)
customer.first_name = 'fred'
customer.save

Check out the examples in the examples directory. If you're not familiar with how ActiveResource works, you may be interested in some ActiveResource Documentation

Duplicate Prevention

Duplicate Prevention is supported by including the uniqueness_token attribute, for example:

subscription = Chargify::Subscription.create(
  :product_handle => 'product-with-trial',
  :customer_attributes => {
    :first_name => "Test",
    :last_name => "Customer",
    :email => "test@example.com"
  },
  :uniqueness_token => "abc-123-def-456"
)

Statements PDF retrieving

File.open(file_path, 'wb+') do |f|
  f.write Chargify::Statement.find_pdf(statement.id)
end

Compatibility

• Rails/ActiveResource 2.3.x, use 0.5.x
• Rails/ActiveResource 3.x, use 0.6 and up

chargify_api_ares	Rails 2.3.x	Rails 3.0.0 - 3.0.19	Rails 3.0.20 and up
0.5.x	OK	Incompatible	OK
0.6.x	Incompatible	OK (Monkey-patched)	OK

The problem with Rails/ActiveResource/ActiveModel 3.0.0 - 3.0.19

Prior to Feb 12, 2013, Chargify would silently refuse to parse XML which contained data specified as YAML, such as:

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <name>John</name>
  <email type="yaml" nil="true"/></email>
</person>

After Feb 12, 2013, Chargify returns a 400 Bad Request response if your XML contains any type="yaml" attribute, since there is no valid reason to send YAML serialized data to Chargify and doing so smells strongly of an attempt to exploit CVE-2013-0156.

However, Rails/ActiveModel versions 3.0.0 to 3.0.19 had a bug (see rails/rails#8853) where any nil attribute would have a type="yaml" attribute added during XML serialization.

Using ActiveResource 3.0.0 - 3.0.19 along with 0.5.x or lower of this gem may result in your sending type="yaml" XML to Chargify. Thus, your requests will be rejected.

Version 0.6.x of this gem will attempt to patch your ActiveModel if you have an incompatible version. To avoid this patch, you should use 3.0.20 or higher of ActiveResource.

Contributing

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for the feature/bugfix
• Please squash your commits.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate it to its own commit so we can cherry-pick around it.

Contributors

We would like to publicly thank everyone who has contributed their time and talents to developing this gem. Thank you!