didit-sdk 2.28.0 → 2.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -81,6 +81,787 @@ module Didit
81
81
  request_options: request_options
82
82
  )
83
83
  end
84
+
85
+ # Cancel a bank link
86
+ #
87
+ # Cancels a link that is not completed yet; its url and token stop working. Cancelling a link that is already
88
+ # cancelled, expired, failed or completed answers `200` and returns it unchanged, so it is safe to repeat. A
89
+ # completed link keeps its connection.
90
+ #
91
+ # +POST /v3/bank/links/{id}/cancel/+
92
+ #
93
+ # @param id [String] The link id.
94
+ # @param idempotency_key [String] sent as the Idempotency-Key header
95
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
96
+ # @return [Didit::Types::BankLink]
97
+ def cancel_link(id, idempotency_key: OMIT, request_options: nil)
98
+ @client.request(
99
+ :post,
100
+ "/v3/bank/links/{id}/cancel/",
101
+ path_params: { "id" => id },
102
+ headers: { "Idempotency-Key" => idempotency_key },
103
+ response: Types::BankLink,
104
+ request_options: request_options
105
+ )
106
+ end
107
+
108
+ # Create a bank link
109
+ #
110
+ # Creates a Bank Link: one run of the flow in which a person connects a bank, or renews a connection. Send the
111
+ # person to `url`. The `client_token` is for Didit's embedded Bank Link, which is not released yet: open the
112
+ # `url` today. A completed link yields a connection.
113
+ #
114
+ # The smallest request is `{}` plus what you want. Defaults: `mode` connect, `access` one_time, `data` accounts
115
+ # only, `history_days` 90, `ownership.compare` none, `segment` any, `duplicates` reuse,
116
+ # `allow_one_time_fallback` false, and for ongoing access a consent as long as the bank allows.
117
+ #
118
+ # The response carries the quote: the price is pinned to the link and charged as quoted. The API key never
119
+ # reaches a browser or an app: only the `url` does.
120
+ #
121
+ # Confirm the outcome yourself with `get_link` or the `bank.link.completed` webhook; never trust a link id sent
122
+ # by the browser. History: send `history_from` or `history_days`, not both. Where the bank allows, ongoing
123
+ # access keeps working until the consent ends; the real date is on each connection.
124
+ #
125
+ # Needs an API key with the Bank data permission (`bank-data`): write for this operation, which changes
126
+ # something. A key with full access does not include it: grant it explicitly when you create the key, or the
127
+ # call answers `403 bank_data_access_denied`.
128
+ #
129
+ # +POST /v3/bank/links/+
130
+ #
131
+ # @param mode [String] `connect` (default) creates a new connection. `renew` needs `connection_id` and reuses
132
+ # that connection's settings.
133
+ # @param connection_id [String] The connection to renew. Only with `mode: renew`.
134
+ # @param access [String] `one_time` (default) reads the data once. `ongoing` keeps access open until the consent
135
+ # ends or someone stops it. With `institution_id` set, a bank that cannot keep access open answers `400
136
+ # ongoing_access_not_available` before any screen. Without it, the bank picker lists only banks that can.
137
+ # @param country [String] Optional. Without it the person picks among the countries your application enabled. It
138
+ # has to be a country Bank Link serves; any other, `ZZZ` included, answers `400 invalid_request` with `field:
139
+ # country`. An empty request body stays valid.
140
+ # @param institution_id [String] Optional bank to preselect, from `list_institutions`. Skips the picker.
141
+ # @param segment [String] Filters the picker and tells the bank which login to open where the bank separates
142
+ # them. Default `any`.
143
+ # @param data [Array<String>] What to read. `accounts` is always included: name, type, currency, identifiers and
144
+ # the holder name where the bank shares it. Default `["accounts"]`.
145
+ # @param history_days [Integer] Days of transaction history to request, 1 to 365, default 90. The bank may
146
+ # deliver less: each account reports what it delivered in `history_coverage`. Cannot be sent with
147
+ # `history_from`.
148
+ # @param history_from [Date, String] Start date of the history to request, instead of `history_days`. Cannot be
149
+ # sent with `history_days`: both together answer `400 history_window_ambiguous`. A date older than 365 days, or
150
+ # in the future, answers `400 window_not_available`.
151
+ # @param extended_history [String] `allow_extra_auth` lets a bank that asks for one more confirmation release
152
+ # older history.
153
+ # @param consent_days [Integer] Ongoing only. How many days to ask the bank to keep access open, 1 or more.
154
+ # Default: the longest the bank allows. The connection reports the date the bank actually granted in
155
+ # `consent.expires_at`. With `access: one_time` it answers `400 invalid_request` with `field: consent_days`.
156
+ # @param ownership [Hash] Optional comparison of the account holder with a person or a company.
157
+ # @param end_user [Hash] The person or company that connects the account.
158
+ # @param redirect_url [String] Where the browser goes at the end, with `link_id`, `status` and a signed `state`
159
+ # (for display only: the webhook and `get_link` are authoritative). In a sandbox application a plain `http`
160
+ # address of `localhost`, `127.0.0.1` or `[::1]` (any port and path, no credentials, no fragment) needs no
161
+ # registration. Any other address answers `400 redirect_url_not_registered`: registering other addresses is n...
162
+ # @param allowed_origins [Array<String>] Accepted and not used today: reserved for Didit's embedded Bank Link,
163
+ # which is not released yet. HTTPS origins, up to 50.
164
+ # @param language [String] Optional language code such as `es` or `pt-BR`. Otherwise the browser language.
165
+ # @param vendor_data [String] Your own reference, returned on the link and the connection.
166
+ # @param expires_in [Integer] Lifetime of the link in seconds, 300 to 86400. Default 3600.
167
+ # @param duplicates [String] `reuse` (default) completes a link that resolves to accounts you already share as a
168
+ # renewal of that connection. `allow` creates an independent second connection.
169
+ # @param allow_one_time_fallback [Boolean] With `ongoing`, lets the person continue with a one-time read at a
170
+ # bank that cannot keep access open, after confirming the reduced access on its own screen. The quote shows what
171
+ # that costs. Only with `access: ongoing`: with one-time access it answers `400 invalid_request` with `field:
172
+ # allow_one_time_fallback`.
173
+ # @param accept_reduced_grant [Boolean] When the bank or the person grants less than you asked for, complete the
174
+ # link and charge only the granted scopes. Otherwise the link ends `failed` with `reduced_grant` and nothing is
175
+ # charged.
176
+ # @param sandbox [Hash] Sandbox applications only: picks the Didit Test Bank customer. Ignored in a live
177
+ # application.
178
+ # @param idempotency_key [String] sent as the Idempotency-Key header
179
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
180
+ # @return [Didit::Types::BankLink]
181
+ def create_link(
182
+ mode: OMIT,
183
+ connection_id: OMIT,
184
+ access: OMIT,
185
+ country: OMIT,
186
+ institution_id: OMIT,
187
+ segment: OMIT,
188
+ data: OMIT,
189
+ history_days: OMIT,
190
+ history_from: OMIT,
191
+ extended_history: OMIT,
192
+ consent_days: OMIT,
193
+ ownership: OMIT,
194
+ end_user: OMIT,
195
+ redirect_url: OMIT,
196
+ allowed_origins: OMIT,
197
+ language: OMIT,
198
+ vendor_data: OMIT,
199
+ expires_in: OMIT,
200
+ duplicates: OMIT,
201
+ allow_one_time_fallback: OMIT,
202
+ accept_reduced_grant: OMIT,
203
+ sandbox: OMIT,
204
+ idempotency_key: OMIT,
205
+ request_options: nil
206
+ )
207
+ @client.request(
208
+ :post,
209
+ "/v3/bank/links/",
210
+ body: {
211
+ "mode" => mode,
212
+ "connection_id" => connection_id,
213
+ "access" => access,
214
+ "country" => country,
215
+ "institution_id" => institution_id,
216
+ "segment" => segment,
217
+ "data" => data,
218
+ "history_days" => history_days,
219
+ "history_from" => history_from,
220
+ "extended_history" => extended_history,
221
+ "consent_days" => consent_days,
222
+ "ownership" => ownership,
223
+ "end_user" => end_user,
224
+ "redirect_url" => redirect_url,
225
+ "allowed_origins" => allowed_origins,
226
+ "language" => language,
227
+ "vendor_data" => vendor_data,
228
+ "expires_in" => expires_in,
229
+ "duplicates" => duplicates,
230
+ "allow_one_time_fallback" => allow_one_time_fallback,
231
+ "accept_reduced_grant" => accept_reduced_grant,
232
+ "sandbox" => sandbox
233
+ },
234
+ headers: { "Idempotency-Key" => idempotency_key },
235
+ response: Types::BankLink,
236
+ request_options: request_options
237
+ )
238
+ end
239
+
240
+ # Delete a bank connection
241
+ #
242
+ # Deletes the connection's bank data and stops access at the bank. The connection's accounts, balances,
243
+ # transactions, sync history, consent records and ownership results are deleted. Deletion is irreversible.
244
+ #
245
+ # It starts at once: the response is `202` with `erasure.status` `pending`, and from that moment the
246
+ # connection's data operations (refresh, sync runs, accounts, balances, transactions and the change feed) answer
247
+ # `409 connection_not_active`. The connection then reads with `erasure.status` `erased`, or `failed` if deletion
248
+ # could not be confirmed within 24 hours; a failed deletion is retried until it completes. A deleted connection
249
+ # reads as a minimal record: its id, `status: deleted`, the reason, its dates and its `erasure` status, and it
250
+ # holds no accounts, balances, transactions, consent or sync data.
251
+ #
252
+ # Not affected: your other connections, the charges already made (they are not refunded), and any data you
253
+ # already downloaded, which is your own copy. Repeating the call returns the current state. To stop access
254
+ # without deleting, use `revoke_connection`.
255
+ #
256
+ # Needs an API key with the Bank data permission (`bank-data`): write for this operation, which changes
257
+ # something. A key with full access does not include it: grant it explicitly when you create the key, or the
258
+ # call answers `403 bank_data_access_denied`.
259
+ #
260
+ # +DELETE /v3/bank/connections/{id}/+
261
+ #
262
+ # @param id [String] The connection id.
263
+ # @param idempotency_key [String] sent as the Idempotency-Key header
264
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
265
+ # @return [Didit::Types::BankConnectionDeletion]
266
+ def delete_connection(id, idempotency_key: OMIT, request_options: nil)
267
+ @client.request(
268
+ :delete,
269
+ "/v3/bank/connections/{id}/",
270
+ path_params: { "id" => id },
271
+ headers: { "Idempotency-Key" => idempotency_key },
272
+ response: Types::BankConnectionDeletion,
273
+ request_options: request_options
274
+ )
275
+ end
276
+
277
+ # Get an account
278
+ #
279
+ # Returns one account with full identifiers, holders, sync state and `history_coverage`, which says what the
280
+ # bank delivered of the history you asked for. `sync.last_synced_at` is when the data was fetched from the bank,
281
+ # not when you read it.
282
+ #
283
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
284
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
285
+ # bank_data_access_denied`. A sandbox application reads its Test Bank data with the key alone. A request without
286
+ # an API key (client credentials) is refused on raw data with the same `403`.
287
+ #
288
+ # +GET /v3/bank/accounts/{account_id}/+
289
+ #
290
+ # @param account_id [String] The account id.
291
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
292
+ # @return [Didit::Types::BankAccount]
293
+ def get_account(account_id, request_options: nil)
294
+ @client.request(
295
+ :get,
296
+ "/v3/bank/accounts/{account_id}/",
297
+ path_params: { "account_id" => account_id },
298
+ response: Types::BankAccount,
299
+ request_options: request_options
300
+ )
301
+ end
302
+
303
+ # Get account balances
304
+ #
305
+ # Returns the typed balances of an account with their reference dates. Balances are replaced at each sync.
306
+ #
307
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
308
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
309
+ # bank_data_access_denied`. A sandbox application reads its Test Bank data with the key alone. A request without
310
+ # an API key (client credentials) is refused on raw data with the same `403`.
311
+ #
312
+ # +GET /v3/bank/accounts/{account_id}/balances/+
313
+ #
314
+ # @param account_id [String] The account id.
315
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
316
+ # @return [Didit::Types::BankBalances]
317
+ def get_balances(account_id, request_options: nil)
318
+ @client.request(
319
+ :get,
320
+ "/v3/bank/accounts/{account_id}/balances/",
321
+ path_params: { "account_id" => account_id },
322
+ response: Types::BankBalances,
323
+ request_options: request_options
324
+ )
325
+ end
326
+
327
+ # Get a bank connection
328
+ #
329
+ # Returns the connection with its consent, sync state and a summary of each account. Read the data itself with
330
+ # the accounts, balances and transactions operations. A connection that was deleted reads as a minimal record:
331
+ # its id, `status: deleted`, the reason, its dates and its `erasure` status, and no accounts, balances,
332
+ # transactions, consent or sync data.
333
+ #
334
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
335
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
336
+ # bank_data_access_denied`.
337
+ #
338
+ # +GET /v3/bank/connections/{id}/+
339
+ #
340
+ # @param id [String] The connection id.
341
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
342
+ # @return [Didit::Types::BankConnection]
343
+ def get_connection(id, request_options: nil)
344
+ @client.request(
345
+ :get,
346
+ "/v3/bank/connections/{id}/",
347
+ path_params: { "id" => id },
348
+ response: Types::BankConnection,
349
+ request_options: request_options
350
+ )
351
+ end
352
+
353
+ # Get bank data coverage
354
+ #
355
+ # Returns one entry per country: whether bank sign-in and the account check are available, and whether ongoing
356
+ # access is available, with how many banks offer it, the longest consent and deepest history any of them allows,
357
+ # and whether business accounts are supported. Ongoing access is counted only where a bank is switched on for
358
+ # it. Use it to decide which countries to offer; use `list_institutions` for a single bank.
359
+ #
360
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
361
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
362
+ # bank_data_access_denied`.
363
+ #
364
+ # +GET /v3/bank/coverage/+
365
+ #
366
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
367
+ # @return [Didit::Types::BankCoverage]
368
+ def get_coverage(request_options: nil)
369
+ @client.request(
370
+ :get,
371
+ "/v3/bank/coverage/",
372
+ response: Types::BankCoverage,
373
+ request_options: request_options
374
+ )
375
+ end
376
+
377
+ # Get an institution
378
+ #
379
+ # Returns one bank with its capabilities. The id is Didit's slug, as listed by `list_institutions`.
380
+ #
381
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
382
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
383
+ # bank_data_access_denied`.
384
+ #
385
+ # +GET /v3/bank/institutions/{id}/+
386
+ #
387
+ # @param id [String] The institution id, for example `es-banco-norte`.
388
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
389
+ # @return [Didit::Types::BankInstitution]
390
+ def get_institution(id, request_options: nil)
391
+ @client.request(
392
+ :get,
393
+ "/v3/bank/institutions/{id}/",
394
+ path_params: { "id" => id },
395
+ response: Types::BankInstitution,
396
+ request_options: request_options
397
+ )
398
+ end
399
+
400
+ # Get a bank link
401
+ #
402
+ # Returns the status of a link and, once it is `completed`, its `connection_id` and `check_id`. This is the
403
+ # authoritative answer: call it from your server after the browser reports success, or on the
404
+ # `bank.link.completed` webhook.
405
+ #
406
+ # A link that fails is not an HTTP error: it reads `200` with `status: failed` and an `error` object, for
407
+ # example `duplicate_conflict` with `conflicts_with`. `url` and `client_token` are returned only when the link
408
+ # is created.
409
+ #
410
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
411
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
412
+ # bank_data_access_denied`.
413
+ #
414
+ # +GET /v3/bank/links/{id}/+
415
+ #
416
+ # @param id [String] The link id.
417
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
418
+ # @return [Didit::Types::BankLink]
419
+ def get_link(id, request_options: nil)
420
+ @client.request(
421
+ :get,
422
+ "/v3/bank/links/{id}/",
423
+ path_params: { "id" => id },
424
+ response: Types::BankLink,
425
+ request_options: request_options
426
+ )
427
+ end
428
+
429
+ # Get a sync run
430
+ #
431
+ # Returns one sync run with its results per account and resource.
432
+ #
433
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
434
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
435
+ # bank_data_access_denied`.
436
+ #
437
+ # +GET /v3/bank/connections/{id}/sync-runs/{sync_id}/+
438
+ #
439
+ # @param id [String] The connection id.
440
+ # @param sync_id [String] The sync run id.
441
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
442
+ # @return [Didit::Types::BankSyncRun]
443
+ def get_sync_run(id, sync_id, request_options: nil)
444
+ @client.request(
445
+ :get,
446
+ "/v3/bank/connections/{id}/sync-runs/{sync_id}/",
447
+ path_params: { "id" => id, "sync_id" => sync_id },
448
+ response: Types::BankSyncRun,
449
+ request_options: request_options
450
+ )
451
+ end
452
+
453
+ # List accounts of a connection
454
+ #
455
+ # Lists every account of the connection, oldest first, with full identifiers and holders. A read never bills.
456
+ #
457
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
458
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
459
+ # bank_data_access_denied`. A sandbox application reads its Test Bank data with the key alone. A request without
460
+ # an API key (client credentials) is refused on raw data with the same `403`.
461
+ #
462
+ # +GET /v3/bank/connections/{id}/accounts/+
463
+ #
464
+ # @param id [String] The connection id.
465
+ # @param limit [Integer] Page size, 1 to 500. Default 100.
466
+ # @param cursor [String] Opaque cursor from the previous page's `next_cursor`.
467
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
468
+ # @return [Didit::Types::BankAccountList]
469
+ def list_accounts(id, limit: OMIT, cursor: OMIT, request_options: nil)
470
+ @client.request(
471
+ :get,
472
+ "/v3/bank/connections/{id}/accounts/",
473
+ path_params: { "id" => id },
474
+ query: {
475
+ "limit" => limit,
476
+ "cursor" => cursor
477
+ },
478
+ response: Types::BankAccountList,
479
+ request_options: request_options
480
+ )
481
+ end
482
+
483
+ # List bank connections
484
+ #
485
+ # Lists the connections of your application, newest first, with cursor pagination. All filters apply inside your
486
+ # application and environment.
487
+ #
488
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
489
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
490
+ # bank_data_access_denied`.
491
+ #
492
+ # In this list `sync.budgets` shows only the budgets that exist already; `GET /v3/bank/connections/{id}/` opens
493
+ # today's budgets.
494
+ #
495
+ # +GET /v3/bank/connections/+
496
+ #
497
+ # @param status [String] Only connections in this status.
498
+ # @param access [String] Only this access mode.
499
+ # @param institution_id [String] Only this bank.
500
+ # @param country [String] Only banks in this country.
501
+ # @param vendor_data [String] Only connections with this `vendor_data`.
502
+ # @param end_user_reference [String] Only connections with this `end_user.reference`.
503
+ # @param consent_expires_before [Time, String] Only connections whose consent ends before this time, for example
504
+ # to send renew links.
505
+ # @param created_after [Time, String] Only connections created after this time.
506
+ # @param limit [Integer] Page size, 1 to 500. Default 100.
507
+ # @param cursor [String] Opaque cursor from the previous page's `next_cursor`.
508
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
509
+ # @return [Didit::Types::BankConnectionList]
510
+ def list_connections(
511
+ status: OMIT,
512
+ access: OMIT,
513
+ institution_id: OMIT,
514
+ country: OMIT,
515
+ vendor_data: OMIT,
516
+ end_user_reference: OMIT,
517
+ consent_expires_before: OMIT,
518
+ created_after: OMIT,
519
+ limit: OMIT,
520
+ cursor: OMIT,
521
+ request_options: nil
522
+ )
523
+ @client.request(
524
+ :get,
525
+ "/v3/bank/connections/",
526
+ query: {
527
+ "status" => status,
528
+ "access" => access,
529
+ "institution_id" => institution_id,
530
+ "country" => country,
531
+ "vendor_data" => vendor_data,
532
+ "end_user_reference" => end_user_reference,
533
+ "consent_expires_before" => consent_expires_before,
534
+ "created_after" => created_after,
535
+ "limit" => limit,
536
+ "cursor" => cursor
537
+ },
538
+ response: Types::BankConnectionList,
539
+ request_options: request_options
540
+ )
541
+ end
542
+
543
+ # List institutions
544
+ #
545
+ # Lists the banks per country with their capabilities: segments, access modes, the longest consent and deepest
546
+ # history the bank offers, whether it reports pending transactions, which transaction fields it is known to
547
+ # send, and how the person signs in. Values come from observed data, refreshed daily; a value never observed is
548
+ # `null`. The same data feeds the bank picker, so use it to know what to expect before you create a link.
549
+ # `access` lists `ongoing` only where ongoing access is available.
550
+ #
551
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
552
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
553
+ # bank_data_access_denied`.
554
+ #
555
+ # The list is sorted by name, then id.
556
+ #
557
+ # In a sandbox application the list holds the Didit Test Bank, one per country Bank Link serves, and no live
558
+ # bank.
559
+ #
560
+ # +GET /v3/bank/institutions/+
561
+ #
562
+ # @param country [String] Only banks in this country, an ISO 3166-1 alpha-3 code. A country Bank Link does not
563
+ # serve answers `400 invalid_request` with `field: country`.
564
+ # @param segment [String] Only banks that serve this segment.
565
+ # @param access [String] Only banks that offer this access mode.
566
+ # @param q [String] Search by name or id, case-insensitive.
567
+ # @param limit [Integer] Page size, 1 to 500. Default 100.
568
+ # @param cursor [String] Opaque cursor from the previous page's `next_cursor`.
569
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
570
+ # @return [Didit::Types::BankInstitutionList]
571
+ def list_institutions(
572
+ country: OMIT,
573
+ segment: OMIT,
574
+ access: OMIT,
575
+ q: OMIT,
576
+ limit: OMIT,
577
+ cursor: OMIT,
578
+ request_options: nil
579
+ )
580
+ @client.request(
581
+ :get,
582
+ "/v3/bank/institutions/",
583
+ query: {
584
+ "country" => country,
585
+ "segment" => segment,
586
+ "access" => access,
587
+ "q" => q,
588
+ "limit" => limit,
589
+ "cursor" => cursor
590
+ },
591
+ response: Types::BankInstitutionList,
592
+ request_options: request_options
593
+ )
594
+ end
595
+
596
+ # List sync runs
597
+ #
598
+ # Lists what each sync of a connection did, newest first, per account and resource.
599
+ #
600
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
601
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
602
+ # bank_data_access_denied`.
603
+ #
604
+ # +GET /v3/bank/connections/{id}/sync-runs/+
605
+ #
606
+ # @param id [String] The connection id.
607
+ # @param limit [Integer] Page size, 1 to 500. Default 100.
608
+ # @param cursor [String] Opaque cursor from the previous page's `next_cursor`.
609
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
610
+ # @return [Didit::Types::BankSyncRunList]
611
+ def list_sync_runs(id, limit: OMIT, cursor: OMIT, request_options: nil)
612
+ @client.request(
613
+ :get,
614
+ "/v3/bank/connections/{id}/sync-runs/",
615
+ path_params: { "id" => id },
616
+ query: {
617
+ "limit" => limit,
618
+ "cursor" => cursor
619
+ },
620
+ response: Types::BankSyncRunList,
621
+ request_options: request_options
622
+ )
623
+ end
624
+
625
+ # List account transactions
626
+ #
627
+ # Date-range read of an account's transactions, sorted by `effective_date` descending, then `id` descending, in
628
+ # pages of up to 500. `date_from` and `date_to` are calendar dates, inclusive, in the bank's own time zone with
629
+ # nothing converted. They apply to `effective_date`: for a booked transaction its booking date, else its value
630
+ # date, else the date it was first seen; for a pending one its transaction date, else the date it was first
631
+ # seen. By default `date_from` is the start of the stored history and `date_to` has no upper bound, and booked
632
+ # and pending are both returned.
633
+ #
634
+ # The first page pins which transactions are included and each is served in its current state: a transaction
635
+ # removed while you page drops out of later pages and is reported by the change feed (`sync_transactions`).
636
+ # `page_token` continues one read and lives one hour; an expired token answers `410 page_expired`, so restart
637
+ # the read from its original query. To keep a copy up to date, use the change feed instead of re-reading ranges.
638
+ #
639
+ # Response headers: `X-Bank-Last-Synced-At` and `Cache-Control: no-store`.
640
+ #
641
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
642
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
643
+ # bank_data_access_denied`. A sandbox application reads its Test Bank data with the key alone. A request without
644
+ # an API key (client credentials) is refused on raw data with the same `403`.
645
+ #
646
+ # +GET /v3/bank/accounts/{account_id}/transactions/+
647
+ #
648
+ # @param account_id [String] The account id.
649
+ # @param date_from [Date, String] First effective date to include, inclusive.
650
+ # @param date_to [Date, String] Last effective date to include, inclusive. No upper bound when you leave it out.
651
+ # @param status [String] Only booked or only pending transactions. Default both.
652
+ # @param limit [Integer] Page size, 1 to 500. Default 100.
653
+ # @param page_token [String] The `next_page_token` of the previous page.
654
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
655
+ # @return [Didit::Types::BankTransactionPage]
656
+ def list_transactions(
657
+ account_id,
658
+ date_from: OMIT,
659
+ date_to: OMIT,
660
+ status: OMIT,
661
+ limit: OMIT,
662
+ page_token: OMIT,
663
+ request_options: nil
664
+ )
665
+ @client.request(
666
+ :get,
667
+ "/v3/bank/accounts/{account_id}/transactions/",
668
+ path_params: { "account_id" => account_id },
669
+ query: {
670
+ "date_from" => date_from,
671
+ "date_to" => date_to,
672
+ "status" => status,
673
+ "limit" => limit,
674
+ "page_token" => page_token
675
+ },
676
+ response: Types::BankTransactionPage,
677
+ request_options: request_options
678
+ )
679
+ end
680
+
681
+ # Refresh a bank connection
682
+ #
683
+ # Syncs now: reads the bank for new data at any moment. Answers `202` with the `sync_id`; if a sync is already
684
+ # running you get that same `sync_id`, not a second job. With `"wait": true` in the body, or the header `Prefer:
685
+ # wait=<seconds>` (up to 25), the call holds for up to 25 seconds and answers `200` with the finished sync
686
+ # (`outcome`, the per-account counts and `balances_changed`), so one request returns fresh data. If the bank has
687
+ # not answered in that time it answers `202`: read the sync with `get_sync_run` using the `sync_id`, or
688
+ # subscribe to `bank.sync.completed`. `bank.data.updated` follows only when the sync stores changes.
689
+ #
690
+ # Live syncs are included in the monthly price of the connection, like the automatic syncs: nothing extra is
691
+ # charged. The only limit is the bank's. Banks limit reads without the person present, for example to four a day
692
+ # (the Didit Test Bank in sandbox does the same). The automatic syncs of the day (`sync.frequency_per_day`) are
693
+ # set aside first and the rest are yours, so `sync.budgets` shows what is left and `sync.live_syncs_left_today`
694
+ # how many live syncs remain today. The automatic schedule never uses the last two reads of a day, so two live
695
+ # syncs always remain. When the budget is used up the call answers `429 refresh_limit_reached` with
696
+ # `Retry-After` (the seconds until the budget resets, 1 to 86400) and a `sync` object with
697
+ # `live_syncs_left_today` and `budgets`. The limit is a ceiling set by the bank, not a promise of a number of
698
+ # syncs.
699
+ #
700
+ # When a sync stores changes, `bank.data.updated` tells you; then read the change feed.
701
+ #
702
+ # Needs an API key with the Bank data permission (`bank-data`): write for this operation, which changes
703
+ # something. A key with full access does not include it: grant it explicitly when you create the key, or the
704
+ # call answers `403 bank_data_access_denied`.
705
+ #
706
+ # Refreshing a deleted connection answers `409 connection_not_active`.
707
+ #
708
+ # +POST /v3/bank/connections/{id}/refresh/+
709
+ #
710
+ # @param id [String] The connection id.
711
+ # @param wait [Boolean] `true` holds the call for up to 25 seconds and answers `200` with the finished sync, so
712
+ # one request returns fresh data. If the bank has not answered in that time the call answers `202`: read the
713
+ # sync with `get_sync_run` using the `sync_id`, or subscribe to `bank.sync.completed`. `bank.data.updated`
714
+ # follows only when the sync stores changes. The header `Prefer: wait=<seconds>` (up to 25) does the...
715
+ # @param idempotency_key [String] sent as the Idempotency-Key header
716
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
717
+ # @return [Didit::Types::BankSyncCompleted, Didit::Types::BankRefreshAccepted]
718
+ def refresh_connection(id, wait: OMIT, idempotency_key: OMIT, request_options: nil)
719
+ @client.request(
720
+ :post,
721
+ "/v3/bank/connections/{id}/refresh/",
722
+ path_params: { "id" => id },
723
+ body: {
724
+ "wait" => wait
725
+ },
726
+ headers: { "Idempotency-Key" => idempotency_key },
727
+ response: { 200 => Types::BankSyncCompleted, 202 => Types::BankRefreshAccepted },
728
+ request_options: request_options
729
+ )
730
+ end
731
+
732
+ # Renew a bank connection
733
+ #
734
+ # Creates a renew link for this connection, a shortcut for `create_link` with `mode: renew`. The connection id
735
+ # and every account id stay the same.
736
+ #
737
+ # Opening the returned link on the hosted page is not available yet: the page that lets the person renew is
738
+ # still to be built.
739
+ #
740
+ # Until the consent has 30 days left or fewer it answers `409 renewal_not_needed`; after
741
+ # `consent.renewable_until` it answers `409 renewal_window_expired` and the person connects again.
742
+ #
743
+ # Needs an API key with the Bank data permission (`bank-data`): write for this operation, which changes
744
+ # something. A key with full access does not include it: grant it explicitly when you create the key, or the
745
+ # call answers `403 bank_data_access_denied`.
746
+ #
747
+ # +POST /v3/bank/connections/{id}/renew/+
748
+ #
749
+ # @param id [String] The connection id.
750
+ # @param redirect_url [String] Where the browser goes at the end. In a sandbox application a plain `http`
751
+ # address of `localhost`, `127.0.0.1` or `[::1]` needs no registration. Any other address answers `400
752
+ # redirect_url_not_registered`: registering other addresses is not available yet.
753
+ # @param allowed_origins [Array<String>] Accepted and not used today: reserved for Didit's embedded Bank Link,
754
+ # which is not released yet. HTTPS origins, up to 50.
755
+ # @param language [String]
756
+ # @param expires_in [Integer] Lifetime in seconds, 300 to 86400.
757
+ # @param idempotency_key [String] sent as the Idempotency-Key header
758
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
759
+ # @return [Didit::Types::BankLink]
760
+ def renew_connection(
761
+ id,
762
+ redirect_url: OMIT,
763
+ allowed_origins: OMIT,
764
+ language: OMIT,
765
+ expires_in: OMIT,
766
+ idempotency_key: OMIT,
767
+ request_options: nil
768
+ )
769
+ @client.request(
770
+ :post,
771
+ "/v3/bank/connections/{id}/renew/",
772
+ path_params: { "id" => id },
773
+ body: {
774
+ "redirect_url" => redirect_url,
775
+ "allowed_origins" => allowed_origins,
776
+ "language" => language,
777
+ "expires_in" => expires_in
778
+ },
779
+ headers: { "Idempotency-Key" => idempotency_key },
780
+ response: Types::BankLink,
781
+ request_options: request_options
782
+ )
783
+ end
784
+
785
+ # Revoke a bank connection
786
+ #
787
+ # Stops access to the bank. Bank fetches stop the moment you ask, even while the bank's confirmation is pending:
788
+ # the consent reads `revocation_pending`, then `revoked` once the bank confirms access is terminated, or
789
+ # `revocation_failed` while the call is retried automatically. `consent.ended_by` is `customer`.
790
+ #
791
+ # Revoking does not delete anything: stored accounts, balances and transactions stay readable until
792
+ # `consent.retain_until`, the retention setting of your application, and nothing is charged. To delete them now,
793
+ # call `delete_connection`. Repeating the call returns the current state.
794
+ #
795
+ # Needs an API key with the Bank data permission (`bank-data`): write for this operation, which changes
796
+ # something. A key with full access does not include it: grant it explicitly when you create the key, or the
797
+ # call answers `403 bank_data_access_denied`.
798
+ #
799
+ # Revoking a connection that was deleted answers `200` with the deleted connection, so repeating the call is
800
+ # safe.
801
+ #
802
+ # +POST /v3/bank/connections/{id}/revoke/+
803
+ #
804
+ # @param id [String] The connection id.
805
+ # @param idempotency_key [String] sent as the Idempotency-Key header
806
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
807
+ # @return [Didit::Types::BankConnection]
808
+ def revoke_connection(id, idempotency_key: OMIT, request_options: nil)
809
+ @client.request(
810
+ :post,
811
+ "/v3/bank/connections/{id}/revoke/",
812
+ path_params: { "id" => id },
813
+ headers: { "Idempotency-Key" => idempotency_key },
814
+ response: Types::BankConnection,
815
+ request_options: request_options
816
+ )
817
+ end
818
+
819
+ # Sync transactions (change feed)
820
+ #
821
+ # Returns what changed in a connection's transactions since a `cursor`: `added`, `modified` and `removed` (with
822
+ # a `reason`), across all its accounts. An empty cursor returns every current transaction as `added` and sets
823
+ # `reset: true`: replace your copy with it instead of adding to it.
824
+ #
825
+ # The first read is a true snapshot. A first read (no cursor, or the read after `reset`) returns every
826
+ # transaction the connection had when the read started, each exactly once as `added`, in its current state, even
827
+ # if a sync runs while you page. Changes made while you were paging arrive in the next read from `next_cursor`:
828
+ # a transaction you already received comes again as `modified`, and a new one as `added`. Apply `modified` as an
829
+ # upsert by `id`, and ignore a `removed` id you do not have. All pages of one read reflect the same point in
830
+ # time. Keep paging with `page_token` while `has_more` is `true`, and store `next_cursor` only after a response
831
+ # with `has_more: false`. If paging fails midway, restart from the cursor you had stored.
832
+ #
833
+ # The change log is replayable for 90 days. An older cursor answers `410 cursor_expired` with `bootstrap: true`:
834
+ # start again from an empty cursor. Stored history is never aged out while the connection exists. A booked
835
+ # pending transaction appears in `added` and the pending one in `removed` with `reason: pending_booked`. Webhook
836
+ # `bank.data.updated` tells you when to call.
837
+ #
838
+ # Needs an API key with the Bank data permission (`bank-data`): read for this operation. A key with full access
839
+ # does not include it: grant it explicitly when you create the key, or the call answers `403
840
+ # bank_data_access_denied`. A sandbox application reads its Test Bank data with the key alone. A request without
841
+ # an API key (client credentials) is refused on raw data with the same `403`.
842
+ #
843
+ # +GET /v3/bank/connections/{id}/transactions/sync/+
844
+ #
845
+ # @param id [String] The connection id.
846
+ # @param cursor [String] The `next_cursor` you stored. Empty or omitted starts from the beginning.
847
+ # @param limit [Integer] Page size, 1 to 500. Default 100.
848
+ # @param page_token [String] Continues the same read while `has_more` is `true`.
849
+ # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
850
+ # @return [Didit::Types::BankTransactionChanges]
851
+ def sync_transactions(id, cursor: OMIT, limit: OMIT, page_token: OMIT, request_options: nil)
852
+ @client.request(
853
+ :get,
854
+ "/v3/bank/connections/{id}/transactions/sync/",
855
+ path_params: { "id" => id },
856
+ query: {
857
+ "cursor" => cursor,
858
+ "limit" => limit,
859
+ "page_token" => page_token
860
+ },
861
+ response: Types::BankTransactionChanges,
862
+ request_options: request_options
863
+ )
864
+ end
84
865
  end
85
866
  end
86
867
  end