@timbro/payments 0.1.0-next.0

package/README.md

@@ -0,0 +1,178 @@
+# `@timbro/payments`
+
+Node 24 ESM SDK for merchant Payments and their payment-linked fiscal documents.
+
+Each Payment create request supplies one immutable `source` coordinate and one tagged `sale` snapshot. `source.id` and `source.version` remain stable across credential rotation and retries; `idempotencyKey` remains the HTTP command retry key.
+
+Payment reads preserve that source, the canonical sale, amount, voluntary tip,
+collected `totalAmount`, stable capture allocations with sanitized payment
+method summaries, and the fiscal recipient projection needed by an ERP.
+
+Use `amount_only` when the adapter has only a payable amount. This variant cannot request fiscal issuance:
+
+```ts
+import { createTimbroPayments } from "@timbro/payments";
+
+const timbro = createTimbroPayments({ secretKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY });
+const payment = await timbro.payments.create({
+  idempotencyKey: "create-order-123",
+  source: { id: "odoo:pos.order:123", version: "7" },
+  sale: {
+    kind: "amount_only",
+    reference: "order-123",
+    description: "Consumo en el comercio",
+    amount: { currency: "DOP", value: "1250.00" },
+  },
+  invoicing: null,
+});
+```
+
+Use `itemized` when the adapter has commercial lines. Each line carries its fiscal description and exact decimal price; optional `product` data is presentation metadata:
+
+```ts
+await timbro.payments.create({
+  idempotencyKey: "create-coffee-126",
+  source: { id: "odoo:pos.order:126", version: "3" },
+  sale: { kind: "itemized", reference: "coffee-126", currency: "DOP",
+    items: [{
+      id: "coffee", description: "Café",
+      product: { id: "product-7", sku: "CAFE-7", imageUrl: "https://merchant.example/cafe.png" },
+      quantity: "1", unit: "unit", unitPrice: "118.00", kind: "good",
+      tax: { kind: "itbis_18", included: true },
+    }],
+    totals: { net: "100.00", tax: "18.00", legalTip: "0.00", total: "118.00" } },
+  invoicing: null,
+});
+
+`sale.totals.total` is the commercial payable amount. A `non_billable` line may
+be collected without entering the fiscal amount. The returned breakdown names
+the invariant explicitly: `payableTotalMinorUnits` equals
+`fiscalDeclaredTotalMinorUnits + nonBillableMinorUnits`. Legal tip is included
+once in the fiscal declared total; voluntary tip is added only to collected
+`totalAmount`.
+
+Refunds are durable full or partial resources with idempotent create, retrieve,
+and list operations. Provider outcome and fiscal note coordination are separate.
+The Gateway reserves captured allocation balances before provider work begins:
+
+```ts
+const refund = await timbro.refunds.create({
+  idempotencyKey: "refund-order-124-1",
+  paymentId: payment.id,
+  source: { id: "odoo:pos.order:124:refund:1", version: "1" },
+  reference: "order-124-return-1",
+  amount: { currency: "DOP", minorUnits: 12500 },
+  // Optional for split Payments; omit to reserve across every captured allocation.
+  allocationIds: payment.capturedPayment?.allocations.map(({ id }) => id),
+});
+```
+
+The Refund response keeps `allocationIds` and exact `allocationAmounts` so an
+ERP can reconcile one or more split-payer allocations without exceeding any
+captured minor-unit balance. The Refund row owns the durable provider binding,
+submission fence, and recovery schedule. Test-mode CardNet full refunds use the
+Ztrans submission and same-key inquiry path. Partial, split, live-mode, Azul,
+and sandbox paths remain `operator_required` before remote money movement.
+
+An authenticated ERP can attach Timbro's accepted E34 fiscal credit note after
+the refund request is recorded. This advances only `fiscalCoordination`; it does
+not claim that provider money movement succeeded:
+
+```ts
+await timbro.refunds.attachFiscalCoordination({
+  refundId: refund.id,
+  timbroFiscalDocumentId: "timbro-operation-01h123456789abcdefgh",
+  eNcf: "E3400000001",
+  acceptedAt: "2026-09-11T00:00:00.000Z",
+  idempotencyKey: "refund-fiscal-note-124-1",
+});
+```
+
+Optional `merchantAccountId` pins an authorized account for the Payment.
+`merchantAccounts.retrieveCheckoutCapabilities(id)` discovers its supported
+Checkout features. Preferences can restrict available methods, but cannot grant
+capabilities or bypass merchant policy. Empty `wallets` explicitly disables both
+wallets; omitted preferences retain the merchant's applicable defaults.
+`testOptions.threeDs` selects authentication for a test Payment only and cannot
+disable production authentication. CardNet requires its supported 3DS flow.
+
+Cancel an unpaid Payment from the merchant backend with a stable command key.
+The operation invalidates prepared Checkout submissions immediately. Split
+authorizations enter provider release and the returned Payment remains
+`releasing` until every void is confirmed; retrieve the Payment to observe the
+authoritative terminal `canceled` state. The gateway emits one ordered
+`payment.canceled` webhook only after that terminal state is committed. A same-key `202` cancellation replay is
+intentionally stale while release is pending; polling the Payment is the
+correctness authority. A submitted or ambiguous unsplit attempt returns a
+conflict and stays under correlation reconciliation. Captured
+money is outside cancellation and requires a separate refund policy.
+
+```ts
+const canceled = await timbro.payments.cancel({
+  paymentId: payment.id,
+  idempotencyKey: "cancel-order-123",
+});
+```
+
+`merchantCheckoutPolicy.retrieve()` reads tenant- and mode-scoped defaults and
+constraints. Administrators update them through the authenticated administrative
+`PUT /v1/merchant_checkout_policy` operation with the expected revision; ordinary
+merchant secret keys cannot update policy. Accepted configuration is retained with the Payment;
+later policy edits do not reroute existing Payments. Account readiness can still
+withdraw permission to start a provider effect.
+
+Use `mode: "required"` when Checkout must remain open until issuance. Required and deferred invoicing require the merchant's real invoice and order references. `externally_coordinated` records the payer recipient choice and lets the authenticated ERP supply those identifiers later.
+
+```ts
+await timbro.payments.create({
+  idempotencyKey: "create-required-order-124",
+  source: { id: "odoo:pos.order:124", version: "9" },
+  sale: { kind: "itemized", reference: "order-124", currency: "DOP", items: [{
+    id: "meal", description: "Meal", quantity: "1", unit: "unit", unitPrice: "1250.00", kind: "good",
+    tax: { kind: "itbis_18", included: true },
+  }], totals: { net: "1059.32", tax: "190.68", legalTip: "0.00", total: "1250.00" } },
+  invoicing: { mode: "required", type: "consumer", merchantInvoiceNumber: "INV-124", merchantOrderNumber: "124" },
+});
+```
+
+Use `mode: "deferred"` when Checkout owns issuance and retries, but the paid receipt may be shown before issuance finishes. The same complete immutable sale and invoicing intent is captured before provider I/O.
+
+Refunds use one resource for the provider money movement and the separate fiscal-note coordination state. An ERP or POS supplies its immutable source coordinate and exact captured allocation attribution:
+
+```ts
+const refund = await timbro.refunds.create({
+  paymentId: payment.id,
+  source: { id: "odoo:pos.order:124:return:1", version: "1" },
+  reference: "RETURN-124-1",
+  amount: { currency: "DOP", minorUnits: 50_000 },
+  allocationIds: [payment.capturedPayment!.allocations[0]!.id],
+  idempotencyKey: "refund-order-124-return-1",
+});
+
+if (refund.providerOutcome.status === "succeeded") {
+  await timbro.refunds.attachFiscalCoordination({
+    refundId: refund.id,
+    timbroFiscalDocumentId: "fiscal_document_123",
+    eNcf: "E340000000001",
+    acceptedAt: new Date().toISOString(),
+    idempotencyKey: "refund-order-124-return-1-e34",
+  });
+}
+```
+
+For a full, unsplit Payment, `timbro.payments.refund({ paymentId, idempotencyKey })` is a bodyless convenience command that returns the same Refund resource. `processing` means provider submission can still begin, `verifying` means an ambiguous submission is being checked without resubmission, and `operator_required` means staff must complete or reconcile the money movement. Provider outcome and fiscal E34 acceptance stay independent.
+
+CardNet Ztrans full refunds are implemented for test mode with deterministic recovery tests. Current laboratory evidence does not prove CardNet's refund-inquiry semantics or production readiness. Partial, split, live-mode, Azul, and sandbox refund paths reserve the requested captured balance and return `operator_required` before remote provider I/O.
+
+Before collecting the rest of a merchant's onboarding details, verify its RNC
+against the current DGII directory snapshot. The operation is read-only and
+returns the canonical taxpayer name for the form to use. It currently requires
+an existing merchant secret key; tenant bootstrap and human administrator
+authentication are separate onboarding work:
+
+```ts
+const verification = await timbro.merchantOnboarding.verifyRnc({ rnc: "101000155" });
+// verification.legalName is the Directory's registered name.
+```
+
+`@timbro/payments` serves payment consumers. `@timbro/sdk` is the consumer-neutral fiscal SDK for ERPs, POS systems, payment systems, and other direct fiscal integrations. Neither package depends on or re-exports the other.