Class: Plaid::User

Inherits:
Object
  • Object
show all
Defined in:
lib/plaid/user.rb

Overview

Public: A class which encapsulates the authenticated user for all Plaid products.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(product, access_token: nil, response: nil, mfa: nil, stripe_token: nil, client: nil) ⇒ User

Internal: Initialize a User instance.

product - The Symbol product name. access_token - The String access token obtained from Plaid. response - The Hash response body to parse. mfa - The Boolean flag indicating that response body

contains an MFA response.

stripe_token - The String stripe bank account token. client - The Plaid::Client instance used to connect to the API

(default is to use global Plaid client - Plaid.client).



156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/plaid/user.rb', line 156

def initialize(product, access_token: nil, response: nil, mfa: nil,
               stripe_token: nil, client: nil)
  @product = product
  @client = client
  @access_token = access_token if access_token
  @mfa_required = mfa
  @stripe_bank_account_token = stripe_token
  @accounts = @initial_transactions = @info = @risk = @income = nil

  parse_response(response) if response
end

Instance Attribute Details

#access_token ⇒ Object (readonly)

Public: The access token for authenticated user.



8
9
10
 
# File 'lib/plaid/user.rb', line 8

def access_token
  @access_token
end

#accounts ⇒ Object (readonly)

Public: The Array of Account instances providing accounts information for the user.



19
20
21
 
# File 'lib/plaid/user.rb', line 19

def accounts
  @accounts
end

#client ⇒ Object (readonly)

Internal: The Plaid::Client instance used to make queries.



50
51
52
 
# File 'lib/plaid/user.rb', line 50

def client
  @client
end

#initial_transactions ⇒ Object (readonly)

Public: The Array of Transactions provided by initial call to User.create.

If the :login_only option of User.create is set to false, the initial 30-day transactional data are returned during the API call. This attribute contains them.



26
27
28
 
# File 'lib/plaid/user.rb', line 26

def initial_transactions
  @initial_transactions
end

#mfa ⇒ Object (readonly)

Public: The MFA data (Hash or Array of Hash) or nil, if no MFA required.

E.g. [{ question: “What was the name of your first pet?” }] or [{ mask: ‘[email protected]’, type: ‘email’ },

{ mask: 'xxx-xxx-5309',   type: 'phone' }]

or { message: ‘Code sent to xxx-xxx-5309’ }



41
42
43
 
# File 'lib/plaid/user.rb', line 41

def mfa
  @mfa
end

#mfa_type ⇒ Object (readonly)

Public: The Symbol MFA type to be used (or nil, if no MFA required).

E.g. :questions, :list, or :device.



31
32
33
 
# File 'lib/plaid/user.rb', line 31

def mfa_type
  @mfa_type
end

#processor_token ⇒ Object (readonly)

Public: The processor token for a given account and authenticated user.



11
12
13
 
# File 'lib/plaid/user.rb', line 11

def processor_token
  @processor_token
end

#product ⇒ Object (readonly)

Public: The current product. Provides a context for #update and #delete calls. See Plaid::PRODUCTS.



15
16
17
 
# File 'lib/plaid/user.rb', line 15

def product
  @product
end

#stripe_bank_account_token ⇒ Object (readonly)

Public: The String stripe bank account token.

This field is set when you use User.exchange_token to convert Link public_token into an access token suitable for Plaid API.



47
48
49
 
# File 'lib/plaid/user.rb', line 47

def 
  @stripe_bank_account_token
end

Class Method Details

.create(product, institution, username, password, pin: nil, options: nil, client: nil) ⇒ Object

Public: Create (add) a user.

product - The Symbol product name you are adding the user to, one of

Plaid::PRODUCTS (e.g. :info, :connect, etc.).

institution - The String/Symbol financial institution type that you

want to access (e.g. :wells).

username - The String username associated with the financial

institution.

password - The String password associated with the financial

institution.

pin - The String PIN number associated with the financial

institution (default: nil).

options - the Hash options (default: {}):

:list       - The Boolean flag which would request the
              available send methods if the institution
              requires code-based MFA credential (default:
              false).
:webhook    - The String webhook URL. Used with :connect,
              :income, and :risk products (default: nil).
:pending    - The Boolean flag requesting to return
              pending transactions. Used with :connect
              product (default: false).
:login_only - The Boolean option valid for initial
              authentication only. If set to false, the
              initial request will return transaction data
              based on the start_date and end_date.
:start_date - The start Date from which to return
              transactions (default: 30 days ago).
:end_date   - The end Date to which transactions
              will be collected (default: today).

client - The Plaid::Client instance used to connect to the API

(default is to use global Plaid client - Plaid.client).

Returns a Plaid::User instance.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/plaid/user.rb', line 86

def self.create(product, institution, username, password,
                pin: nil, options: nil, client: nil)
  check_product product

  payload = { username: username, password: password,
              type: institution.to_s }
  payload[:pin] = pin if pin
  payload[:options] = MultiJson.dump(options) if options

  conn = Connector.new(product, auth: true, client: client)
  resp = conn.post(payload)

  new product, response: resp, mfa: conn.mfa?, client: client
end

.exchange_token(public_token, account_id = nil, product: :connect, client: nil) ⇒ Object

Public: Exchange a Link public_token for an API access_token.

The account_id parameter is required if you wish to receive a Stripe bank account token.

public_token - The String Link public_token. account_id - The String account ID. product - The Symbol product name (default: :connect). client - The Plaid::Client instance used to connect to the API

(default is to use global Plaid client - Plaid.client).

Returns a new User with access token obtained from Plaid and default product set to product. User#stripe_bank_account_token for this user instance will contain the Stripe token.



131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/plaid/user.rb', line 131

def self.exchange_token(public_token,  = nil,
                        product: :connect, client: nil)
  check_product product

  payload = { public_token: public_token }
  payload[:account_id] =  if 

  response = Connector.new(:exchange_token, auth: true, client: client)
                      .post(payload)

  stripe_token =  && response['stripe_bank_account_token']
  new product, response: response, client: client,
               stripe_token: stripe_token
end

.load(product, token, client: nil) ⇒ Object

Public: Get User instance in case user access token is known.

No requests are made, but the returned User instance is ready to be used.

product - The Symbol product name you want to use, one of

Plaid::PRODUCTS (e.g. :info, :connect, etc.).

token - The String access token for the user. client - The Plaid::Client instance used to connect to the API

(default is to use global Plaid client - Plaid.client).

Returns a Plaid::User instance.



113
114
115
 
# File 'lib/plaid/user.rb', line 113

def self.load(product, token, client: nil)
  new check_product(product), access_token: token, client: client
end

Instance Method Details

#auth(sync: false) ⇒ Object

Public: Get auth information for the user (routing numbers for accounts).

Not only this method returns the new data, but it updates self.accounts as well.

The method does a POST /auth/get request.

sync - The Boolean flag which, if true, causes auth information to be

rerequested from the server. Otherwise cached version is returned,
if it exists.

Returns an Array of Account with numbers baked in.



370
371
372
373
374
375
376
377
378
379
 
# File 'lib/plaid/user.rb', line 370

def auth(sync: false)
  if sync || !@accounts || !@accounts[0] || !@accounts[0].numbers
    response = Connector.new(:auth, :get, auth: true, client: client)
                        .post(access_token: access_token)

    update_accounts(response)
  end

  accounts
end

#balance ⇒ Object

Public: Get current account balance.

Does a POST /balance request.

Returns an Array of Plaid::Account.



440
441
442
443
444
445
 
# File 'lib/plaid/user.rb', line 440

def balance
  response = Connector.new(:balance, auth: true, client: client)
                      .post(access_token: access_token)

  update_accounts(response)
end

#delete ⇒ Object

Public: Delete the user.

Makes a delete request and freezes self to prevent further modifications to the object.

Returns self.



315
316
317
318
319
320
 
# File 'lib/plaid/user.rb', line 315

def delete
  Connector.new(product, auth: true, client: client)
           .delete(access_token: access_token)

  freeze
end

#for_product(product) ⇒ Object

Public: Get the current user tied to another product.

No API request is made, just the current product is changed.

product - The Symbol product you are selecting, one of Plaid::PRODUCTS.

See also User#upgrade.

Returns a new User instance.



354
355
356
 
# File 'lib/plaid/user.rb', line 354

def for_product(product)
  User.load product, access_token, client: client
end

#income(sync: false) ⇒ Object

Public: Get income information for the user.

Does a POST /income/get request.

sync - The Boolean flag which, if true, causes income information to be

rerequested from the server. Otherwise cached version is returned,
if it exists.

Returns a Plaid::Income instance.



408
409
410
411
412
413
414
415
 
# File 'lib/plaid/user.rb', line 408

def income(sync: false)
  if sync || !@income
    parse_response(Connector.new(:income, :get, auth: true, client: client)
                            .post(access_token: access_token))
  end

  @income
end

#info(sync: false) ⇒ Object

Public: Get info for the user.

Does a POST /info/get request.

sync - The Boolean flag which, if true, causes information to be

rerequested from the server. Otherwise cached version is returned,
if it exists.

Returns a Plaid::Info instance.



390
391
392
393
394
395
396
397
 
# File 'lib/plaid/user.rb', line 390

def info(sync: false)
  if sync || !@info
    parse_response(Connector.new(:info, :get, auth: true, client: client)
                            .post(access_token: access_token))
  end

  @info
end

#mfa? ⇒ Boolean

Public: Find out if MFA is required based on last request.

After calling e.g. User.create you might need to make an additional authorization step if MFA is required by the financial institution.

Returns true if this step is needed, a falsey value otherwise.

Returns:

  • (Boolean) 


174
175
176
 
# File 'lib/plaid/user.rb', line 174

def mfa?
  @mfa_required
end

#mfa_step(info = nil, send_method: nil, options: nil) ⇒ Object

Public: Submit MFA information.

info - The String with MFA information (default: nil). send_method - The Hash with code send method information.

E.g. { type: 'phone' } or { mask: '123-...-4321' }.
Default is first available email.

options - the Hash options (default: {}):

:list       - The Boolean flag which would request the
              available send methods if the institution
              requires code-based MFA credential (default:
              false).
:webhook    - The String webhook URL. Used with :connect,
              :income, and :risk products (default: nil).
:pending    - The Boolean flag requesting to return
              pending transactions. Used with :connect
              product (default: false).
:login_only - The Boolean option valid for initial
              authentication only. If set to false, the
              initial request will return transaction data
              based on the start_date and end_date.
:start_date - The start Date from which to return
              transactions (default: 30 days ago).
:end_date   - The end Date to which transactions
              will be collected (default: today).

Returns true if whole MFA process is completed, false otherwise.



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/plaid/user.rb', line 204

def mfa_step(info = nil, send_method: nil, options: nil)
  payload = { access_token: access_token }
  payload[:mfa] = info if info
  if options || send_method
    options = {} unless options
    options[:send_method] = send_method if send_method
    payload[:options] = MultiJson.dump(options)
  end
  conn = Connector.new(product, :step, auth: true)

  # Use PATCH if we are in context of User#update.
  response = if @mfa_patch
               conn.patch(payload)
             else
               conn.post(payload)
             end

  @mfa_required = conn.mfa?
  parse_response(response)
end

#risk(sync: false) ⇒ Object

Public: Get risk data for the user’s accounts.

Does a POST /risk/get request.

sync - The Boolean flag which, if true, causes risk information to be

rerequested from the server. Otherwise cached version is returned,
if it exists.

Returns an Array of accounts with risk attribute set.



426
427
428
429
430
431
432
433
 
# File 'lib/plaid/user.rb', line 426

def risk(sync: false)
  if sync || !@accounts || !@accounts[0] || !@accounts[0].risk
    parse_response(Connector.new(:risk, :get, auth: true, client: client)
                            .post(access_token: access_token))
  end

  @accounts
end

#transactions(pending: false, account_id: nil, start_date: nil, end_date: nil) ⇒ Object

Public: Get transactions.

Does a /connect/get call. Updates self.accounts with latest information.

pending - the Boolean flag requesting to return pending transactions. account_id - the String Account ID (default: nil). If this argument is

present, only transactions for given account will be
requested.

start_date - The start Date (inclusive). end_date - The end Date (inclusive).

Returns an Array of Transaction records.



237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/plaid/user.rb', line 237

def transactions(pending: false, account_id: nil,
                 start_date: nil, end_date: nil)
  options = { pending: pending }
  options[:account] =  if 
  options[:gte] = start_date.to_s if start_date
  options[:lte] = end_date.to_s if end_date

  response = Connector.new(:connect, :get, auth: true, client: client)
                      .post(access_token: access_token,
                            options: MultiJson.dump(options))
  update_accounts(response)
  build_objects(response['transactions'], Transaction)
end

#update(username, password, pin = nil) ⇒ Object

Public: Update user credentials.

Updates the user credentials for the current product. See User#for_product.

username - The String username associated with the financial

institution.

password - The String password associated with the financial

institution.

pin - The String PIN number associated with the financial

institution (default: nil).

Returns self.



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/plaid/user.rb', line 264

def update(username, password, pin = nil)
  payload = {
    access_token: access_token,
    username: username,
    password: password
  }

  payload[:pin] = pin if pin

  conn = Connector.new(product, auth: true, client: client)
  resp = conn.patch(payload)

  if conn.mfa?
    @mfa_required = true
  end

  parse_response(resp)

  # A note for User#mfa_step to send PATCH request too
  @mfa_patch = true

  self
end

#update_webhook(webhook) ⇒ Object

Public: Create or update the webhook for Connect.

Does a PATCH /connect request.

webhook - The String with webhook URL.

Returns self.

Raises:

  • (ArgumentError) 


295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/plaid/user.rb', line 295

def update_webhook(webhook)
  raise ArgumentError, 'User#update_webhook only supported by Connect!' \
    unless product == :connect

  payload = {
    access_token: access_token,
    options: MultiJson.dump(webhook: webhook)
  }

  parse_response(Connector.new(:connect, auth: true, client: client)
                          .patch(payload))
  self
end

#upgrade(product) ⇒ Object

Public: Upgrade the user.

For an existing user that has been added via any of products (:connect, :auth, :income, :info, or :risk), you can upgrade that user to have functionality with other products.

Does a POST /upgrade request.

See also User#for_product.

product - The Symbol product name you are upgrading the user to, one of

Plaid::PRODUCTS.

Returns another User record with the same access token, but tied to the new product.



337
338
339
340
341
342
343
 
# File 'lib/plaid/user.rb', line 337

def upgrade(product)
  payload = { access_token: access_token, upgrade_to: product.to_s }
  response = Connector.new(:upgrade, auth: true, client: client)
                      .post(payload)

  User.new product, response: response, client: client
end