@spritz-finance/api-client 0.9.0 → 0.11.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
@@ -82,6 +82,7 @@ const transactionData = await client.paymentRequest.getWeb3PaymentParams({
82
82
  - [Transaction Fees](#transaction-fees)
83
83
  - [Retrieving Payments](#retrieving-payments)
84
84
  - [Payment Limits](#payment-limits)
85
+ - [Refunding a Payment](#refunding-a-payment)
85
86
  - [On-ramp](#on-ramp)
86
87
  - [Prerequisites](#prerequisites)
87
88
  - [Checking User Access](#checking-user-access)
@@ -331,6 +332,133 @@ interface CABankAccountInput {
331
332
  }
332
333
  ```
333
334
 
335
+ #### Link a US Bank Account with Plaid
336
+
337
+ Rather than collecting raw account and routing numbers, link a US bank account through [Plaid Link](https://plaid.com/docs/link/). Plaid verifies account ownership, returns institution metadata, and — for ACH-eligible accounts — provisions the **funding source** required for [ACH onramp](#ach-onramp-direct-debit).
338
+
339
+ > **Plaid Link must be enabled on your integration.** It is gated per account. If `createLinkToken()` returns `403`, contact Spritz to enable it, and fall back to [Create US Bank Account](#create-us-bank-account) in the meantime (see [Fall back to manual entry](#fall-back-to-manual-entry) below).
340
+
341
+ Linking is a two-part flow: create a link token on your **server**, then run the Plaid Link UI on the **client**. The SDK is server-side only — only the Plaid Link UI runs in the browser.
342
+
343
+ **1. Create a link token (server)**
344
+
345
+ ```typescript
346
+ const { linkToken, hostedLinkUrl, expiration } = await client.bankAccount.createLinkToken()
347
+ ```
348
+
349
+ | Field | Type | Description |
350
+ | --------------- | ---------------- | --------------------------------------------------------- |
351
+ | `linkToken` | `string` | Token for initializing the Plaid Link SDK |
352
+ | `hostedLinkUrl` | `string \| null` | Plaid-hosted linking URL (alternative to running the SDK) |
353
+ | `expiration` | `string` | Token expiry (ISO 8601) |
354
+
355
+ If a bank uses OAuth, pass the OAuth target as `redirectUri` (see [Handle OAuth redirects](#handle-oauth-redirects)):
356
+
357
+ ```typescript
358
+ await client.bankAccount.createLinkToken({
359
+ // Web / iOS: an https:// return URL or iOS universal link
360
+ // Android: your package name (e.g. 'com.example.app')
361
+ redirectUri: 'https://app.example.com/plaid/oauth-return',
362
+ })
363
+ ```
364
+
365
+ **2. Run Plaid Link (client)**
366
+
367
+ Hand the `linkToken` to the Plaid Link SDK ([React Native](https://plaid.com/docs/link/react-native/), [Web](https://plaid.com/docs/link/web/), [iOS](https://plaid.com/docs/link/ios/), [Android](https://plaid.com/docs/link/android/)). On success, send the public token and selected account IDs back to your server.
368
+
369
+ React Native ([`react-native-plaid-link-sdk`](https://github.com/plaid/react-native-plaid-link-sdk) v11+):
370
+
371
+ ```typescript
372
+ import { create, open } from 'react-native-plaid-link-sdk'
373
+
374
+ create({
375
+ token: linkToken,
376
+ onSuccess: async (success) => {
377
+ await yourServer.completePlaidLink({
378
+ publicToken: success.publicToken,
379
+ accountIds: success.metadata.accounts.map((a) => a.id),
380
+ institutionId: success.metadata.institution?.id,
381
+ institutionName: success.metadata.institution?.name,
382
+ })
383
+ },
384
+ onExit: (exit) => {
385
+ if (exit.error) console.error('Plaid error:', exit.error)
386
+ },
387
+ })
388
+
389
+ open()
390
+ ```
391
+
392
+ Web ([`react-plaid-link`](https://github.com/plaid/react-plaid-link) or the vanilla JS SDK):
393
+
394
+ ```typescript
395
+ const handler = Plaid.create({
396
+ token: linkToken,
397
+ onSuccess: async (publicToken, metadata) => {
398
+ await yourServer.completePlaidLink({
399
+ publicToken,
400
+ accountIds: metadata.accounts.map((a) => a.id),
401
+ // Web SDK uses institution_id; the RN SDK uses id
402
+ institutionId: metadata.institution?.institution_id,
403
+ institutionName: metadata.institution?.name,
404
+ })
405
+ },
406
+ })
407
+ handler.open()
408
+ ```
409
+
410
+ **3. Complete linking (server)**
411
+
412
+ ```typescript
413
+ const { bankAccounts } = await client.bankAccount.completeLinking({
414
+ publicToken,
415
+ accountIds,
416
+ institutionId,
417
+ institutionName,
418
+ })
419
+
420
+ // A funding source is provisioned for ACH-eligible accounts. Its presence is
421
+ // the signal that the account can be used for ACH onramp.
422
+ const onrampable = bankAccounts.find((b) => b.fundingSourceId)
423
+ ```
424
+
425
+ `completeLinking` exchanges the public token, stores the linked bank account(s), and provisions a funding source for ACH-eligible accounts. A `null` `fundingSourceId` means the account is usable for off-ramp only. See the [ACH Onramp Integration Guide](docs/ach-onramp-guide.md#bank-accounts-vs-funding-sources) for the bank-account-vs-funding-source model.
426
+
427
+ ##### Handle OAuth redirects
428
+
429
+ Some institutions send the user out to their bank's OAuth page and redirect back when auth completes. Because Spritz creates the link token, the redirect targets must be **allowlisted on Spritz's Plaid account** — send them to Spritz before going live:
430
+
431
+ | Platform | What to register |
432
+ | -------- | ------------------------------------------------------------------------------------------------------- |
433
+ | Web | An HTTPS return URL on a domain you control (e.g. `https://app.example.com/plaid/oauth-return`) |
434
+ | iOS | The universal link URL you receive the redirect on — custom URL schemes (`yourapp://`) are not accepted |
435
+ | Android | Your app's package name (e.g. `com.example.app`) |
436
+
437
+ 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.
438
+
439
+ ##### Fall back to manual entry
440
+
441
+ 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:
442
+
443
+ ```typescript
444
+ import { BankAccountType, BankAccountSubType } from '@spritz-finance/api-client'
445
+
446
+ try {
447
+ const { linkToken } = await client.bankAccount.createLinkToken()
448
+ // hand linkToken to Plaid Link on the client, then completeLinking(...)
449
+ } catch {
450
+ // Plaid unavailable — collect account + routing numbers and create directly
451
+ const bankAccount = await client.bankAccount.create(BankAccountType.USBankAccount, {
452
+ accountNumber: '123456789',
453
+ routingNumber: '987654321',
454
+ subType: BankAccountSubType.Checking,
455
+ ownedByUser: true,
456
+ })
457
+ }
458
+ ```
459
+
460
+ A manually added account is immediately usable for **off-ramp**. **ACH on-ramp** additionally requires a funding source, and the Plaid link flow is what provisions it — so prefer Plaid Link whenever ACH onramp is in scope, and use manual entry as the off-ramp fallback.
461
+
334
462
  ### Debit Cards
335
463
 
336
464
  Supported networks: **Visa** and **Mastercard**.
@@ -692,6 +820,33 @@ const limits = await client.payment.getPaymentLimits(account.id)
692
820
  }
693
821
  ```
694
822
 
823
+ ### Refunding a Payment
824
+
825
+ A **failed** off-ramp payment can be refunded, either by returning the funds to the user's Spritz balance or by reissuing the payout to a bank account.
826
+
827
+ ```typescript
828
+ // Reissue the payout to a different bank account
829
+ await client.offramp.refund(offRampId, {
830
+ method: 'account',
831
+ accountId: '6a5f75585a936eb477232f05',
832
+ })
833
+
834
+ // Reissue to the off-ramp's original destination account
835
+ await client.offramp.refund(offRampId, { method: 'account' })
836
+
837
+ // Return the funds to the user's Spritz balance
838
+ await client.offramp.refund(offRampId, { method: 'credit' })
839
+ ```
840
+
841
+ | Field | Type | Description |
842
+ | ----------- | ----------------------- | ---------------------------------------------------------------------------------------- |
843
+ | `method` | `'account' \| 'credit'` | `account` reissues the payout to a bank account; `credit` returns funds to the balance |
844
+ | `accountId` | `string` (optional) | Only with `method: 'account'`. Omit to reuse the off-ramp's original destination account |
845
+
846
+ Only failed off-ramps settled through Modern Treasury or Checkbook are refundable — anything else is rejected. The response is the updated off-ramp record, with `status` moving to `refunded`.
847
+
848
+ > **Retries:** the platform recommends an `Idempotency-Key` header so a retried request replays the original response rather than returning a stale "not refundable" error. The client does not currently send one, so if a refund request times out, re-fetch the off-ramp and check its `status` before issuing another.
849
+
695
850
  ## On-ramp
696
851
 
697
852
  The on-ramp feature allows users to purchase crypto stablecoins via ACH or wire transfer.