@spritz-finance/api-client 0.27.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:
@@ -1398,6 +1431,8 @@ To move submission onto the customer's device, pass `clientNetwork: { ipAddresse
1398
1431
 
1399
1432
  If risk checks block the create step, the API returns 409 before any ACH debit is pulled. Prepare a new quote before retrying; blocked create attempts consume the original `preparationId`.
1400
1433
 
1434
+ When a `priority: 'high'` preparation can get no instant portion at create, the deposit goes ahead at standard timing by default. Send `instantFallback: 'confirm'` to ask the user first: `create` then throws a `ConflictError` with `problem.code === 'instant_unavailable'` and leaves the preparation usable. Once the user accepts standard timing, call `create` again with the same `preparationId`, `instantFallback: 'standard'` and a new idempotency key. See [Confirming a fallback from instant](docs/ach-onramp-guide.md#confirming-a-fallback-from-instant).
1435
+
1401
1436
  For a complete walkthrough with code examples, request/response schemas, and deposit lifecycle documentation, see the **[ACH Onramp Integration Guide](docs/ach-onramp-guide.md)**.
1402
1437
 
1403
1438
  A standalone sandbox demo is available at `scripts/sandbox/ach-onramp.html`. Run `yarn build && node scripts/sandbox/evidence-server.mjs`, then open `http://localhost:3001/ach-onramp.html` to test the SDK-backed flow and save redacted QC evidence.