@sphoq/payments 0.3.0 → 0.5.0

package/dist/client.d.ts

@@ -2,7 +2,7 @@ import type { SphoqPaymentsOptions, CreateChargeOptions, Charge, GetChargeOption
 /**
  * Sphoq Payments SDK client.
  *
- * Provides methods for creating and managing PIX charges, and verifying webhook signatures.
+ * Provides methods for creating and managing charges, and verifying webhook signatures.
  * Zero dependencies — uses native `fetch` and Web Crypto API.
  *
  * @example Basic setup
@@ -15,20 +15,20 @@ import type { SphoqPaymentsOptions, CreateChargeOptions, Charge, GetChargeOption
  * });
  * ```
  *
- * @example Create a PIX charge and display QR code
+ * @example Create a charge and display checkout image
  * ```ts
  * const charge = await sphoq.charges.create({
  *   amount: 49.90,
  *   description: "Premium Plan",
  *   externalId: "order_123",
- *   customer: { name: "João Silva", cpf: "12345678900" },
+ *   customer: { name: "João Silva", taxId: "12345678900" },
  * });
  *
- * // Show QR code to user (base64 PNG)
- * document.getElementById("qr").src = `data:image/png;base64,${charge.qrCode}`;
+ * // Show checkout image to user (base64 PNG)
+ * document.getElementById("qr").src = `data:image/png;base64,${charge.checkoutImage}`;
  *
- * // Or show the copy-paste PIX string
- * console.log(charge.pixCopiaECola);
+ * // Or show the copy-paste payment code
+ * console.log(charge.paymentCode);
  * ```
  *
  * @example Convex integration — reactive payment status
@@ -72,7 +72,7 @@ export declare class SphoqPayments {
     private readonly apiKey;
     private readonly baseUrl;
     /**
-     * Client for creating, querying, and cancelling PIX charges.
+     * Client for creating, querying, and cancelling charges.
      *
      * @example
      * ```ts
@@ -155,14 +155,14 @@ declare class ChargesClient {
     private readonly baseUrl;
     constructor(apiKey: string, baseUrl: string);
     /**
-     * Create a new PIX charge.
+     * Create a new charge.
      *
-     * Generates a PIX QR code and copy-paste string that the customer can use to pay.
+     * Generates a payment code and checkout image that the customer can use to pay.
      * The charge starts with `status: "pending"` and transitions to `"paid"` when
      * the customer completes the payment.
      *
      * @param options - Charge details (amount, description, customer info, etc.).
-     * @returns The created charge with QR code data.
+     * @returns The created charge with payment data.
      * @throws {@link SphoqApiError} if the API returns an error (invalid params, rate limit, etc.).
      *
      * @example Simple charge
@@ -171,7 +171,7 @@ declare class ChargesClient {
      *   amount: 29.90,
      *   description: "Monthly subscription",
      * });
-     * console.log(charge.pixCopiaECola); // PIX copy-paste string
+     * console.log(charge.paymentCode); // Copy-paste payment string
      * ```
      *
      * @example Full options
@@ -183,7 +183,7 @@ declare class ChargesClient {
      *   customer: {
      *     name: "Maria Santos",
      *     email: "maria@example.com",
-     *     cpf: "12345678900",
+     *     taxId: "12345678900",
      *   },
      *   expirationSeconds: 1800, // 30 minutes
      *   metadata: { planId: "annual", coupon: "SAVE20" },
@@ -213,10 +213,10 @@ declare class ChargesClient {
      */
     get(options: GetChargeOptions): Promise<Charge>;
     /**
-     * Cancel a pending PIX charge.
+     * Cancel a pending charge.
      *
      * Only charges with `status: "pending"` can be cancelled.
-     * After cancellation, the QR code is invalidated and the charge
+     * After cancellation, the payment code is invalidated and the charge
      * cannot be paid.
      *
      * @param options - The charge ID to cancel.

package/dist/client.js

@@ -3,7 +3,7 @@ const DEFAULT_BASE_URL = "https://your-convex-deployment.convex.site";
 /**
  * Sphoq Payments SDK client.
  *
- * Provides methods for creating and managing PIX charges, and verifying webhook signatures.
+ * Provides methods for creating and managing charges, and verifying webhook signatures.
  * Zero dependencies — uses native `fetch` and Web Crypto API.
  *
  * @example Basic setup
@@ -16,20 +16,20 @@ const DEFAULT_BASE_URL = "https://your-convex-deployment.convex.site";
  * });
  * ```
  *
- * @example Create a PIX charge and display QR code
+ * @example Create a charge and display checkout image
  * ```ts
  * const charge = await sphoq.charges.create({
  *   amount: 49.90,
  *   description: "Premium Plan",
  *   externalId: "order_123",
- *   customer: { name: "João Silva", cpf: "12345678900" },
+ *   customer: { name: "João Silva", taxId: "12345678900" },
  * });
  *
- * // Show QR code to user (base64 PNG)
- * document.getElementById("qr").src = `data:image/png;base64,${charge.qrCode}`;
+ * // Show checkout image to user (base64 PNG)
+ * document.getElementById("qr").src = `data:image/png;base64,${charge.checkoutImage}`;
  *
- * // Or show the copy-paste PIX string
- * console.log(charge.pixCopiaECola);
+ * // Or show the copy-paste payment code
+ * console.log(charge.paymentCode);
  * ```
  *
  * @example Convex integration — reactive payment status
@@ -73,7 +73,7 @@ export class SphoqPayments {
     apiKey;
     baseUrl;
     /**
-     * Client for creating, querying, and cancelling PIX charges.
+     * Client for creating, querying, and cancelling charges.
      *
      * @example
      * ```ts
@@ -182,14 +182,14 @@ class ChargesClient {
         this.baseUrl = baseUrl;
     }
     /**
-     * Create a new PIX charge.
+     * Create a new charge.
      *
-     * Generates a PIX QR code and copy-paste string that the customer can use to pay.
+     * Generates a payment code and checkout image that the customer can use to pay.
      * The charge starts with `status: "pending"` and transitions to `"paid"` when
      * the customer completes the payment.
      *
      * @param options - Charge details (amount, description, customer info, etc.).
-     * @returns The created charge with QR code data.
+     * @returns The created charge with payment data.
      * @throws {@link SphoqApiError} if the API returns an error (invalid params, rate limit, etc.).
      *
      * @example Simple charge
@@ -198,7 +198,7 @@ class ChargesClient {
      *   amount: 29.90,
      *   description: "Monthly subscription",
      * });
-     * console.log(charge.pixCopiaECola); // PIX copy-paste string
+     * console.log(charge.paymentCode); // Copy-paste payment string
      * ```
      *
      * @example Full options
@@ -210,7 +210,7 @@ class ChargesClient {
      *   customer: {
      *     name: "Maria Santos",
      *     email: "maria@example.com",
-     *     cpf: "12345678900",
+     *     taxId: "12345678900",
      *   },
      *   expirationSeconds: 1800, // 30 minutes
      *   metadata: { planId: "annual", coupon: "SAVE20" },
@@ -266,10 +266,10 @@ class ChargesClient {
         return this.request("/v1/charges/get", body);
     }
     /**
-     * Cancel a pending PIX charge.
+     * Cancel a pending charge.
      *
      * Only charges with `status: "pending"` can be cancelled.
-     * After cancellation, the QR code is invalidated and the charge
+     * After cancellation, the payment code is invalidated and the charge
      * cannot be paid.
      *
      * @param options - The charge ID to cancel.

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

@@ -79,7 +79,7 @@ export interface ChargeItem {
     imageUrl?: string;
 }
 /**
- * Options for creating a new PIX charge.
+ * Options for creating a new charge.
  *
  * @example Simple charge
  * ```ts
@@ -90,7 +90,7 @@ export interface ChargeItem {
  *   customer: {
  *     name: "João Silva",
  *     email: "joao@example.com",
- *     cpf: "12345678900",
+ *     taxId: "12345678900",
  *   },
  *   expirationSeconds: 3600, // 1 hour
  *   metadata: { planId: "premium", userId: "usr_abc" },
@@ -111,8 +111,8 @@ export interface ChargeItem {
  */
 export interface CreateChargeOptions {
     /**
-     * Charge amount in BRL (Brazilian Real).
-     * Must be greater than 0. Use decimal notation (e.g., `29.90` for R$ 29,90).
+     * Charge amount. Must be greater than 0.
+     * Use decimal notation (e.g., `29.90`).
      */
     amount: number;
     /** Human-readable description shown to the customer. */
@@ -131,12 +131,19 @@ export interface CreateChargeOptions {
         name?: string;
         /** Customer's email address. */
         email?: string;
-        /** Customer's CPF (Brazilian tax ID, 11 digits, no formatting). */
-        cpf?: string;
+        /** Customer's tax ID (e.g., CPF in Brazil, 11 digits, no formatting). */
+        taxId?: string;
+        /**
+         * Your own identifier for this customer.
+         * Useful for mapping charges to users in your system.
+         *
+         * @example "usr_abc123"
+         */
+        externalId?: string;
     };
     /**
-     * Time in seconds until the PIX charge expires.
-     * After expiration, the QR code can no longer be paid.
+     * Time in seconds until the charge expires.
+     * After expiration, the payment code can no longer be used.
      *
      * @default 3600 (1 hour)
      */
@@ -145,7 +152,7 @@ export interface CreateChargeOptions {
      * Line items included in this charge.
      *
      * When provided, the sum of `quantity * unitPrice` across all items **must**
-     * exactly equal the `amount` field (within R$ 0.01 tolerance). The API rejects
+     * exactly equal the `amount` field (within 0.01 tolerance). The API rejects
      * the request if the totals don't match.
      *
      * Items are stored with the charge and included in webhook payloads,
@@ -172,7 +179,36 @@ export interface CreateChargeOptions {
     metadata?: Record<string, unknown>;
 }
 /**
- * A PIX charge object returned by the Sphoq API.
+ * 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 charge object returned by the Sphoq API.
  *
  * @example
  * ```ts
@@ -181,16 +217,16 @@ export interface CreateChargeOptions {
  *   description: "Monthly subscription",
  * });
  *
- * // Display QR code to user
- * console.log(charge.qrCode);        // Base64-encoded QR code image
- * console.log(charge.pixCopiaECola); // PIX copy-paste string
+ * // Display checkout image to user
+ * console.log(charge.checkoutImage); // Base64-encoded checkout image (QR code, barcode, etc.)
+ * console.log(charge.paymentCode);   // Copy-paste payment string
  * console.log(charge.status);        // "pending"
  *
  * // After payment, query the charge
  * const paid = await sphoq.charges.get({ id: charge.id });
- * console.log(paid.status);      // "paid"
- * console.log(paid.paidAt);      // Unix timestamp in ms
- * console.log(paid.endToEndId);  // Central Bank end-to-end ID
+ * console.log(paid.status);            // "paid"
+ * console.log(paid.paidAt);            // Unix timestamp in ms
+ * console.log(paid.providerPaymentId); // Provider's payment confirmation ID
  * ```
  */
 export interface Charge {
@@ -198,50 +234,54 @@ export interface Charge {
     id: string;
     /** Your external ID, if provided when creating the charge. */
     externalId?: string;
-    /** Charge amount in BRL. */
+    /** Charge amount. */
     amount: number;
-    /**
-     * Currency code. Always `"BRL"` (Brazilian Real).
-     */
+    /** Currency code (e.g., `"BRL"`, `"USD"`). */
     currency: string;
     /** Human-readable description of the charge. */
     description: string;
     /**
      * Current status of the charge.
      *
-     * - `"pending"` — Awaiting payment. QR code is active.
-     * - `"paid"` — Payment confirmed by the bank.
-     * - `"expired"` — QR code expired before payment.
+     * - `"pending"` — Awaiting payment.
+     * - `"paid"` — Payment confirmed by the provider.
+     * - `"expired"` — Charge expired before payment.
      * - `"cancelled"` — Charge was cancelled via the API.
      */
     status: "pending" | "paid" | "expired" | "cancelled";
-    /** PIX transaction ID (txid). Unique identifier in the Brazilian PIX system. */
-    txid: string;
+    /** Provider's charge identifier (e.g., PIX txid, Stripe charge_id). */
+    providerChargeId: string;
+    /** Payment method used (e.g., `"pix"`). */
+    paymentMethod: string;
+    /** Payment provider (e.g., `"efibank"`). */
+    provider: string;
     /**
-     * PIX "copia e cola" (copy-paste) string.
-     * The customer can paste this into their banking app to pay.
+     * Copy-paste payment string for the customer
+     * (e.g., PIX copia-e-cola, Boleto barcode digits).
      */
-    pixCopiaECola?: string;
+    paymentCode?: string;
     /**
-     * Base64-encoded PNG image of the PIX QR code.
-     * Display this to the customer for scanning.
+     * Base64-encoded checkout image (e.g., QR code, barcode).
+     * Display this to the customer.
      */
-    qrCode?: string;
+    checkoutImage?: string;
     /** Customer name, if provided. */
     customerName?: string;
     /** Customer email, if provided. */
     customerEmail?: string;
+    /** Your own customer identifier, if provided. */
+    customerExternalId?: string;
     /**
      * Unix timestamp (milliseconds) when the payment was confirmed.
      * Only present when `status` is `"paid"`.
      */
     paidAt?: number;
     /**
-     * Central Bank end-to-end ID for the PIX transaction.
+     * Provider's payment confirmation ID.
      * Only present when `status` is `"paid"`.
-     * Can be used for reconciliation with bank statements.
+     * Can be used for reconciliation with bank/provider statements.
      */
-    endToEndId?: string;
+    providerPaymentId?: string;
     /**
      * Line items included in the charge, if provided at creation.
      * Returned as-is from the API. Useful for order fulfillment.
@@ -252,15 +292,30 @@ 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.
+     * Equal to `fees.reduce((sum, f) => sum + f.amount, 0)`.
+     */
+    totalFees: number;
+    /**
+     * Amount after fees.
+     * Equal to `amount - totalFees`.
+     */
+    netAmount: number;
     /**
      * The environment this charge was created in.
-     * - `"production"` — Real PIX charge.
-     * - `"development"` — EfiBank sandbox charge (no real money).
+     * - `"production"` — Real charge.
+     * - `"development"` — Sandbox charge (no real money).
      */
     environment?: "production" | "development";
     /** Unix timestamp (milliseconds) when the charge was created. */
     createdAt: number;
-    /** Unix timestamp (milliseconds) when the PIX QR code expires. */
+    /** Unix timestamp (milliseconds) when the charge expires. */
     expiresAt: number;
 }
 /**
@@ -347,8 +402,8 @@ export interface WebhookPayload {
     /**
      * The event type.
      *
-     * - `"charge.paid"` — Customer completed the PIX payment.
-     * - `"charge.expired"` — QR code expired before payment.
+     * - `"charge.paid"` — Customer completed the payment.
+     * - `"charge.expired"` — Charge expired before payment.
      * - `"charge.cancelled"` — Charge was cancelled via the API.
      */
     type: "charge.paid" | "charge.expired" | "charge.cancelled";

package/package.json

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