Cardflex Ruby Client Library (Unofficial)

This gem provides client integration with the Cardflex API: https://secure.cardflexonline.com/gw/merchants/resources/integration/integration_portal.php. Currently, only the operations under the Three Step Integration are supported. This gem is supported by the community and is not associated with Cardflex.

Installation

gem install cardflex-ruby

Or add this line to your Gemfile:

gem "cardflex-ruby"

And run a bundle install

Usage

Before you can perform any actions, you must set your api_key:

Cardflex::Configuration.api_key = "my_api_key"

You can also change the logger (default is stdout):

Cardflex::Configuration.logger 

To start step 1 of a transaction, use the Three Step API to initiatialize the request process, and use the result to set the form URL for part 2:

# See Cardflex documentation for required parameters
step_one = Cardflex::ThreeStep.sale({
  :redirect_url => "https://example.com",
  :amount => 5.00
})

if step_one.success?
  @form_url = step_one.three_step.form_url
else
  @error_message = step_one.result_text
end

When you complete step one in the three step API, you will receive the returned data in the #three_step attribute if the request succeeded.

During step 2, you will present to your users a form that will POST to Cardflex using the form_url you received from Cardflex in step 1. Then, the user will be redirected to the :redirect_url supplied in the initial request, with a token_id that you send back to Cardflex to complete the transaction in the query string:

token_id = params['token_id']

result = Cardflex::ThreeStep.complete(token_id)

if result.success?
  # payment has been processed, send user the all clear
  # the result of the transaction is in result.transaction
  result.transaction.transaction_id
else
  @error_message = result.result_text
end

The library will automatically add your api key to each request. You can also access these methods via the ThreeStep API:

# Transactional Methods
ThreeStep#sale
ThreeStep#credit
ThreeStep#auth
ThreeStep#offline
ThreeStep#validate

# Recurring Methods
ThreeStep#add_subscription
ThreeStep#update_subscription

# Customer Vault Methods
ThreeStep#add_customer
ThreeStep#update_customer
ThreeStep#add_billing
ThreeStep#update_billing

The methods above exist for your convenience, and take care of adding the root level XML node to the request. If you want to control the full XML request, you can use this method to do it all yourself (api key is still added):

# Step One
Cardflex::ThreeStep.get_form_url(:sale => {
  :redirect_url => "https://example.com",
  :amount => 5.00
})

When a three step response completes step 3, it will return all the data to you inside of the #transaction attribute, as all three step actions are transactional in nature.

Other Features

In addition to supporting the Three Step API, you can also perform a few other actions that do not involve sensitive information, and so you are freed from having to use the Three Step process:

Plan#create
Subscription#delete
CustomerVault#sale
CustomerVault#credit
CustomerVault#auth
CustomerVault#offline
CustomerVault#delete_customer
CustomerVault#delete_billing
Transaction#void
Transaction#capture
Transaction#refund

When these methods return, you can find the response inside of the #plan, #subscription, #customer_vault, and #transaction attributes, respectively.

More Information

You can find all the Cardflex documentation here: https://secure.cardflexonline.com/gw/merchants/resources/integration/integration_portal.php

Tests

The tests run against the Cardflex API using the testing account. You will need an internet connection to run some of the tests.

Contributing

All pull requests that add tests, clean up the code, add features, or fix issues are welcome. Be sure to write tests for any and all changes to the code base, and make sure all tests pass before submitting.

License

MIT. See LICENSE file.