# 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

```shell
gem install cardflex-ruby
```

Or add this line to your Gemfile:

```ruby
gem "cardflex-ruby"
```

And run a bundle install

## Usage

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

```ruby
Cardflex::Configuration.api_key = "my_api_key"
```

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

```ruby
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:

```ruby
# 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
```

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:

```ruby
token_id = params['token_id']

result = Cardflex::ThreeStep.complete(token_id)

if result.success?
  # payment has been processed, send user the all clear
else
  @error_message = step_one.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):

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

## 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
```

## 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.