### 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.custid   = 'your_custid'
		TrustCommerceGateway.password = 'your_password'
		
		# (optional) Sets vault password for use in query() calls
		TrustCommerceGateway.vault_password = 'your_vault_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 TC_VAULT_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
	
**Make a one-time sale against an existing subscription**

	response = TrustCommerceGateway::Subscription.charge(
	  :billingid  => 'ABC123',
	  :amount     => 1995
	)	

**Issue a credit against an previous transaction**

	response = TrustCommerceGateway::Subscription.credit(
	  :transid  => '001-0000111101',
	  :amount   => 1995
	)

**Fetch all transactions for a customer in CSV format**

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

Author: Zack Chandler  
Email: zackchandler@depixelate.com  
Code: http://svn.depixelate.com/plugins/trustcommerce_subscription/
		
[Citadel]:								http://www.trustcommerce.com/citadel.php
[TrustCommerce]:					http://www.trustcommerce.com
[TCLink ruby extension]:	http://www.trustcommerce.com/tclink.php