plaid_kilt

Accessing the Plaid API using Ruby.

Notes

Minimal undergarments. Sporran not included. Tests coming.

Version

Head is 0.6.0

Install

'gem install plaid-kilt'

Usage

Grab a client

Clients take 4 parameters: username, email, password, and the institution.

client = Plaid.client 'user_name','[email protected]','pass_word', 'amex'

Connect

Plaid uses the “connect” Plaid API call to initiate the user flow and to access information.

info = client.connect               <= gets information from Plaid

Responses

This gem returns values in response objects or error objects. This is not very ruby-esque, but it helps to make sense of the Plaid environment as well as making HTTPParty consumable for a business.

Response objects are initialized when the client gets a valid response from plaid. In the case of non-MFA banks

r = client.connect

r.raw_response <= the raw HTTPParty-wrapped response from Plaid
r.accounts <= Array of accounts associated with this institution for this user
r.transactions <= Array of transactions associated with the accounts
r.is_mfa? <= false for this request
r.message <= “Successful retrieved information from bank”
r.http_code <= 200 in this case

Accounts and Transactions are objects that follow the JSON from Plaid. Thus you can expect to see

r.transactions[66].category_id              <= "52544965f71e87d007000119"
r.transactions[66].name                     <= "Online Payment Processed"
r.accounts[2].institution_type              <= "fake_institution"
r.accounts[2].balance["current"]            <= 8.98

More explicitly

r.accounts[2].inspect

"#<PlaidObject:0x007f92853ca770 @type=\"credit\", @_id=\"52db1be4be13cbc36e000006\", @_item=\"52af631671c3bd1b25000064\", @_user=\"52af630f71c3bd1b25000063\", @balance={\"available\"=>3721, \"current\"=>8.98}, @meta={\"limit\"=>3500, \"name\"=>\"Plaid Credit Card\", \"number\"=>\"93004\"}, @institution_type=\"fake_institution\">"

Errors

Errors use the gem’s PlaidError object

client = Plaid.client 'user_name','[email protected]','pass_word_WRONG', 'amex'
r = client.connect

r.http_code <= 402
r.plaid_code <= Plaid’s internal error code (plaid.com/expand#Response_Code_Detail)
r.error_message <= “Error”
r.resolution <= “The username or password provided were not correct.”
r.raw_response <= the raw HTTPParty response

More explicitly

r = client.connect

"#<PlaidError:0x007f928513d638 @code=\"1200\", @message=\"Error\", @resolve=\"The username or password provided were not correct.\", @response=#<HTTParty::Response:0x7f928513d318 parsed_response={\"code\"=>1200, \"message\"=>\"invalid credentials\", \"resolve\"=>\"The username or password provided were not correct.\"}, @response=#<Net::HTTPPaymentRequired 402 Payment Required readbody=true>, @headers={\"content-type\"=>[\"application/json; charset=utf-8\"], \"date\"=>[\"Sat, 15 Mar 2014 17:31:46 GMT\"], \"x-powered-by\"=>[\"Express\"], \"content-length\"=>[\"109\"], \"connection\"=>[\"Close\"]}>>"

MFA

MFA requires some management of user flow, which is why this gem tries to make the returns / errors from API calls explicit. If it seems heavyweight to you, it is because the MFA process is a heavyweight process. Plaid does a better job managing it than some others (no names!!), but if you are going to use Plaid extensively, then you are going to have to cope with MFA. See the wiki for more information.

github.com/jkoisch/plaid/wiki/MFA

These two diagrams go through user set up and user flow with MFA, respectively.

Raw response

You can, if you would rather, ignore the PlaidResponse objects.

#config/initializers/plaid.rb
config.save_full_response = true

#when you get your responses
x = client.connect
x.raw_response                 <= the raw http-party wrapped response to the request. Have fun.

Thin Client

The Plaid-kilt gem also has a thin_client for some secure followup operations:

thin_client = Plaid.thin_client "[email protected]", "chase", "access_token_test"

This client can be used only after you have retrieved an access_token, but supports followup methods allowed for by Plaid:

thin_client.followup                                <= GET operation to get account and transaction information
thin_client.get_balance                             <= GET operation to receive account balances
thin_client.get_entity("unique_plaid_entity")       <= Entity context information

Scaffolding

Some Plaid methods are accessible via a GET with no additional credentials:

Plaid.scaffold.institutions    <= all of the institutions that Plaid supports
Plaid.scaffold.category(id)    <= detailed information about the plaid category

Configuration

You need to configure access through your own initializers using the values you receive from Plaid.

#config/initializers/plaid.rb
require 'plaid'
Plaid.configure do |config|
  config.client_id            = 'JUNK'
  config.secret               = 'JUNK'
  config.endpoint             = 'https://tartan.plaid.com/'
  config.certpath             = 'ca-bundle.crt'
  config.headers              = {'Content-Type'=>'application/x-www-form-urlencoded'}
  config.webhook_address      = 'https://You.will.need.a/plaid_webhook/'
  config.save_full_response   = false
end

Additional Client Methods

The Plaid Client is not-quite-skinny so that it can handle various parts of the returns from the Plaid API. This is to support alternate user flows (MFA, etc) or user handling in implementation.

The Plaid Client supports the following attr_readers

client.settings
client.username
client.password
client.institution
client.endpoint
client.secret
client.access_token
client.mfa_type
client.mfa_message
client.mfa_return               <= an array of the MFA returns from Plaid

Contributing to the plaid gem

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.