@spritz-finance/api-client 0.10.0 → 0.12.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 +58 -0
- package/dist/spritz-api-client.cjs +14 -14
- package/dist/spritz-api-client.d.ts +25594 -10036
- package/dist/spritz-api-client.mjs +14 -14
- package/package.json +1 -1
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)
|
|
@@ -160,6 +161,21 @@ const { apiKey, userId, email } = await client.user.authorizeApiKeyWithOTP({
|
|
|
160
161
|
const userData = await client.user.getCurrentUser()
|
|
161
162
|
```
|
|
162
163
|
|
|
164
|
+
#### REST User Profile
|
|
165
|
+
|
|
166
|
+
`user.getMe()` returns the user profile from the REST API (`GET /v1/users/me`) as-is, typed as `UserProfile`. It includes the user's `verification` state and `capabilities`:
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
const me = await client.user.getMe()
|
|
170
|
+
|
|
171
|
+
me.verification.status // 'not_started' | 'verified' | 'failed' | 'disabled' | 'retry'
|
|
172
|
+
me.verification.country // e.g. 'US', or null
|
|
173
|
+
me.verification.requirement // outstanding requirement, if any ({ type, status, actionUrl?, retryable? })
|
|
174
|
+
me.capabilities // [{ product, method?, name, status, nextRequirement?, requirements }]
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
> **Note:** `getMe()` does not yet replace `getCurrentUser()`. The REST profile has no verification failure reason, reports verifications under review as `not_started`, and there is no REST equivalent of `retryFailedVerification()`.
|
|
178
|
+
|
|
163
179
|
### Identity Verification
|
|
164
180
|
|
|
165
181
|
All users must complete identity verification before using the platform. New users start with a verification status of `NotStarted`.
|
|
@@ -178,6 +194,21 @@ const verificationParams = await client.user.getVerificationParams()
|
|
|
178
194
|
// - verificationUrlExpiresAt: Expiration timestamp for the verification URL
|
|
179
195
|
```
|
|
180
196
|
|
|
197
|
+
#### Creating a Verification Session (REST)
|
|
198
|
+
|
|
199
|
+
`verification.createSession()` creates or resumes the user's verification session via the REST API (`POST /v1/users/me/verification-sessions/`) and returns the response as-is, typed as `VerificationSession`:
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
const { sessionId, provider, sessionToken, verificationUrl, verificationUrlExpiresAt } =
|
|
203
|
+
await client.verification.createSession()
|
|
204
|
+
|
|
205
|
+
// provider: 'persona' | 'plaid'
|
|
206
|
+
// sessionToken: embedded-flow token (Persona session token or Plaid Link token), or null
|
|
207
|
+
// verificationUrl: provider-hosted URL, or null
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Tokens and URLs may expire, so create the session just in time rather than caching it. The call throws a `ConflictError` (409) when verification is under review or unavailable, and an `InternalServerError` (503, with `retryAfter` in the error body) when the provider is temporarily unavailable.
|
|
211
|
+
|
|
181
212
|
#### Option 1: Verification URL
|
|
182
213
|
|
|
183
214
|
The simplest integration — redirect the user to the hosted verification flow:
|
|
@@ -819,6 +850,33 @@ const limits = await client.payment.getPaymentLimits(account.id)
|
|
|
819
850
|
}
|
|
820
851
|
```
|
|
821
852
|
|
|
853
|
+
### Refunding a Payment
|
|
854
|
+
|
|
855
|
+
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.
|
|
856
|
+
|
|
857
|
+
```typescript
|
|
858
|
+
// Reissue the payout to a different bank account
|
|
859
|
+
await client.offramp.refund(offRampId, {
|
|
860
|
+
method: 'account',
|
|
861
|
+
accountId: '6a5f75585a936eb477232f05',
|
|
862
|
+
})
|
|
863
|
+
|
|
864
|
+
// Reissue to the off-ramp's original destination account
|
|
865
|
+
await client.offramp.refund(offRampId, { method: 'account' })
|
|
866
|
+
|
|
867
|
+
// Return the funds to the user's Spritz balance
|
|
868
|
+
await client.offramp.refund(offRampId, { method: 'credit' })
|
|
869
|
+
```
|
|
870
|
+
|
|
871
|
+
| Field | Type | Description |
|
|
872
|
+
| ----------- | ----------------------- | ---------------------------------------------------------------------------------------- |
|
|
873
|
+
| `method` | `'account' \| 'credit'` | `account` reissues the payout to a bank account; `credit` returns funds to the balance |
|
|
874
|
+
| `accountId` | `string` (optional) | Only with `method: 'account'`. Omit to reuse the off-ramp's original destination account |
|
|
875
|
+
|
|
876
|
+
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`.
|
|
877
|
+
|
|
878
|
+
> **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.
|
|
879
|
+
|
|
822
880
|
## On-ramp
|
|
823
881
|
|
|
824
882
|
The on-ramp feature allows users to purchase crypto stablecoins via ACH or wire transfer.
|