Class: Lithic::Resources::AccountHolders

Inherits:
Object
  • Object
show all
Defined in:
lib/lithic/resources/account_holders.rb,
lib/lithic/resources/account_holders/entities.rb

Defined Under Namespace

Classes: Entities

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ AccountHolders

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of AccountHolders.

Parameters:



321
322
323
324
 
# File 'lib/lithic/resources/account_holders.rb', line 321

def initialize(client:)
  @client = client
  @entities = Lithic::Resources::AccountHolders::Entities.new(client: client)
end

Instance Attribute Details

#entities ⇒ Lithic::Resources::AccountHolders::Entities (readonly)

Returns:



7
8
9
 
# File 'lib/lithic/resources/account_holders.rb', line 7

def entities
  @entities
end

Instance Method Details

#create(body:, request_options: {}) ⇒ Lithic::Models::AccountHolderCreateResponse

Create an account holder and initiate the appropriate onboarding workflow. Account holders and accounts have a 1:1 relationship. When an account holder is successfully created an associated account is also created. All calls to this endpoint will return a synchronous response. The response time will depend on the workflow. In some cases, the response may indicate the workflow is under review or further action will be needed to complete the account creation process. This endpoint can only be used on accounts that are part of the program that the calling API key manages.

Parameters:

Returns:

See Also:



26
27
28
29
30
31
32
33
34
35
 
# File 'lib/lithic/resources/account_holders.rb', line 26

def create(params)
  parsed, options = Lithic::AccountHolderCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/account_holders",
    body: parsed[:body],
    model: Lithic::Models::AccountHolderCreateResponse,
    options: {timeout: 300, **options}
  )
end

#list(begin_: nil, email: nil, end_: nil, ending_before: nil, external_id: nil, first_name: nil, last_name: nil, legal_business_name: nil, limit: nil, phone_number: nil, starting_after: nil, request_options: {}) ⇒ Lithic::Internal::SinglePage<Lithic::Models::AccountHolder>

Some parameter documentations has been truncated, see Models::AccountHolderListParams for more details.

Get a list of individual or business account holders and their KYC or KYB evaluation status.

Parameters:

  • begin_ (Time) —

    Date string in RFC 3339 format. Only entries created after the specified time wi

  • email (String) —

    Email address of the account holder. The query must be an exact match, case inse

  • end_ (Time) —

    Date string in RFC 3339 format. Only entries created before the specified time w

  • ending_before (String) —

    A cursor representing an item’s token before which a page of results should end.

  • external_id (String) —

    If applicable, represents the external_id associated with the account_holder.

  • first_name (String) —

    (Individual Account Holders only) The first name of the account holder. The quer

  • last_name (String) —

    (Individual Account Holders only) The last name of the account holder. The query

  • legal_business_name (String) —

    (Business Account Holders only) The legal business name of the account holder. T

  • limit (Integer) —

    The number of account_holders to limit the response to.

  • phone_number (String) —

    Phone number of the account holder. The query must be an exact match.

  • starting_after (String) —

    A cursor representing an item’s token after which a page of results should begin

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/lithic/resources/account_holders.rb', line 126

def list(params = {})
  parsed, options = Lithic::AccountHolderListParams.dump_request(params)
  query = Lithic::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "v1/account_holders",
    query: query.transform_keys(begin_: "begin", end_: "end"),
    page: Lithic::Internal::SinglePage,
    model: Lithic::AccountHolder,
    options: options
  )
end

#list_documents(account_holder_token, request_options: {}) ⇒ Lithic::Models::AccountHolderListDocumentsResponse

Retrieve the status of account holder document uploads, or retrieve the upload URLs to process your image uploads.

Note that this is not equivalent to checking the status of the KYC evaluation overall (a document may be successfully uploaded but not be sufficient for KYC to pass).

In the event your upload URLs have expired, calling this endpoint will refresh them. Similarly, in the event a previous account holder document upload has failed, you can use this endpoint to get a new upload URL for the failed image upload.

When a new document upload is generated for a failed attempt, the response will show an additional entry in the ‘required_document_uploads` list in a `PENDING` state for the corresponding `image_type`.

Parameters:

  • account_holder_token (String) —

    Globally unique identifier for the account holder.

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



164
165
166
167
168
169
170
171
 
# File 'lib/lithic/resources/account_holders.rb', line 164

def list_documents(, params = {})
  @client.request(
    method: :get,
    path: ["v1/account_holders/%1$s/documents", ],
    model: Lithic::Models::AccountHolderListDocumentsResponse,
    options: params[:request_options]
  )
end

#retrieve(account_holder_token, request_options: {}) ⇒ Lithic::Models::AccountHolder

Get an Individual or Business Account Holder and/or their KYC or KYB evaluation status.

Parameters:

  • account_holder_token (String) —

    Globally unique identifier for the account holder.

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



49
50
51
52
53
54
55
56
 
# File 'lib/lithic/resources/account_holders.rb', line 49

def retrieve(, params = {})
  @client.request(
    method: :get,
    path: ["v1/account_holders/%1$s", ],
    model: Lithic::AccountHolder,
    options: params[:request_options]
  )
end

#retrieve_document(document_token, account_holder_token:, request_options: {}) ⇒ Lithic::Models::Document

Check the status of an account holder document upload, or retrieve the upload URLs to process your image uploads.

Note that this is not equivalent to checking the status of the KYC evaluation overall (a document may be successfully uploaded but not be sufficient for KYC to pass).

In the event your upload URLs have expired, calling this endpoint will refresh them. Similarly, in the event a document upload has failed, you can use this endpoint to get a new upload URL for the failed image upload.

When a new account holder document upload is generated for a failed attempt, the response will show an additional entry in the ‘required_document_uploads` array in a `PENDING` state for the corresponding `image_type`.

Parameters:

  • document_token (String) —

    Globally unique identifier for the document.

  • account_holder_token (String) —

    Globally unique identifier for the account holder.

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/lithic/resources/account_holders.rb', line 199

def retrieve_document(document_token, params)
  parsed, options = Lithic::AccountHolderRetrieveDocumentParams.dump_request(params)
   =
    parsed.delete(:account_holder_token) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["v1/account_holders/%1$s/documents/%2$s", , document_token],
    model: Lithic::Document,
    options: options
  )
end

#simulate_enrollment_document_review(document_upload_token:, status:, accepted_entity_status_reasons: nil, status_reason: nil, request_options: {}) ⇒ Lithic::Models::Document

Some parameter documentations has been truncated, see Models::AccountHolderSimulateEnrollmentDocumentReviewParams for more details.

Simulates a review for an account holder document upload.

Parameters:

Returns:

See Also:



234
235
236
237
238
239
240
241
242
243
 
# File 'lib/lithic/resources/account_holders.rb', line 234

def simulate_enrollment_document_review(params)
  parsed, options = Lithic::AccountHolderSimulateEnrollmentDocumentReviewParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/simulate/account_holders/enrollment_document_review",
    body: parsed,
    model: Lithic::Document,
    options: options
  )
end

#simulate_enrollment_review(account_holder_token: nil, status: nil, status_reasons: nil, request_options: {}) ⇒ Lithic::Models::AccountHolderSimulateEnrollmentReviewResponse

Some parameter documentations has been truncated, see Models::AccountHolderSimulateEnrollmentReviewParams for more details.

Simulates an enrollment review for an account holder. This endpoint is only applicable for workflows that may required intervention such as ‘KYB_BASIC`.

Parameters:

Returns:

See Also:



264
265
266
267
268
269
270
271
272
273
 
# File 'lib/lithic/resources/account_holders.rb', line 264

def simulate_enrollment_review(params = {})
  parsed, options = Lithic::AccountHolderSimulateEnrollmentReviewParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/simulate/account_holders/enrollment_review",
    body: parsed,
    model: Lithic::Models::AccountHolderSimulateEnrollmentReviewResponse,
    options: options
  )
end

#update(account_holder_token, body:, request_options: {}) ⇒ Lithic::Models::AccountHolderUpdateResponse::KYBKYCPatchResponse, Lithic::Models::AccountHolderUpdateResponse::PatchResponse

Update the information associated with a particular account holder (including business owners and control persons associated to a business account). If Lithic is performing KYB or KYC and additional verification is required we will run the individual’s or business’s updated information again and return whether the status is accepted or pending (i.e., further action required). All calls to this endpoint will return a synchronous response. The response time will depend on the workflow. In some cases, the response may indicate the workflow is under review or further action will be needed to complete the account creation process. This endpoint can only be used on existing accounts that are part of the program that the calling API key manages.

Parameters:

Returns:

See Also:



80
81
82
83
84
85
86
87
88
89
 
# File 'lib/lithic/resources/account_holders.rb', line 80

def update(, params)
  parsed, options = Lithic::AccountHolderUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["v1/account_holders/%1$s", ],
    body: parsed[:body],
    model: Lithic::Models::AccountHolderUpdateResponse,
    options: options
  )
end

#upload_document(account_holder_token, document_type:, entity_token:, request_options: {}) ⇒ Lithic::Models::Document

Use this endpoint to identify which type of supported government-issued documentation you will upload for further verification. It will return two URLs to upload your document images to - one for the front image and one for the back image.

This endpoint is only valid for evaluations in a ‘PENDING_DOCUMENT` state.

Supported file types include ‘jpg`, `png`, and `pdf`. Each file must be less than 15 MiB. Once both required uploads have been successfully completed, your document will be run through KYC verification.

If you have registered a webhook, you will receive evaluation updates for any document submission evaluations, as well as for any failed document uploads.

Two document submission attempts are permitted via this endpoint before a ‘REJECTED` status is returned and the account creation process is ended. Currently only one type of account holder document is supported per KYC verification.

Parameters:

Returns:

See Also:



307
308
309
310
311
312
313
314
315
316
 
# File 'lib/lithic/resources/account_holders.rb', line 307

def upload_document(, params)
  parsed, options = Lithic::AccountHolderUploadDocumentParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/account_holders/%1$s/documents", ],
    body: parsed,
    model: Lithic::Document,
    options: options
  )
end