@spritz-finance/api-client 0.28.0 → 0.29.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.
package/README.md CHANGED
@@ -622,6 +622,39 @@ Some institutions send the user out to their bank's OAuth page and redirect back
622
622
 
623
623
  Pass the same value as `redirectUri` when creating the link token. The client-side work to resume the flow differs per platform (web requires re-initializing Link with `receivedRedirectUri`; native iOS/Android forward the redirect into the in-memory SDK). See [Handle OAuth redirects](docs/ach-onramp-guide.md#1c-handle-oauth-redirects) in the ACH Onramp guide for the full per-platform breakdown.
624
624
 
625
+ ##### Reconnect a bank account
626
+
627
+ Banks cut Plaid connections (password changes, expired consent). At Chase, PNC and U.S. Bank the account number Plaid returns belongs to the connection, so it can stop working when the connection breaks. Every bank account and funding source carries `connectionStatus`:
628
+
629
+ | `connectionStatus` | Meaning |
630
+ | -------------------- | ---------------------------------------------------------------------------------------------- |
631
+ | `connected` | Nothing to do |
632
+ | `expiring` | The bank will cut the connection soon; offer a reconnect |
633
+ | `reconnect_required` | The connection is cut or the number stopped working; reconnect before paying to or debiting it |
634
+ | `not_applicable` | Entered by hand, not linked through Plaid; nothing to reconnect |
635
+
636
+ To reconnect, create a link token for the bank account and run Plaid Link as usual. The bank account and its funding source keep their IDs:
637
+
638
+ ```typescript
639
+ const { linkToken, hostedLinkUrl } = await client.bankAccount.createLinkToken({
640
+ bankAccountId: bankAccount.id,
641
+ })
642
+ ```
643
+
644
+ With the Link SDK, pass the same `bankAccountId` when completing:
645
+
646
+ ```typescript
647
+ await client.bankAccount.completeLinking({
648
+ publicToken,
649
+ accountIds,
650
+ institutionId,
651
+ institutionName,
652
+ bankAccountId: bankAccount.id,
653
+ })
654
+ ```
655
+
656
+ If the user picks a different account at the bank, `completeLinking` throws a `ConflictError` with `problem.code === 'PLAID_ITEM_NOT_REPAIRABLE'` and nothing is linked; ask them to choose the same account. With Hosted Link, Spritz completes the reconnect when the session finishes. `bankAccountId` works whether or not the bank account has a funding source, so use it for payout destinations too; `fundingSourceId` is accepted in its place for funding sources.
657
+
625
658
  ##### Fall back to manual entry
626
659
 
627
660
  Plaid Link can be unavailable — it may not be enabled on your integration yet, `createLinkToken()` can fail, or the user may abandon or hit an error in the Link UI. Treat manual account/routing entry as a fallback so users can always add a bank account:
@@ -1361,7 +1394,7 @@ ACH onramp lets users convert USD from their bank account into USDC delivered to
1361
1394
  3. **Server:** complete linking with `client.bankAccount.completeLinking(...)`
1362
1395
  4. **Server:** find an active funding source and fetch limits with `client.fundingSource.getDepositLimits(id)`
1363
1396
  5. **Server:** prepare a quote with `client.deposit.prepare(...)`
1364
- 6. **Client:** show the quote and ACH authorization `message` to the user. If your UI lays out the amounts from `summary` itself, show `authorizationStatement` word for word instead. That's only allowed when `messageVersion` is `fomo_v2` or `fomo_v4`; for any other version, show `message` in full
1397
+ 6. **Client:** show the quote and ACH authorization `message` to the user. If your UI lays out the amounts from `summary` itself, show `authorizationStatement` word for word instead. That's only allowed when `messageVersion` is `fomo_v2`; for any other version, show `message` in full
1365
1398
  7. **Server:** create the deposit with `client.deposit.create(input, { idempotencyKey })`; Spritz runs risk checks before initiating the ACH pull. Persist one unique key per deposit intent and reuse it verbatim on retries so a timed-out request replays the original response instead of authorizing a second debit
1366
1399
  8. **Server:** track the deposit with `client.deposit.get(depositId)`, or reconcile a backlog by paging `client.deposit.list({ limit, cursor })`
1367
1400
  9. **Server (optional):** while `deposit.cancellable` is true, let the user call it off with `client.deposit.cancel(depositId)` (see [Cancelling a Deposit](docs/ach-onramp-guide.md#cancelling-a-deposit))