@timbro/payments 0.2.0-next.0 → 0.2.0-next.2

package/README.md

@@ -1,92 +1,160 @@
 # `@timbro/payments`
 
-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`.
+Create a payment on your server and send the customer to Checkout. Retrieve the Payment to confirm collection; signed webhooks notify you when it changes. Use `@timbro/invoices` to issue and deliver invoices. Payments and Refunds coordinate with invoices through the canonical `invoiceId`.
 
-Requires Node.js 24.19 or later and ESM. Install the stable `0.1.0` release:
+Requires Node.js 24.19 or later and ESM. These examples use the prerelease API:
 
 ```sh
-npm install @timbro/payments
+npm install @timbro/payments@0.2.0-next.2
 ```
 
-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.
+The stable `0.1.0` package uses the earlier fiscal coordination interface. Do not mix its methods with these examples. Check [capabilities and enablement](https://timbro.do/en/docs/produccion/capacidades/) before using a function for a merchant or environment.
+
+## Create and confirm a payment
+
+Keep the merchant API key on your server. Its capabilities determine which tasks it can perform. For an amount-only payment, configure a tax default or send `tax.includedAmount`; Timbro does not infer the tax rate.
 
 ```ts
 import { createTimbroPayments } from "@timbro/payments";
 
-const timbro = createTimbroPayments({
-  apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY,
-});
+const apiKey = process.env.TIMBRO_PAYMENTS_SECRET_KEY;
+if (!apiKey) throw new Error("TIMBRO_PAYMENTS_SECRET_KEY is required");
+const timbro = createTimbroPayments({ apiKey });
 
 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",
+    tax: { includedAmount: "190.68" },
     returnUrl: "https://shop.example.com/orders/123",
   });
-
   return Response.redirect(payment.checkout.url);
 }
 ```
 
-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/).
+Persist a unique `paymentReference` and the request before sending it. Reuse both after a timeout to recover the same Payment; changing its intent conflicts. The customer's return to `returnUrl` does not confirm payment.
+
+```ts
+const payment = await timbro.payments.retrieve("payment_123456789abcdefghjkmnpqr");
+if (payment.status === "succeeded") {
+  // Apply the matching reference, currency, and amount to your order once.
+}
+```
 
-## Read, cancel, or refund
+## Collect and issue an invoice
 
-Retrieve a Payment from your server to read its current state:
+Automatic and merchant invoicing require itemized DOP sales. Supply each item's fiscal unit and kind. An amount-only Payment cannot be changed into an invoice-capable sale through `updateInvoiceChoice`.
 
 ```ts
-const payment = await timbro.payments.retrieve("payment_123");
+const invoicePayment = await timbro.payments.create({
+  paymentReference: "order-124-payment-1",
+  currency: "DOP",
+  items: [{
+    description: "Service",
+    quantity: "1",
+    unit: "unit",
+    kind: "service",
+    unitPrice: "1250.00",
+    tax: { kind: "itbis_18", included: true },
+  }],
+  invoicing: { mode: "automatic", type: "E32" },
+});
+
+await timbro.payments.updateInvoiceChoice({
+  paymentId: invoicePayment.id,
+  idempotencyKey: "order-124-buyer-1",
+  type: "E31",
+  buyer: { kind: "domestic", taxId: "130123456" },
+});
 ```
 
-Cancel only a Payment that is still unpaid and eligible for cancellation:
+Choose the Invoice type and buyer before submission, using the buyer's real tax identity. Locked choices and changes after submission or split creation are refused. Where permitted, `buyer: { kind: "anonymous" }` clears an earlier recipient. A captured Payment's `invoiceId` identifies its invoice; retrieve it through Invoices to confirm acceptance and file readiness.
+
+For merchant-issued or existing invoices and independent installations, follow [collect and issue an e-CF](https://timbro.do/en/docs/comprobantes/emitir-ecf/). An independent installation supplies restricted receipt access; Payments never needs its Source key.
+
+## Cancel or refund
+
+Cancel an unpaid Payment only while cancellation is permitted:
 
 ```ts
-await timbro.payments.cancel({ paymentId: "payment_123" });
+await timbro.payments.cancel({ paymentId: "payment_123456789abcdefghjkmnpqr" });
 ```
 
-Refund only after capture. Omitting `amount` reserves the remaining refundable balance once:
+Refund after capture. Omitting `amount` reserves the remaining refundable balance once. For a partial refund, `amount` is the total returned money and `voluntaryTipAmount` is the portion returning a voluntary tip. Omitting the tip portion declares zero; returning the entire remaining balance includes the remaining tip.
 
 ```ts
 const refund = await timbro.refunds.create({
-  paymentId: "payment_123",
+  paymentId: "payment_123456789abcdefghjkmnpqr",
   refundReference: "order-123-refund-1",
+  amount: { currency: "DOP", value: "135.00" },
+  voluntaryTipAmount: { currency: "DOP", value: "10.00" },
 });
 ```
 
-Before the customer submits a payment, choose its Invoice type and buyer:
+Reuse `refundReference` and the request for retries. Automatic provider refunds currently cover full, unsplit DOP card payments in TEST with Azul. CardNet refund and inquiry qualification remain pending. Partial, split, LIVE, wallet, and sandbox paths require an operator and return `operator_required` before remote money movement.
+
+## Associate the credit note separately
+
+A provider refund does not create an E34 credit note. In this example, RD$125.00 is the commercial portion and RD$10.00 is the voluntary tip, which is excluded from the credit-note amount. Replace `originalInvoiceId` with the accepted invoice for this payment and use its actual fiscal facts. Install the fiscal SDK before this step:
+
+```sh
+npm install @timbro/invoices@0.9.0-next.1
+```
 
 ```ts
-await timbro.payments.updateInvoiceChoice({
-  paymentId: payment.id,
-  idempotencyKey: "buyer-1",
-  type: "E31",
-  buyer: { kind: "domestic", taxId: "130123456" },
+import { createTimbroInvoices } from "@timbro/invoices";
+
+const invoiceApiKey = process.env.TIMBRO_INVOICES_API_KEY;
+if (!invoiceApiKey) throw new Error("TIMBRO_INVOICES_API_KEY is required");
+const invoices = createTimbroInvoices({
+  apiKey: invoiceApiKey,
+  baseUrl: process.env.TIMBRO_INVOICES_ORIGIN,
+});
+const creditNote = await invoices.invoices.create({
+  invoiceReference: "order-123-credit-note-1",
+  type: "E34",
+  originalInvoiceId: "f35b7ae4-c484-4c63-981e-4f0f15e913b5",
+  modificationCode: "3",
+  reason: "Partial return",
+  currency: "DOP",
+  incomeType: "01",
+  paymentTerms: { type: "immediate" },
+  items: [{
+    description: "Returned service",
+    quantity: "1",
+    unit: "unit",
+    kind: "service",
+    unitPrice: "125.00",
+    tax: { kind: "itbis_18", included: true },
+  }],
 });
 ```
 
-Use `buyer: { kind: "anonymous" }` to clear an earlier recipient. The operation preserves locked choices and refuses changes after submission or split creation.
-
-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:
+For an independent installation, set `TIMBRO_INVOICES_ORIGIN` to its trusted origin and use its own key. Omit the origin for the hosted Gateway. Once the credit note is accepted, associate it with the Refund. For an Invoice from an independent installation, obtain its restricted receipt there and keep the token on your server:
 
 ```ts
+const currentCreditNote = await invoices.invoices.retrieve(creditNote.id);
+if (
+  currentCreditNote?.status !== "accepted" &&
+  currentCreditNote?.status !== "acceptedWithObservations"
+) throw new Error("The credit note is not accepted yet");
+const receipt = await invoices.invoices.shareReceipt(creditNote.id);
 await timbro.refunds.attachInvoice({
   refundId: refund.id,
   invoiceId: creditNote.id,
-  idempotencyKey: "order-123-credit-note",
   receipt: { id: receipt.id, accessToken: receipt.accessToken },
+  idempotencyKey: "order-123-credit-note-association",
 });
 ```
 
-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.
-
-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/).
+For an Invoice in the same hosted business, omit `receipt`. The Gateway verifies the original Invoice, issuer, environment, currency, acceptance, and amount before setting `Refund.invoiceId`. This association does not change the provider outcome.
 
 ## Guides and API reference
 
 - [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/)
+- [Taxes and sale items](https://timbro.do/en/docs/cobros/impuestos-y-articulos/) and [signed webhooks](https://timbro.do/en/docs/cobros/webhooks/)
+- [Refunds](https://timbro.do/en/docs/cobros/reembolsos/) and [credit or debit notes](https://timbro.do/en/docs/comprobantes/corregir-ecf/)
+- [REST reference](https://timbro.do/en/docs/reference/payments/) and [error handling](https://timbro.do/en/docs/produccion/errores/)
 
-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.
+`PaymentsError` exposes the error code, HTTP status, request ID, field problems, retry timing, and cause. Check the operation's recovery rules before retrying. The generated transport and internal coordination modules are not public entrypoints.