@sphoq/payments 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { SphoqPayments } from "./client.js";
 export { SphoqApiError } from "./types.js";
-export type { SphoqPaymentsOptions, ChargeItem, CreateChargeOptions, Charge, GetChargeOptions, CancelChargeOptions, CancelChargeResult, WebhookPayload, VerifyWebhookOptions, } from "./types.js";
+export type { SphoqPaymentsOptions, ChargeItem, ChargeFee, CreateChargeOptions, Charge, GetChargeOptions, CancelChargeOptions, CancelChargeResult, WebhookPayload, VerifyWebhookOptions, } from "./types.js";

package/dist/types.d.ts

@@ -171,6 +171,35 @@ export interface CreateChargeOptions {
      */
     metadata?: Record<string, unknown>;
 }
+/**
+ * A fee applied to a charge.
+ *
+ * Fees are calculated at charge creation and included in every charge response
+ * and webhook payload.
+ *
+ * @example
+ * ```ts
+ * const charge = await sphoq.charges.create({ amount: 100, description: "Test" });
+ * for (const fee of charge.fees) {
+ *   console.log(`${fee.type} (${fee.provider}): ${fee.rate}% = R$ ${fee.amount}`);
+ * }
+ * console.log(`Net amount: R$ ${charge.netAmount}`);
+ * ```
+ */
+export interface ChargeFee {
+    /**
+     * The category of this fee.
+     * - `"platform"` — Sphoq platform fee
+     * - `"processor"` — Payment processor fee (e.g., EfiBank PIX)
+     */
+    type: "platform" | "processor";
+    /** Who charges this fee (e.g., `"sphoq"`, `"efibank"`). */
+    provider: string;
+    /** Fee percentage (e.g., `5` for 5%). */
+    rate: number;
+    /** Calculated fee amount in BRL. */
+    amount: number;
+}
 /**
  * A PIX charge object returned by the Sphoq API.
  *
@@ -252,6 +281,21 @@ export interface Charge {
      * Returned as-is from the API.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Fees applied to this charge.
+     * Calculated at creation time based on the store's tax settings.
+     */
+    fees: ChargeFee[];
+    /**
+     * Sum of all fee amounts in BRL.
+     * Equal to `fees.reduce((sum, f) => sum + f.amount, 0)`.
+     */
+    totalFees: number;
+    /**
+     * Amount after fees in BRL.
+     * Equal to `amount - totalFees`.
+     */
+    netAmount: number;
     /**
      * The environment this charge was created in.
      * - `"production"` — Real PIX charge.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sphoq/payments",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Sphoq Payments SDK — integrate PIX payment processing into your app",
   "type": "module",
   "main": "dist/index.js",