This plugin provides a simple interface to create, edit, delete, and query subscriptions using the TrustCommerce Citadel API. This is most useful if you have an application that needs to bill on a monthly or quarterly basis and would like to avoid the liability of storing customer credit card information and the hassle of being CISP compliant.

Note: This plugin is being used in production at Service Sidekick.

TrustCommerce Subscription plugin

TrustCommerce is a payment gateway providing credit card processing and subscription/recurring billing services.

TrustCommerce implements recurring billing through a service named Citadel.

This plugin provides a simple interface to create, edit, delete, and query subscriptions using the TrustCommerce Citadel API.

Setup

1. Install the plugin.

   ./script/plugin install http://svn.depixelate.com/plugins/trustcommerce_subscription
   

2. Contact TrustCommerce and request a Citadel-enabled test account.

3. Setup your TrustCommerce credentials in environment.rb.

   TrustCommerceGateway::ACCOUNT_SETTINGS = {
     :custid   => 'your_customer_id',
     :password => 'your_password'
   }
   

4. (optional) Install the TCLink ruby extension.

   It is highly recommended to download and install the extension as it provides fail-over capability and enhanced security features. If this library is not installed, the plugin will fall back to standard POST over SSL.

5. (optional) Run the tests (see testing section below).

6. You're ready to go! See usage section on ideas on integrating with your app.

Testing

Important! You must have a TrustCommerce account setup with Citadel support before running these tests!

You can set the appropriate environment variables from the command line and run the tests like this:

export TC_USERNAME=username TC_PASSWORD=password
ruby vendor/plugins/trustcommerce_subscription/test/trustcommerce_subscription_test.rb

Note: Use 'set' command on windows in place of export

About Citadel

Merchants create a billing profile through Citadel including customer information, credit card data, and billing frequency. Citadel stores the information and issues the merchant a Billing ID. A Billing ID is a six-character alphanumeric string identifying the customer profile.

Merchants can modify the customer's information, credit card data, or billing frequency anytime using the issued Billing ID.

Usage

Create a $12.00 monthly subscription for Jennifer Smith

response = TrustCommerceGateway::Subscription.create(
  :cc =>        '4111111111111111', 
  :exp =>       '0412', 
  :name =>      'Jennifer Smith',
  :amount =>    1200,
  :cycle =>     '1m',
  :demo =>      'y'
)

if response['status'] == 'approved'
  puts "Customer profile created with Billing ID: #{response['billingid']}"
else
  puts "An error occurred: #{response['error']}"
end

Modify subscription with a new credit card

response = TrustCommerceGateway::Subscription.update(
  :billingid =>  'ABC123',
  :cc =>         '5411111111111115', 
  :exp =>        '0412'
)

if response['status'] == 'accepted'
  puts "Customer profile updated"
else
  puts "An error occurred: #{response['error']}"
end

Cancel subscription

response = TrustCommerceGateway::Subscription.destroy(
  :billingid =>  'ABC123'
)

if response['status'] == 'accepted'
  puts 'Customer profile removed from active use'
else
  puts 'An error occurred'
end

Fetch all transactions for a customer in CSV format

response = TrustCommerceGateway::Subscription.query(
  :querytype  => 'transaction',
  :action     => 'sale',
  :billingid  => 'ABC123'
)