Introduction

Use this guide to move from sandbox onboarding to production access with clear guardrails for KYC, callbacks, connectors, and readiness.

Getting started

• Create a sandbox account and verify email.
• Signup defaults to sandbox provisioning; set sandbox=false in /auth/signup to skip sandbox setup.
• Pick SI, AP, or Hybrid for your first environment.
• Confirm your organization profile (legal name, contact email, TIN).
• Configure sandbox FIRS details (TIN, Service ID, Business ID, business name).
• Generate sandbox API keys in the dashboard (Authorization: Bearer <keyId:secret>).
• Decide which connectors you will use (Mono, Odoo, or direct SI API).

Sandbox onboarding

Sandbox onboarding focuses on connectivity and validation without production KYC:

• Register an external system and add an optional callback URL.
• Run POST /onboarding/test-callback to verify the callback endpoint.
  • The callback URL must be allowlisted via ONBOARDING_CALLBACK_ALLOWLIST.
  • HTTPS is required unless ONBOARDING_CALLBACK_ALLOW_HTTP=true.
  • Timeouts are enforced by ONBOARDING_CALLBACK_TIMEOUT_MS (default 5000).
• Run sample invoices (POST /si/invoices/sample) to verify IRN and QR generation.
• Optional: run a FIRS smoke test (POST /ap/firs-smoke) to confirm sandbox connectivity.

Connector setup (Mono/Odoo)

Use the dashboard connector panels or the SI connector endpoints:

• Enable connectors per environment and keep configs scoped to sandbox vs production.
• Odoo: test connection, store credentials (encrypted at rest), preview invoices, then sync using stored config.
• Mono: create a widget link, complete Mono Connect, exchange the auth code for an account ID, and verify webhook status. See the integration guides for details.

Production access and KYC

Production access is gated by KYC and ops controls:

• Request production access in the dashboard. The backend generates a Dojah flow link.
• The production environment moves to PENDING_KYC until the webhook returns.
• The /kyc/webhook endpoint requires x-kyc-signature and x-kyc-timestamp headers.
  • Signature is HMAC SHA256 of {timestamp}.{payload} using KYC_WEBHOOK_SECRET.
• Approved status sets APPROVED_PENDING_CONFIG and unlocks production setup.

Callbacks and webhooks

Validate webhook delivery early:

• Invoice callbacks include x-signature (HMAC SHA256 of raw body). Receivers should verify the signature.
• Mono webhooks use x-mono-signature and x-mono-timestamp with MONO_WEBHOOK_SECRET.
• Test callbacks only deliver to allowlisted URLs for sandbox safety.

Monitoring and reliability

• Check connector health via GET /si/connectors/registry.
• Review pipeline metrics via GET /si/metrics (ingest/validate/sign counters, connector health, recent failures).
• Inspect and replay DLQ items via GET /si/dlq, GET /si/dlq/stats, and POST /si/dlq/replay.
• Replay failed callbacks via POST /si/callbacks/dlq/replay.

Sandbox to production cutover

Before going live:

• Ensure /si/readiness reports sandbox ready (SI/AP enabled, DLQ empty).
• Provision production FIRS credentials and keys via ops (no UI key uploads).
• Run a production smoke invoice with callbacks and verify delivery.
• Only enable production traffic when readiness is green and connector health is stable.

System integration

System Integration (SI) handles canonical invoice ingest, validation, and signing:

• Ingest: POST /si/invoices with environmentId and optional idempotency-key.
• Retrieve status: GET /si/invoices/:id or dashboard invoice views.
• Optional callbacks for async status updates.

Access Point

Access Point (AP) adds downstream routing and archival:

• Route validated invoices to counterparties.
• Track delivery status and maintain audit trails.
• Use DLQ and replay for failed deliveries.

Hybrid orchestration

Hybrid combines SI and AP into a single workflow:

• SI ingest and validation feed AP routing automatically.
• Unified monitoring, connector health, and cutover playbooks.
• Shared audit and compliance reporting.