@timbro/payments 0.1.0-next.3 → 0.1.0

package/README.md

@@ -8,54 +8,51 @@ Payments; an administrator key, which the owner creates and names in the Workspa
 settings, also administers the business and its Merchant Accounts. Keys are additive: creating another one,
 of either kind, never retires the keys you already use.
 
-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.
+Each Payment is identified by an immutable `paymentReference` within the merchant and TEST/LIVE scope. The SDK derives a stable HTTP idempotency key from that identity and retries payment creation a bounded number of times. Optional `source` coordinates preserve an upstream order identity; `saleReference` remains a searchable business label and may repeat.
 
-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.
+Payment reads preserve that source, the canonical sale, decimal money values,
+Checkout URL, 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:
+Use the amount form when the adapter has one payable amount. Declare the tax
+included in that amount; Timbro does not infer a tax rate for an amount-only
+request. Omitting `tax` lets an explicitly configured merchant policy apply or
+returns an input error when no policy covers the sale. Omitting `invoicing`
+means no fiscal issuance is requested:
 
 ```ts
 import { createTimbroPayments } from "@timbro/payments";
 
 const timbro = createTimbroPayments({ apiKey: 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,
+  paymentReference: "order-123-payment-1",
+  amount: { currency: "DOP", value: "1250.00" },
+  description: "Consumo en el comercio",
+  tax: { includedAmount: "190.68" },
 });
+return Response.redirect(payment.checkout.url);
 ```
 
-Use `itemized` when the adapter has commercial lines. Each line carries its fiscal description and exact decimal price; optional `product` data is presentation metadata:
+Use the itemized form when the adapter has commercial lines. Each line carries
+its description, exact decimal price, and tax treatment. Fiscal item fields
+become required when invoicing needs them:
 
 ```ts
 await timbro.payments.create({
-  idempotencyKey: "create-coffee-126",
+  paymentReference: "order-126-payment-1",
   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,
+  currency: "DOP",
+  items: [{ description: "Café", quantity: "2", unitPrice: "118.00",
+    tax: { kind: "itbis_18", included: true } }],
+  expectedTotals: { net: "200.00", tax: "36.00", legalTip: "0.00", total: "236.00" },
 });
+```
 
-`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`.
+Timbro computes line rounding and totals once. `expectedTotals` lets the caller
+assert agreement with its accounting snapshot. Product IDs, line IDs, quantity,
+unit, and good/service kind are optional for payment-only lines; invoicing
+requires the fiscal details it consumes. Money fields on Payment and Refund
+resources use `{ currency, value }` decimal strings.
 
 Refunds are durable full or partial resources with idempotent create, retrieve,
 and list operations. Provider outcome and fiscal note coordination are separate.
@@ -63,11 +60,9 @@ 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 },
+  refundReference: "order-124-return-1",
+  amount: { currency: "DOP", value: "125.00" },
   // Optional for split Payments; omit to reserve across every captured allocation.
   allocationIds: payment.capturedPayment?.allocations.map(({ id }) => id),
 });
@@ -75,10 +70,13 @@ const refund = await timbro.refunds.create({
 
 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.
+captured balance. The Refund row owns the durable provider binding,
+submission fence, and recovery schedule. Full, unsplit DOP TEST Azul card refunds
+use the original capture credentials and tax, and confirm approval through
+`VerifyPayment` on a unique refund correlation. TEST CardNet full refunds retain
+the Ztrans submission and same-key inquiry path, pending provider qualification
+in [issue #587](https://github.com/indexa-labs/checkout/issues/587). Partial, split,
+live-mode, wallet, 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
@@ -116,27 +114,43 @@ 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.
+constraints. Administrators replace them through a revision-checked `PUT`;
+ordinary merchant secret keys cannot update policy. The optional `defaults.tax`
+selects an explicit inclusive tax treatment for amount-only requests:
+
+```ts
+const admin = createTimbroPayments({ apiKey: process.env.TIMBRO_ADMIN_KEY });
+const policy = await admin.merchantCheckoutPolicy.retrieve();
+await admin.merchantCheckoutPolicy.update({
+  expectedRevision: policy.revision,
+  defaults: {
+    ...policy.defaults,
+    tax: { kind: "itbis_18", included: true },
+  },
+  constraints: policy.constraints,
+});
+```
+
+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",
+  paymentReference: "order-124-payment-1",
   source: { id: "odoo:pos.order:124", version: "9" },
-  sale: { kind: "itemized", reference: "order-124", currency: "DOP", items: [{
+  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" } },
+  }],
+  expectedTotals: { net: "1059.32", tax: "190.68", legalTip: "0.00", total: "1250.00" },
   invoicing: { mode: "required", type: "consumer", merchantInvoiceNumber: "INV-124", merchantOrderNumber: "124" },
 });
 ```
@@ -149,10 +163,9 @@ Refunds use one resource for the provider money movement and the separate fiscal
 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 },
+  refundReference: "RETURN-124-1",
+  amount: { currency: "DOP", value: "500.00" },
   allocationIds: [payment.capturedPayment!.allocations[0]!.id],
-  idempotencyKey: "refund-order-124-return-1",
 });
 
 if (refund.providerOutcome.status === "succeeded") {
@@ -166,9 +179,15 @@ if (refund.providerOutcome.status === "succeeded") {
 }
 ```
 
-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.
+`timbro.refunds.create()` also accepts an omitted `amount`, which reserves the
+remaining refundable balance once. Repeating the same `refundReference` returns that
+same reservation. `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.
+Full, unsplit DOP TEST Azul card refunds submit against the original captured transaction and accepted tax, then confirm the refund amount through `VerifyPayment`. Azul allows one refund per settled transaction within six months; this implementation supports a full refund. CardNet Ztrans full refunds have deterministic recovery tests, while provider refund, inquiry, and settlement qualification remains open in [issue #587](https://github.com/indexa-labs/checkout/issues/587). Partial, split, live-mode, wallet, 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