The official Ruby bindings for the Plaid API. It's generated from our OpenAPI schema.
- Installation
- Versioning
- Getting Started
- Examples
- Errors
- Response objects
- Migration Guide
- Contributing
- License
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 3.0.0+ only.
Versions > 14 are generated from our OpenAPI schema.
Each major version of plaid-ruby targets a specific version of the Plaid API:
| API version | plaid-ruby release |
|---|---|
2020-09-14 (latest) |
12.x.x and higher |
2019-05-29 |
11.x.x, 10.x.x, 9.x.x, 8.x.x, 7.x.x |
2018-05-22 |
6.x.x |
2017-03-08 |
5.x.x |
For information about what has changed between versions and how to update your integration, head to the version changelog.
The plaid-ruby client library is typically updated on a monthly basis. The canonical source for the latest version number is the client library changelog. New versions are published as GitHub tags, not as Releases. New versions are also published on RubyGems.org.
All users are strongly recommended to use a recent version of the library, as older versions do not contain support for new endpoints and fields. For more details, see the Migration Guide.
Create an instance of the client using the client_id and secret from your Plaid dashboard along with your environment of choice:
require 'plaid'
configuration = Plaid::Configuration.new
configuration.server_index = Plaid::Configuration::Environment["sandbox"]
configuration.api_key["PLAID-CLIENT-ID"] = "***"
configuration.api_key["PLAID-SECRET"] = "***"
api_client = Plaid::ApiClient.new(
configuration
)
client = Plaid::PlaidApi.new(api_client)The server_index field is the environment which the client will be running in. Your choices for the server_index field include:
Plaid::Configuration::Environment["sandbox"]allows you to do your initial integrations tests against preloaded data without being billed or making expensive API calls. More information about using the API sandbox can be found on the API Sandbox documentation.Plaid::Configuration::Environment["development"]allows you to test against both real and test accounts without being billed. More information about Plaid test accounts can be found in our API documentation.Plaid::Configuration::Environment["production"]is the production environment where you can launch your production ready application and be charged for your Plaid usage.
The gem uses Faraday to wrap HTTPS connections, which allows you to tune certain params:
configuration = Plaid::Configuration.new
api_client = Plaid::ApiClient.new(
configuration
)
api_client.connection.options[:timeout] = 60*20 # 20 minutesTo use custom middleware, reinitialize the Faraday::Connection object:
configuration = Plaid::Configuration.new
api_client = Plaid::ApiClient.new(configuration)
api_client.create_connection do |builder|
builder.use Faraday::Response::Logger
end
Dates and datetimes in requests, which are represented as strings in the API and previous versions of the client library, are represented in this version of the Ruby client library as Ruby Date or DateTime objects.
Time zone information is required for request fields that accept datetimes. Failing to include time zone information (or passing in a string, instead of a Date or DateTime object) will result in an error. See the following examples for guidance on Date and DateTime usage.
If the API reference documentation for a field specifies format: date, any of following are acceptable:
require 'date'
# Not an exhaustive list of possible options
a = Date.new(2022, 5, 5)
b = Date.new(2022, 5, 5).to_date
c = Date.parse('2022-05-05')
d = Date.parse('2022-05-05').to_date
e = Date.todayIf the API reference documentation for a field specifies format: date-time, either of the following are acceptable:
require 'time'
# Not an exhaustive list of possible options
a = Time.parse("2022-05-06T22:35:49Z").to_datetime
b = Date.parse("2022-05-06T22:35:49Z").to_datetimeFor more examples, see the test suites, Quickstart, or API Reference documentation.
# Grab the client_user_id by searching for the current user in your database
user = User.find_by!(email: '***')
client_user_id = user.id
# Create the link_token with all of your configurations
link_token_create_request = Plaid::LinkTokenCreateRequest.new({
:user => { :client_user_id => client_user_id.to_s },
:client_name => 'My app',
:products => %w[auth transactions],
:country_codes => ['US'],
:language => 'en'
})
link_token_response = client.link_token_create(
link_token_create_request
)
# Pass the result to your client-side app to initialize Link
# and retrieve a public_token
link_token = link_token_response.link_tokenIf you have a Link public token, use this function to get an access_token: client.item_public_token_exchange(request)
An example of the function's usage if you have a public_token in hand:
request = Plaid::ItemPublicTokenExchangeRequest.new
request.public_token = public_token
response = client.item_public_token_exchange(request)
access_token = response.access_tokenrequest = Plaid::ItemPublicTokenExchangeRequest.new
request.public_token = public_token
response = client.item_public_token_exchange(request)
access_token = response.access_token
# Provide the access_token for the Item you want to remove
item_remove_request = Plaid::ItemRemoveRequest.new
item_remove_request.access_token = access_token
client.item_remove(item_remove_request)request = Plaid::ItemPublicTokenExchangeRequest.new
request.public_token = public_token
response = client.item_public_token_exchange(request)
access_token = response.access_token
transactions_sync_request = Plaid::TransactionsSyncRequest.new
transactions_sync_request.access_token = access_token
transaction_response = client.transactions_sync(transactions_sync_request)
transactions = transaction_response.added
# the transactions in the response are paginated, so make multiple calls while
# updating the cursor to retrieve all transactions
while transaction_response.has_more
transactions_sync_request = Plaid::TransactionsSyncRequest.new
transactions_sync_request.access_token = access_token
transactions_sync_request.cursor = transaction_response.next_cursor
transaction_response = client.transactions_sync(transactions_sync_request)
transactions += transaction_response.added
endrequest = Plaid::ItemPublicTokenExchangeRequest.new
request.public_token = public_token
response = client.item_public_token_exchange(request)
access_token = response.access_token
transactions_get_request = Plaid::TransactionsGetRequest.new
transactions_get_request.access_token = access_token
transactions_get_request.start_date = "2020-01-01"
transactions_get_request.end_date = "2021-01-01"
transaction_response = client.transactions_get(transactions_get_request)
transactions = transaction_response.transactions
# the transactions in the response are paginated, so make multiple calls while
# increasing the offset to retrieve all transactions
while transactions.length < transaction_response.total_transactions
options_payload = {}
options_payload[:offset] = transactions.length
transactions_get_request = Plaid::TransactionsGetRequest.new
transactions_get_request.access_token = access_token
transactions_get_request.start_date = "2020-01-01"
transactions_get_request.end_date = "2021-01-01"
transactions_get_request.options = options_payload
transaction_response = client.transactions_get(transactions_get_request)
transactions += transaction_response.transactions
endrequest = Plaid::ItemPublicTokenExchangeRequest.new
request.public_token = public_token
response = client.item_public_token_exchange(request)
access_token = response.access_token
auth_get_request = Plaid::AuthGetRequest.new
auth_get_request.access_token = access_token
auth_response = client.auth_get(auth_get_request)
auth = auth_response.authFinancial institution information is available as shown below where the function arguments represent count and offset:
institutions_get_request = Plaid::InstitutionsGetRequest.new({
:count => 3,
:offset => 1,
:country_codes => ["US"],
})
response = client.institutions_get(institutions_get_request)Any methods making API calls will result in an exception raised unless the response code is "200: Success" or "210: MFA Required".
Plaid::ApiError is returned in response to API internal server errors.
Read more about response codes and their meaning in the Plaid documentation.
All API calls return a response object that is accessible only with dot notation
(i.e., response.foo.bar) and not with bracket notation. Expected keys for all types of responses are defined,
and any attempt to access an unknown key will cause NoMethodError exception.
Migrating from a version released on or after August 2021 to a recent version should involve very minor integration changes. Many customers will not need to make changes to their integrations at all. To see a list of all potentially-breaking changes since your current version, see the client library changelog and search for "Breaking changes in this version". Breaking changes are annotated at the top of each major version header.
Version 14.0.0 of the client library was released in August 2021 and contains multiple interface changes, as described below.
From:
client = Plaid::Client.new(env: :sandbox,
client_id: client_id,
secret: secret)To:
configuration = Plaid::Configuration.new
configuration.server_index = Plaid::Configuration::Environment["sandbox"]
configuration.api_key["PLAID-CLIENT-ID"] = ENV["PLAID_RUBY_CLIENT_ID"]
configuration.api_key["PLAID-SECRET"] = ENV["PLAID_RUBY_SECRET"]
configuration.api_key["Plaid-Version"] = "2020-09-14"
api_client = Plaid::ApiClient.new(
configuration
)
client = Plaid::PlaidApi.new(api_client)All endpoint requests now take a request model and the functions have been renamed to include _.
From:
response = client.auth.get(access_token)To:
auth_get_request = Plaid::AuthGetRequest.new
auth_get_request.access_token = access_token
or
auth_get_request = Plaid::AuthGetRequest.new({:access_token => access_token})
response = client.auth_get(auth_get_request)From:
begin
client.auth.get(auth_get_request)
rescue Plaid::PlaidAPIError => e
raise e if e.error_code != 'PRODUCT_NOT_READY'
sleep 1
endTo:
begin
client.auth_get(auth_get_request)
rescue Plaid::ApiError => e
json_response = JSON.parse(e.response_body)
if json_response["error_code"] != "PRODUCT_NOT_READY"
endSee Dates for information on updates to date formats.
Bug reports are welcome on GitHub. See also contributing guidelines.
The gem is available as open source under the terms of the MIT License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent