Ruby bindings for the Plaid API.
Add this line to your application's Gemfile:
gem 'plaid'And then execute:
$ bundle
Or install it yourself as:
$ gem install plaid
The gem supports Ruby 2.x only.
This gem wraps the Plaid API, which is fully described in the documentation.
The RubyDoc for the gem is available here.
Configure the gem with your client id, secret, and the environment you would like to use.
Plaid.config do |p|
p.client_id = '<<< Plaid provided client ID >>>'
p.secret = '<<< Plaid provided secret key >>>'
p.env = :tartan # or :production
enduser = Plaid::User.create(:connect, 'wells', 'plaid_test', 'plaid_good')This call will do a POST /connect. The response will contain account information and transactions
for last 30 days, which you can find in user.accounts and user.initial_transactions, accordingly.
If the authentication requires a pin, you can pass it as a named parameter:
user = Plaid::User.create(:income, 'usaa', 'plaid_test', 'plaid_good', pin: '1234')To add options such as login_only or webhook, use options argument:
user = Plaid::User.create(:connect, 'wells', 'plaid_test', 'plaid_good',
options: { login_only: true, webhook: 'https://example.org/callbacks/plaid')The first argument for Plaid::User.create is always a product you want to add the user to (like,
:connect, :auth, :info, :income, or :risk). The user object is bound to the product, and subsequent
calls like user.update or user.delete are done for this product (i.e., PATCH /info and DELETE /info
for :info).
If you've already added the user and saved the access token, you should use User.load:
user = Plaid::User.load(:risk, 'access_token')This won't make any API requests by itself, just set the product and the token in the User instance.
If you have a Link public token, use User.exchange_token:
user = Plaid::User.exchange_token('public_token') # bound to :connect productWith more options:
user2 = Plaid::User.exchange_token('public_token', 'account_id', product: :auth)If you want to move money via Stripe's ACH
API, you
ought to specify the account_id param. In this case the returned user
instance will have the stripe_bank_account_token attribute set.
Plaid supports upgrading a user, i.e. adding it to another product:
# Create a user in Connect
user = Plaid::User.create(:connect, 'wells', 'plaid_test', 'plaid_good')
# Upgrade this user, attaching it to Auth as well (makes a request to /upgrade).
auth_user = user.upgrade(:auth)The auth_user will be a different instance of User, attached to Auth, but the access token will be the same.
Sometimes you know that the user has already been added to another product. To get a User instance with
same access token, but different current product, use User.for_product:
# Get a user attached to Connect
user = Plaid::User.load(:connect, 'access_token')
# Makes no requests
info_user = user.for_product(:info)Basically it's the same as:
info_user = Plaid::User.load(:info, 'access_token')If MFA is requested by the financial institution, the User.create call would behave
a bit differently:
user = Plaid::User.create(:auth, 'wells', 'plaid_test', 'plaid_good')
user.accounts #=> nil
user.mfa? #=> true
user.mfa_type #=> :questions
user.mfa #=> [{question: "What's the nickname of the person who created Ruby?"}]In this case you'll have to submit the answer to the question:
user.mfa_step('matz') # This is the correct answer!
user.mfa? #=> false
user.mfa_type #=> nil
user.mfa #=> nil
user.accounts #=> [<Plaid::Account ...>, ...]The code-based MFA workflow is similar. Basically you need to call user.mfa_step(...)
until user.mfa? becomes false.
If you have a live User instance, you can use following methods
(independent of instance's current product):
user.transactions(...). Makes a/connect/getrequest.user.auth(sync: false). Makes an/auth/getrequest.user.info(sync: false). Makes an/info/getrequest.user.income(sync: false). Makes an/income/getrequest.user.risk(sync: false). Makes an/risk/getrequest.user.balance. Makes an/balancerequest.
All of these methods return appropriate data, but they also update the cached user.accounts. That is,
if you user has access to Auth and Risk products, the following code:
user = User.load(:auth, 'access_token')
user.auth
user.riskwill result in user.accounts having both routing number and risk information for all the accounts. The
subsequent user.balance call will just update the current balance, not touching the routing and risk information.
The sync flag, if set to true, will result in updating the information from the server even if it has already been
loaded. Otherwise cached information will be returned:
user = User.load(:auth, 'access_token') # Just set the token
user.auth # POST /auth/get
user.auth # No POST, return cached info
user.auth(sync: true) # POST /auth/get againSame goes for other methods, except User#transactions and User#balance which always make requests to the API.
You can request category information:
cats = Plaid::Category.all # Array of all known categories
cat = Plaid::Category.get('17001013') # A single category by its IDFinancial institution information is available via Plaid::Institution and Plaid::LongTailInstitution:
insts = Plaid::Institution.all # Array of all major financial institutions
inst = Plaid::Institution.get('5301a93ac140de84910000e0') # A single institution by its ID
lti = Plaid::LongTailInstitution.get('bofa') # A single one
ltis = Plaid::LongTailInstitution.all(count: 20, offset: 20) # A page
res = Plaid::LongTailInstitution.search(query: 'c') # Lookup by nameIt's possible to use several Plaid environments and/or credentials in one app by
explicit instantiation of Plaid::Client:
# Configuring the global client (Plaid.client) which is used by default
Plaid.config do |p|
p.client_id = 'client_id_1'
p.secret = 'secret_1'
p.env = :tartan
end
# Creating a custom client
api = Plaid::Client.new(client_id: 'client_id_2', secret: 'secret_2', env: :production)
# Tartan user (using default client)
user1 = Plaid::User.create(:connect, 'wells', 'plaid_test', 'plaid_good')
# Api user (using api client)
user2 = Plaid::User.create(:connect, 'wells', 'plaid_test', 'plaid_good', client: api)
# Lookup a long tail institution in production
res = Plaid::LongTailInstitution.search(query: 'c', client: api)The client option can be passed to the following methods:
User.createUser.loadUser.exchange_tokenCategory.allCategory.getInstitution.allInstitution.getLongTailInstitution.allLongTailInstitution.searchLongTailInstitution.get
Any methods making API calls will result in an exception raised unless the response code is "200: Success" or "201: MFA Required".
Plaid::BadRequestError is raised when status code is "400: Bad Request".
Plaid::UnauthorizedError is raised when status code is "401: Unauthorized".
Plaid::RequestFailedError is raised when status code is "402: Request Failed".
Plaid::NotFoundError is raised when status code is "404: Cannot be Found".
Plaid::ServerError is raised when status code is "50X: Server Error".
Read more about response codes and their meaning in the Plaid documentation.
After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/plaid/plaid-ruby. See also contributing guidelines.
The gem is available as open source under the terms of the MIT License.