@spritz-finance/api-client 0.4.6 → 0.4.8

package/README.md

@@ -29,6 +29,7 @@ import {
   PaymentNetwork,
   BankAccountType,
   BankAccountSubType,
+  DebitCardNetwork,
 } from '@spritz-finance/api-client'
 
 // Initialize the client with your integration key
@@ -93,6 +94,7 @@ const transactionData = await client.paymentRequest.getWeb3PaymentParams({
   - [Account Types](#account-types)
   - [Commonalities & Differences](#commonalities---differences)
   - [Bank Accounts](#bank-accounts)
+  - [Debit Cards](#debit-cards)
   - [Bills](#bills)
   - [Virtual Card](#virtual-card)
   - [Address Book](#address-book)
@@ -305,11 +307,12 @@ Spritz emphasizes its capabilities in account handling and payment processing.
 
 ### Account Types
 
-Spritz supports three distinct types of accounts:
+Spritz supports four distinct types of accounts:
 
 1. **Bank Account**
-2. **Bill**
-3. **Virtual Card**
+2. **Debit Card**
+3. **Bill**
+4. **Virtual Card**
 
 Though each account type possesses its unique creation process and specific properties, it's important to understand that all of them are uniformly termed as an "account" within the Spritz platform.
 
@@ -427,6 +430,67 @@ const bankAccounts = await client.bankAccount.create(BankAccountType.CABankAccou
 })
 ```
 
+### Debit Cards
+
+Spritz provides support for adding debit cards as payment accounts, allowing users to make payments directly to their debit cards.
+
+#### List user debit cards
+
+To retrieve all debit cards linked to a user:
+
+```typescript
+const debitCards = await client.debitCard.list()
+```
+
+The `debitCard.list()` method returns an array of user-linked debit cards:
+
+```typescript
+const debitCards = [{
+  id: "62d17d3b377dab6c1342136e",
+  type: "DebitCard",
+  name: "My Visa Debit",
+  userId: "62d17d3b377dab6c1342136e",
+  country: "US",
+  currency: "USD",
+  payable: true,
+  debitCardNetwork: "Visa",
+  expirationDate: "12/25",
+  cardNumber: "4111111111111111",
+  mask: "1111",
+  createdAt: "2023-01-01T00:00:00Z",
+  paymentCount: 5,
+  externalId: "ext-123"
+}]
+```
+
+#### Add a debit card
+
+To add a new debit card for a user:
+
+```typescript
+import { DebitCardNetwork } from '@spritz-finance/api-client'
+
+const debitCard = await client.debitCard.create({
+  name: 'My Visa Debit',
+  cardNumber: '4111111111111111',
+  expirationDate: '12/25',
+})
+```
+
+The input structure for adding a debit card is:
+
+```typescript
+export interface DebitCardInput {
+  name?: string | null      // Optional name for the card
+  cardNumber: string        // Full card number (13-19 digits)
+  expirationDate: string    // Expiration date in MM/YY format
+}
+```
+
+Supported debit card networks:
+- `Visa`
+- `Mastercard`
+
 ### Bills
 
 Spritz provides robust support for bills, allowing seamless management and interaction with user billing accounts. Below is a guide to the methods and functionalities specifically designed for handling bills within Spritz.
@@ -589,6 +653,14 @@ You can conveniently change the display name of a bank account using the followi
 const updateAccount = await client.bankAccount.rename('62d17d3b377dab6c1342136e', 'My new account')
 ```
 
+#### Rename a debit card
+
+You can change the display name of a debit card:
+
+```typescript
+const updatedCard = await client.debitCard.rename('62d17d3b377dab6c1342136e', 'My primary debit card')
+```
+
 #### Rename a bill
 
 You can conveniently change the display name of a bill using the following endpoint. The first argument specifies the ID of the bill, while the second argument represents the desired new name for the account.
@@ -607,6 +679,14 @@ To remove a bank account from a user's account, you can use the following endpoi
 await client.bankAccount.delete('62d17d3b377dab6c1342136e')
 ```
 
+#### Delete a debit card
+
+To remove a debit card from a user's account:
+
+```typescript
+await client.debitCard.delete('62d17d3b377dab6c1342136e')
+```
+
 #### Delete a bill
 
 To remove a bill from a user's account, you can use the following endpoint. You only need to specify the ID of the bill that you want to delete as an argument.
@@ -894,6 +974,10 @@ Spritz currently supports the following webhook events:
 - `payment.completed`: Triggered when a payment is successfully completed.
 - `payment.refunded`: Triggered when a payment is refunded.
 
+#### Verification Events
+
+- `verification.status.updated`: Triggered when a user's verification status changes.
+
 These events allow you to respond to changes in the account and payments for a user.
 
 ### Setting up webhooks
@@ -919,3 +1003,23 @@ Upon receiving a webhook, your server will get a payload with the following stru
   "eventName": "name-of-the-event-here"
 }
 ```
+
+### Webhook security and signing
+
+Each webhook request is signed using an HMAC SHA256 signature, based on the exact JSON payload sent in the body. This signature is included in the Signature HTTP header of the request.
+
+The secret key used to compute the signature is the webhook secret you set when configuring your webhook integration. If you have not set a webhook secret, there will be no Signature header in the webhook request.
+
+You can verify webhook authenticity by computing the HMAC signature and comparing it to the Signature header included in the webhook request.
+
+#### Example: Verifying a webhook signature (Node.js)
+
+```typescript
+import { createHmac } from "crypto";
+
+const signature = createHmac("sha256", <YOUR_WEBHOOK_SECRET>)
+  .update(<REQUEST_BODY_AS_JSON_STRING>) // JSON.stringify(payload)
+  .digest("hex");
+```
+
+Ensure that the computed signature matches the Signature header received in the webhook request before processing the payload.