Slidepay Ruby Sdk

Using the Gem

Add the following line to your Gemfile:

gem 'slidepay'

Dependencies

We depend on these fantastic libraries:

Building the Gem

From the root of the repository, run the gem build command:

$ gem build slidepay.gemspec

How Does SlidePay's API Work?

Check out our main documentation for detailed information about how the API works, as well as information about functionality not yet wrapped by this library.

The Ruby SDK Basics

Requests can be made three ways:

Using the SlidePay request methods directly with the desired API url and relevant request JSON
Using an instance of the SlidePay::Client class to save an ApiResource, such as a payment, bank_account, or api_key
Using an instance of a SlidePay::ApiResource class, such as SlidePay::ApiKey or SlidePay::Payment

Authentication

A request to SlidePay is considered authenticated if either an api_key or token are present in the request. Information about how those are sent, and how they are obtained, can be found on the authentication page of the api documentation.

Both the api_key and token can be set in a global, instance, and request context. The order of precedence goes from most to least specific, and tokens are of greater significance than api_keys. This means that an api_key provided to an instance of an ApiResource would be used over a global token, but would be ignored in the face of a token set on that same object, and would yield to either provided to a single request method.

Either of these fields can be set globally by assigning SlidePay.token or SlidePay.api_key:

SlidePay.token = "MY_TOKEN"

SlidePay.api_key = "MY_API_KEY"

The global token can also be set using the global SlidePay authentication method:

SlidePay.authenticate(email, password)

You can retrieve a token for use in any context with the retrieve_token method, which is similar to SlidePay.authenticate except that it returns the token string and does not set a global token value.

SlidePay.retrieve_token(email, password)

These fields can also be used on an instance or per-request level by either passing them into the SlidePay module request methods as a field in a hash, or by assigning instance variables on a SlidePay::Client.

SlidePay.get(path: "payment/#{payment_id}", token: "MY_TOKEN")

SlidePay.get(path: "payment/#{payment_id}", api_key: "MY_API_KEY")

Resources

The Ruby SDK provides explicit interfaces to the following SlidePay resources:

api_key through the ApiKey class
bank_account through the BankAccount class
payment through the Payment class
user_master through the UserMaster class
customer through the Customer class

All of the above resource classes inherit class- and instance-level functionality from SlidePay::ApiResource.

As a result, each resource class provides common searching and CRUD functionality.

Search

Each ApiResource offers several class-level search methods:

find(search_filter_array)
find_where(value_hash)
find_between(start_value_hash, end_value_hash)
find_greater_than(value_hash)
find_less_than(value_hash)

Each of these methods will return an array of zero or more instances of the ApiResource class.

find(search_filter_array)

find is a flexible interface for searching SlidePay resources. Search parameters must be supplied in the form of a search filter array. To supply them, pass an array of search filter Hashes as the first parameter.


# Find users whose first name contains "at"
users = SlidePay::UserMaster.find(field: "first_name", condition: "contains", value: "at")

# Find all users whose first name is "Matt"
users = SlidePay::UserMaster.find(field: "first_name", condition: "equals", value: "Matt")

find_where(value_hash)

find_where allows you to specify equality constraints in your search. For instance, the following example is equivalent to the second find example above.


# Find all users whose first name is "Matt"
users = SlidePay::UserMaster.find_where(first_name: "Matt")

find_greater_than(value_hash) and find_less_than(value_hash)

find_greater_than and find_less_than allow searching for resources with values greater than or less than what is provided in the hash.


# Find all payments greater than $200.00
payments = SlidePay::Payment.find_greater_than(amount: 200.00)

# Find all payments less than $10.00
payments = SlidePay::Payment.find_less_than(amount: 10.00)

# Find all users created after 10/12/2013 at 12:00 AM
users = SlidePay::UserMaster.find_greater_than(created: "10/12/2013")

# Find all users created before 10/05/2013 at 12:00 AM
users = SlidePay::UserMaster.find_less_than(created: "10/05/2013")

find_between(start_value_hash, end_value_hash)

find_between takes two value hashes as arguments to combine the functionality of find_greater_than and find_less_than.


# Find all payments made between 10/05/2013 and 10/12/2013
start_values = { created: "10/05/2013" }
end_values = { created: "10/12/2013" }
payments = SlidePay::Payment.find_between(start_values, end_values)

# Find all payments between $3.00 and $10.00
start_values = { amount: 3.00 }
end_values = { amount: 10.00 }
payments = SlidePay::Payment.find_between(start_values, end_values)

CRUD (Create, Read, Update, Delete)

Each ApiResource class provides RESTful CRUD functionality through the following instance methods:

save
destroy
retrieve

The save method can handle both creation via POST, and updating via PUT. It determines which verb is appropriate by the ApiResource.is_new? method, which checks for data in the appropriate *_id field of the resource.

Payments

Payments are much like resources, except they cannot be updated or destroyed once created. Two more relevant instance methods for interacting with payments are provided.

To process a payment, supply a JSON representation of a valid simple_payment object on instantiation, and then call that instance's process method:

p = SlidePay::Payment.new(simple_payment_json)
p.process()

To refund a payment, call an existing payment's refund method, or POST to the payment/refund/:payment_id API path:

# Refund from an object
p.refund()

# Refund using SlidePay.post
SlidePay.post(path: 'payment/refund/#{payment_id}')

Reports

The SlidePay reports allow broader views into a user's data. The reports retrieve this data based on constraints supplied in the Report class constructor.

We currently expose two reports through the Ruby library: an Account Report and a Payment Report.

Account Report

The account report gives a view into the current state of the SlidePay user's account.

The only valid constraint for this report is on location_id, and may be supplied in the ways illustrated below.


# Pass the location_id constraint in as an integer
account_report = SlidePay::AccountReport.new(14)
account_report.retrieve()

# Pass the location_id constraint in as a string
account_report = SlidePay::AccountReport.new("14")
account_report.retrieve()

# Pass the location_id constraint in as a hash
account_report = SlidePay::AccountReport.new(location_id: 14)
account_report.retrieve()

Payment Report

The payment report gives a detailed view into the past payments for an account. The report can be constrained in many dimensions using one or more search_filters.

Search filters are optional, should be supplied on object instantiation, and can be supplied through a hash (if there is only one), or as an array (for > 0 search filters).


# Supply no search filter to retrieve all payment data accessible by the currently authenticated account
payment_report = SlidePay::PaymentReport.new()
payment_report.retrieve()

# Supply a single search filter as a hash
single_time_search_filter = {field: "created", condition: "greater_than", value: "12/12/2013"}
payment_report = SlidePay::PaymentReport.new(single_time_search_filter)
payment_report.retrieve()

# Supply multiple search filters in an array
search_filter_array = []
search_filter_array.push({field: "created", condition: "greater_than", value: "10/12/2013"})
search_filter_array.push({field: "created", condition: "less_than", value: "12/12/2013"})
search_filter_array.push({field: "amount", condition: "greater_than", value: 1.01})

payment_report = SlidePay::PaymentReport.new(search_filter_array)
payment_report.retrieve()

ACH

SlidePay supports ACH retrievals, programmatic settlements via ACH, and checking the balance of unsettled funds for an account.

Balance

To check the balance of a settlement ledger, just provide a location_id to the Balance.retrieve class method.

location_id = 18
balance = SlidePay::ACH::Balance.retrieve(location_id)

ACH Retrieval

To initiate an ACH retrieval from a bank account, supply a hash with bank account details to the Retrieval.create_with_bank_account class method, or create an instance of the Retrieval class and use the instance method of the same name.

A retrieval can be initiated using either a stored bank account or explicit bank account details. A full explanation of the differences can be found on the ACH retrieval documentation page.

retrieval_info = {
  location_id: 12,
  company_id: 10,
  bank_account_id: 3,
  user_master_id: 20,
  retrieval_amount: 1.02
}

# class method
r = ACH::Retrieval.create_with_bank_account(retrieval_info)

# instance method - the retrieval instance will be populated with the
# retrieval response data from the server.
r = ACH::Retrieval.new()
r.create_with_bank_account(retrieval_info)

ACH Settlement

SlidePay users can settle funds from an account ledger to one or more bank accounts programmatically via ACH. Note: To do this, an account must have manual settlement enabled. Complete documentation for ACH settlements lives on the documentation page.

To initiate an ACH settlement to one or more bank accounts, supply a settlement descriptor Hash to the Settlement.process method in the following format:

settlement_descriptor = {
  location_id: YOUR_LOCATION_ID,
  company_id: YOUR_COMPANY_ID,
  settlement_list:[
    { bank_account_id: FIRST_SETTLEMENT_BANK_ACCOUNT_ID, amount: 0.25 },
    { bank_account_id: SECOND_SETTLEMENT_BANK_ACCOUNT_ID, amount: 0.25 }
  ],
  notes:'Really important notes about this settlement. '
}

The Settlement.process class method will return an array of transaction processor responses corresponding to the list of settlements requested.


# Process the settlement
settlment_result = SlidePay::ACH::Settlement.process(settlement_descriptor)

Testing

Basics

Test are in the spec directory, and can be run from the root of the repository:

$ rspec spec

Automatic Testing

There is also a Guardfile in the root directory of the library that will help test changes automatically. If you intend to modify this code, we highly recommend you configure Guard on your system to make use of this.

Once installed, run the Guard monitor from the root of the repository:

$ guard

Scenarios Requiring Account Information

Some tests, the ones in the scenarios directory, will require that you have an active SlidePay account on the development server, and that you supply those credentials in an environment.rb file in the root of this repository.

Your populated environment.rb should look something like this:

# Environment variables for testing. This Should NOT be included in VCS
ENV["email"]      = "[email protected]"
ENV["password"]   = "really_secure_password"
ENV["api_key"]    = "super-secret-api-key-that-you-never-share"

Notes

Though this document rarely mentions authentication in most examples following the section above dedicated to it, an api_key or token, and an endpoint, may be supplied to any object or module that can perform an API request. This flexibility allows for interacting with a single instance of a single ApiResource class without having to use the SlidePay module methods directly, or having to use an instance of the SlidePay::Client class. It also accommodates those developers who may wish to authenticate many SlidePay accounts within a single thread, such as inside a request context of a Rails application, or in a scheduled task, without having to repeatedly set the SlidePay.token or SlidePay.api_key global values.

License

The MIT License (MIT)