@timbro/payments 0.1.0-next.4 → 0.2.0-next.0

package/README.md

@@ -1,283 +1,92 @@
 # `@timbro/payments`
 
-Node 24 ESM SDK for merchant Payments, their payment-linked fiscal documents, and the merchant
-business that onboards them.
+Create a payment on your server and send the customer to Checkout. Read the Payment state from your server; signed webhooks notify you when it changes. Use `@timbro/invoices` to issue, retrieve, and deliver invoices independently. This SDK coordinates invoices with Payments and Refunds through their canonical `invoiceId`.
 
-`apiKey` takes either merchant key. A secret key (`sk_test_…` or `sk_live_…`) creates and reads
-Payments; an administrator key, which the owner creates and names in the Workspace business
-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.
+Requires Node.js 24.19 or later and ESM. Install the stable `0.1.0` release:
 
-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, decimal money values,
-Checkout URL, stable capture allocations with sanitized payment method
-summaries, and the fiscal recipient projection needed by an ERP.
+```sh
+npm install @timbro/payments
+```
 
-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:
+Keep the API key on your server. Its granted capabilities determine which Payment, Invoice coordination, and Business setup tasks it can perform. This example assumes the merchant has an explicit amount-only tax default configured. Timbro does not infer a tax rate. For an amount-only override, pass `tax: { includedAmount: "190.68" }`; see [taxes and sale items](https://timbro.do/en/docs/cobros/impuestos-y-articulos/) for setup and itemized sales.
 
 ```ts
 import { createTimbroPayments } from "@timbro/payments";
 
-const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY });
-const payment = await timbro.payments.create({
-  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 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({
-  paymentReference: "order-126-payment-1",
-  source: { id: "odoo:pos.order:126", version: "3" },
-  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" },
+const timbro = createTimbroPayments({
+  apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY,
 });
-```
 
-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.
-The Gateway reserves captured allocation balances before provider work begins:
+export async function POST(): Promise<Response> {
+  const payment = await timbro.payments.create({
+    paymentReference: "order-123-payment-1",
+    amount: { currency: "DOP", value: "1250.00" },
+    description: "Service",
+    returnUrl: "https://shop.example.com/orders/123",
+  });
 
-```ts
-const refund = await timbro.refunds.create({
-  paymentId: payment.id,
-  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),
-});
+  return Response.redirect(payment.checkout.url);
+}
 ```
 
-The Refund response keeps `allocationIds` and exact `allocationAmounts` so an
-ERP can reconcile one or more split-payer allocations without exceeding any
-captured 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",
-});
-```
+Replace `order-123-payment-1` with a stable reference for your order and persist it before collecting payment. Reuse the same reference and request after a timeout to recover that Payment; changing the request under that reference conflicts. `returnUrl` returns the customer from Checkout and does not confirm payment. See [retries and idempotency](https://timbro.do/en/docs/cobros/reintentos-e-idempotencia/) and [signed webhooks](https://timbro.do/en/docs/cobros/webhooks/).
 
-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.
+## Read, cancel, or refund
 
-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.
+Retrieve a Payment from your server to read its current state:
 
 ```ts
-const canceled = await timbro.payments.cancel({
-  paymentId: payment.id,
-});
+const payment = await timbro.payments.retrieve("payment_123");
 ```
 
-`merchantCheckoutPolicy.retrieve()` reads tenant- and mode-scoped defaults and
-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:
+Cancel only a Payment that is still unpaid and eligible for cancellation:
 
 ```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,
-});
+await timbro.payments.cancel({ paymentId: "payment_123" });
 ```
 
-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({
-  paymentReference: "order-124-payment-1",
-  source: { id: "odoo:pos.order:124", version: "9" },
-  currency: "DOP",
-  items: [{
-    id: "meal", description: "Meal", quantity: "1", unit: "unit", unitPrice: "1250.00", kind: "good",
-    tax: { kind: "itbis_18", included: true },
-  }],
-  expectedTotals: { 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:
+Refund only after capture. Omitting `amount` reserves the remaining refundable balance once:
 
 ```ts
 const refund = await timbro.refunds.create({
-  paymentId: payment.id,
-  source: { id: "odoo:pos.order:124:return:1", version: "1" },
-  refundReference: "RETURN-124-1",
-  amount: { currency: "DOP", value: "500.00" },
-  allocationIds: [payment.capturedPayment!.allocations[0]!.id],
+  paymentId: "payment_123",
+  refundReference: "order-123-refund-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",
-  });
-}
 ```
 
-`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.
-
-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. Either merchant key
-calls it:
+Before the customer submits a payment, choose its Invoice type and buyer:
 
 ```ts
-const verification = await timbro.merchantOnboarding.verifyRnc({ rnc: "101000155" });
-// verification.legalName is the Directory's registered name.
-```
-
-## Onboard the merchant business
-
-The business belongs to the key's tenant, so no call names it. Claiming the business and handing
-over the certificate file stay with the person who holds them; everything else is one resource.
-Read it, act on the first requirement your integration owns, and read it again:
-
-```ts
-const admin = createTimbroPayments({ apiKey: process.env.TIMBRO_ADMIN_KEY });
-
-let business = await admin.merchantBusiness.retrieve();
-business = await admin.merchantBusiness.update({
-  capabilities: { electronicInvoicing: { requested: true } },
-  fiscalDetails: {
-    commercialName: "Café Duarte",
-    address: "Calle El Conde 101",
-    location: { municipalityCode: "320100" },
-    phone: "+18095550142",
-    defaultIncomeType: "01",
-  },
-});
-business = await admin.merchantBusiness.importSigningCertificate({
-  certificateP12Base64: p12.toString("base64"),
-  password: certificatePassword,
+await timbro.payments.updateInvoiceChoice({
+  paymentId: payment.id,
+  idempotencyKey: "buyer-1",
+  type: "E31",
+  buyer: { kind: "domestic", taxId: "130123456" },
 });
-// Timbro sends the TesteCF document itself; poll until DGII answers.
-business = await admin.merchantBusiness.retrieve();
-if (business.capabilities.electronicInvoicing.status === "active") {
-  const { credential, fiscalOrigin } = await admin.merchantBusiness.issueSandboxCredential({
-    idempotencyKey: "sandbox-credential-1",
-  });
-}
 ```
 
-Each entry of `business.requirements` names its `owner`: `merchant` entries are yours to resolve,
-and `field` points into the representation when a field answers it. `dgii` and `timbro` entries
-wait, `provider` entries wait on the acquirer, and `operator` entries need Timbro support. `update` replaces each member it carries, and
-an `expectedRevision` refuses a stale write with `merchant_business_revision_conflict`.
-Electronic invoicing onboards against DGII's TesteCF environment only. The certificate import is
-the one call that carries the PKCS#12 archive; send it only from a machine that already holds the
-file, and do not resend it once `fiscalSetup.signingCertificate.sha256` matches.
-`retryTestFiscalDocument()` sends a new TesteCF document only when none is processing or
-accepted. `issueSandboxCredential` returns the ERP credential once and retires the one issued
-before it; the same `idempotencyKey` replays it.
-
-## Every published operation
+Use `buyer: { kind: "anonymous" }` to clear an earlier recipient. The operation preserves locked choices and refuses changes after submission or split creation.
 
-`timbro.client` is the typed low-level client for every operation in the published document,
-with the same key and transport. Requests, responses, and Problem bodies are typed from the
-generated `paths`, `components`, and `operations`, which the package also exports:
+For a partial refund, pass exact `amount` and, when returning a voluntary tip, `voluntaryTipAmount`, each as `{ currency, value }`. Omitting the tip portion declares zero; refunding the entire remaining balance includes its remaining tip. `Refund.voluntaryTipAmount` records the reserved portion. Issue the credit note through the Invoices API for the commercial portion, then associate it separately:
 
 ```ts
-import { createTimbroPayments, type components } from "@timbro/payments";
-
-const { data, error, response } = await timbro.client.POST("/v1/api_keys/rotate", {
-  params: { header: { "idempotency-key": "rotate-2026-09" } },
+await timbro.refunds.attachInvoice({
+  refundId: refund.id,
+  invoiceId: creditNote.id,
+  idempotencyKey: "order-123-credit-note",
+  receipt: { id: receipt.id, accessToken: receipt.accessToken },
 });
-if (error !== undefined) {
-  console.error(response.status, error.code);
-}
-type Requirement = components["schemas"]["MerchantBusinessRequirement"];
 ```
 
-The facade covers every published merchant operation except `rotateApiKey` and
-`chooseFiscalDocument`, which the client reaches directly.
+Use the restricted receipt when the ERP owns the Invoice through an independent Source. The Gateway verifies the original Invoice, issuer, environment, currency, acceptance, and amount before setting `Refund.invoiceId`; it never changes the provider outcome.
 
-## From a terminal
+Reuse a `refundReference` for retries. Automatic refunds currently cover full, unsplit DOP card payments in TEST with Azul. CardNet refund qualification remains open in [issue #587](https://github.com/indexa-labs/checkout/issues/587); partial, split, LIVE, wallet, and sandbox refunds require an operator and return `operator_required`. See [refunds](https://timbro.do/en/docs/cobros/reembolsos/).
 
-The published document is served at `https://api.timbro.do/openapi.json`, so a
-generic OpenAPI client needs nothing from Timbro. With [Restish](https://rest.sh), register the
-API once and pass a test administrator key on each call, from an environment variable rather than
-your shell history:
-
-```sh
-restish api configure timbro https://api.timbro.do
-restish timbro retrieve-merchant-business -H "Authorization: Bearer $TIMBRO_ADMIN_KEY"
-restish timbro update-merchant-business -H "Authorization: Bearer $TIMBRO_ADMIN_KEY" \
-  'capabilities.electronicInvoicing.requested: true'
-jq -n --arg p12 "$(base64 -w0 certificate.p12)" --arg password "$CERTIFICATE_PASSWORD" \
-  '{certificateP12Base64: $p12, password: $password}' |
-  restish timbro import-merchant-business-signing-certificate -H "Authorization: Bearer $TIMBRO_ADMIN_KEY"
-```
+## Guides and API reference
 
-Restish names each command after the operation ID in kebab case. Timbro ships no CLI of its own.
+- [Retrieve payments](https://timbro.do/en/docs/cobros/consultar-pagos/) and [payment states](https://timbro.do/en/docs/cobros/estados-del-pago/)
+- [Taxes and sale items](https://timbro.do/en/docs/cobros/impuestos-y-articulos/) and [request an e-CF](https://timbro.do/en/docs/comprobantes/emitir-ecf/)
+- [Webhooks](https://timbro.do/en/docs/cobros/webhooks/) and [refunds](https://timbro.do/en/docs/cobros/reembolsos/)
+- [Payments API reference](https://timbro.do/en/docs/reference/payments/) and [error handling](https://timbro.do/en/docs/produccion/errores/)
 
-`@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.
+Use `PaymentsError.code` to classify API failures. The [Payments API reference](https://timbro.do/en/docs/reference/payments/) documents the complete surface; see [error handling](https://timbro.do/en/docs/produccion/errores/) for recovery guidance.