@cauril/node

Typed Node.js client for the Cauril payments API. A thin fetch wrapper over the v1 endpoints, with request/response types that match the API exactly.

Requires Node ≥ 20 (uses the global fetch and node:crypto). Zero runtime dependencies.

npm install @cauril/node

import { Cauril } from "@cauril/node";

const cauril = new Cauril(process.env.CAURIL_SECRET_KEY!); // sk_test_… or sk_live_…

const payment = await cauril.payments.create(
  {
    amount: 5000,
    currency: "BRL",
    payment_method: { type: "card", token: tokenFromClient },
    description: "Plan Pro - junio",
    // omit `provider` to let server-side routing rules pick the PSP
  },
  { idempotencyKey: orderId }, // same orderId never double-charges
);

if (payment.status === "requires_action") {
  redirect(payment.next_action!.url!);
}

// Refund (full or partial) — created from the payment, not via `refunds.create`:
const refund = await cauril.payments.refund(payment.id, { amount: 2000 });

What it does for you

• Idempotency by default. Every mutating call sends an Idempotency-Key; if you don't pass one, the SDK mints a UUID v4. Retries therefore never double-charge (hard rule #4).
• Automatic retries. Network errors, 429 (honoring Retry-After) and 5xx are retried with jittered exponential backoff. Safe because every retried request carries a stable idempotency key. Deterministic 4xx (e.g. card_declined, 400) are not retried.
• Auto-pagination. Every list method has a listAutoPaging(...) async iterator that follows next_cursor across pages.
• Typed errors. Failures throw CaurilAPIError (with .type, .code, .statusCode, .requestId, .providerError) or CaurilConnectionError. All extend CaurilError — guard with CaurilError.is(e).
• Webhook verification. cauril.webhooks.constructEvent(rawBody, sigHeader, secret) verifies the Cauril-Signature HMAC + timestamp (API_SPEC §6) and returns the parsed event. (verifySignature(...) returns just a boolean if you've already parsed the body.)

Config

new Cauril(apiKey, {
  baseURL: "https://api.cauril.com", // default
  apiVersion: "2026-06-01",          // Cauril-Version header
  maxRetries: 2,                      // up to 3 attempts
  timeout: 60_000,                    // ms per attempt
  fetch: customFetch,                 // inject for tests / other runtimes
});

Resources

payments (incl. payments.refund(id, …)) · refunds (retrieve only) · customers · providerConnections · routingRules · webhookEndpoints · webhookDeliveries · events · analytics · plans · subscriptions · invoices · checkout.sessions (server-side create/retrieve/cancel) · webhooks (signature verification).

Buyer-side checkout operations (confirm/reroute, which use a per-session client_secret) live in the browser drop-in @cauril/checkout-js, not here — this is the server SDK.

Notes

• Amounts are integers in the minor unit (cents) + ISO-4217 currency. Never floats.
• The SDK never sees a PAN/CVV — payment_method.token is produced client-side by the PSP SDK (SAQ-A).
• Full API reference and guides: cauril.com/docs.