Onboarding

From "I want to integrate" to your first live submission.

1. Get provisioned (keys)

Two paths, one per environment:

Sandbox (staging) — open signup is on. Sign up at console.gofundnode.com, point the console at the staging environment, and it issues your staging keys on the spot. Ops can also provision a staging tenant for you.
Production — GoFundNode ops creates your tenant; keys arrive via a secrets vault (never email/Slack/git).

Either way you receive, per environment:

Item	What it is
Tenant API id	Your public id, sent as `X-GFN-Tenant`.
HMAC secret	Signs your requests to GoFundNode.
Webhook secret	Verifies webhooks from GoFundNode (separate secret).
Allowed job types	The allowlist you may submit. Launch: `["ats.application"]`.

Store both secrets in your own secret manager and expose them as env vars:

GFN_API_BASE_URL=https://api.staging.gofundnode.com   # sandbox; production is https://api.gofundnode.com
GFN_TENANT_API_ID=<your tenant api id>
GFN_HMAC_SECRET=<inbound signing secret>
GFN_WEBHOOK_SECRET=<inbound webhook verification secret>

The two secrets are not interchangeable. Swapping them makes every request (or every webhook verification) 401. See Auth.

2. Configure your webhook URL

Give ops a public HTTPS endpoint — this becomes your webhook_url.
Implement the handler: verify the signature on the raw body, dedupe on X-GFN-Delivery, reply 2xx fast. See Webhooks.
No URL configured = events silently dropped; poll GET /v1/submissions/:id instead, or set a URL.

3. Sandbox vs production

Two live environments. The sandbox runs at https://api.staging.gofundnode.com with its own database and its own TLS, and speaks a byte-identical wire — same endpoints, same signing, same webhooks, same error taxonomy. Build against the sandbox first; nothing you write there changes for production.

	Sandbox (staging)	Production
Base URL	`https://api.staging.gofundnode.com`	`https://api.gofundnode.com`
Keys	Open signup via the console (pointed at staging), or ops-provisioned	Ops-provisioned, prod vault item
Data	Its own database — nothing shared with production	Live tenants, live submissions
Credits	Automatic signup grant; further top-ups ops-coordinated	Fiat top-ups, ops-coordinated
Wire	Byte-identical. Only the base URL + secrets change between environments.

To promote, swap the base URL and both secrets — nothing else changes. Verify either environment with GET /ready (no auth) → { "status": "ready" }.

4. Top up credits (fiat)

Fiat is the customer payment rail (ADR-046). Credits are a consumptive, single-issuer, non-transferable prepayment — no token, wallet, or stored value. During the pilot beta, top-ups in both environments are coordinated with ops (ops@gofundnode.com): you pay in fiat and ops grants the credits to your tenant. Sandbox tenants start with an automatic signup grant, so you can submit on staging before any top-up. There is no customer-callable purchase endpoint; self-serve checkout arrives with general availability, and until then top-ups remain ops-coordinated. Watch GET /v1/credits/balance and the credits.low_balance webhook (default threshold 1000). The inbound Solana Pay USDC flow is a preserved continuity exception (ADR-047), off unless enabled — not the GA rail. See Credits.

5. Go-live checklist

A sandbox submission succeeds end-to-end (201 → webhook → settled) against https://api.staging.gofundnode.com; first production submissions are coordinated with ops.
Webhook handler verifies signatures, dedupes on X-GFN-Delivery, replies 2xx.
Idempotency keys are derived from your durable records (not random). See Idempotency.
Clock is NTP-synced (avoids ±5-min replay 401s).
Prod secrets + base URL configured; GET /ready is green.
A funded fiat credit balance.

Platform-side launch gates live in docs/launch/GA-CHECKLIST.md in the repository.

6. Support

Provisioning, secrets, top-ups, incidents: ops@gofundnode.com.
Live status, both environments: status.gofundnode.com.
API reference (source of truth): docs/V1-API.md in the repository.
Integration walkthrough: docs/TENANT-ONBOARDING.md in the repository.
SDK: @gofundnode/vendor-client (packages/vendor-client/README.md).

Include the x-request-id response header (surfaced as err.requestId on SDK errors) when reporting an issue.