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','user@name.com','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

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','user@name.com','pass_word_WRONG', 'amex'
r = client.connect

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 "me@example.com", "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

Copyright © 2014 John Koisch. See LICENSE.txt for further details.