nuvouch
Home
§ Setup · Prerequisites

What you need before the first request

  • An active integrator record with a configured callback URL.
  • The integrator callback secret stored server-side, either as NUVOUCH_CALLBACK_SECRET or in your secret manager.
  • An integrator API key for server-to-server requests.
  • A callback handler that can verify signatures and deduplicate deliveries.
§ Setup · Server config

Configure your server runtime

.env
server environment
NUVOUCH_INTEGRATOR_API_KEY=itg_live_xxxxx
NUVOUCH_CALLBACK_SECRET=nuvouch_live_callback_secret
NUVOUCH_API_BASE_URL=https://api.nuvouch.com
Bootstrap the client
node sdk
import { createNuvouchIntegratorClientFromEnv } from "@nuvouch/integrator-sdk";

const client = createNuvouchIntegratorClientFromEnv();
// reads NUVOUCH_INTEGRATOR_API_KEY
// optional: NUVOUCH_API_BASE_URL

Public docs use x-api-key as the canonical request header. The backend also accepts Authorization: ApiKey <key>, but standardizing on one header keeps support and logging simpler.

In the integrator console, treat NUVOUCH_CALLBACK_SECRET as the canonical server env var name for the callback secret you receive or rotate there. If your platform uses a secret manager instead of env vars, store the same value there and resolve it when verifying callbacks.

secret-manager.ts
no env required
import { verifyNuvouchWebhookSignature } from "@nuvouch/integrator-sdk";

const callbackSecret = await secrets.get("integrations/nuvouch/callback-secret");

const valid = await verifyNuvouchWebhookSignature({
  secret: callbackSecret,
  rawBody,
  signatureHeader: req.headers.get("x-nuvouch-signature"),
});
§ Setup · First loop

Run the first working loop

  1. Provision the callback URL and store the callback secret from the integrator console in your server config or secret manager.
  2. Create a connection session for your business subject and show the QR code or short code in your product.
  3. Wait for the signed nuvouch.connection.accepted callback before creating approvals for that subject.
  4. Create approval requests with a stable externalRequestId.
  5. Execute the business side effect only after a verified approval callback arrives.

Continue into the integration guide for the end-to-end payment authorization walkthrough.

§ Setup · Reliability

Idempotency and retries

Retry-safe approval creation
node sdk
import {
  NUVOUCH_INTEGRATOR_ERROR_CODES,
  NuvouchApiError,
} from "@nuvouch/integrator-sdk";

const externalRequestId = "payment_auth_001";

try {
  await client.createApprovalRequest({
    targetSubject: {
      subjectId: "cus_123",
      contextKey: "merchant:acct_live_001",
    },
    externalRequestId,
    title: "Approve payment",
    summary: "Stripe needs the customer to confirm a high-risk payment.",
    requestedFor: "Payment authorization",
    actor: {
      id: "payments_agent_01",
      name: "Stripe Payment Agent",
      subtitle: "Payments risk workflow",
      avatarLabel: "ST",
    },
    context: {
      kind: "digital-service",
      title: "Card payment",
      reason: "High-risk payment requires customer confirmation",
      expiresAt: "2026-04-21T18:00:00.000Z",
      referenceCode: "pi_123",
    },
    risk: {
      level: "high",
      summary: "Customer confirmation required before capture",
    },
  });
} catch (error) {
  if (
    error instanceof NuvouchApiError &&
    error.code === NUVOUCH_INTEGRATOR_ERROR_CODES.DUPLICATE_EXTERNAL_ID
  ) {
    await client.getApprovalRequestByExternalId(externalRequestId);
  }
}
§ Setup · Environments

Staging and production safety

  • Keep callback secrets and API keys separate per environment.
  • Never point staging Nuvouch deployments at production callback URLs.
  • Verify signed callbacks and delivery retries in staging before production rollout.
  • Store callback secrets and API keys only in server-side config, never in browser bundles.
§ Next

Continue with the references

Move into the Node SDK reference, HTTP API reference, webhook reference, and integration guide.