Skip to content
NuansisNuansis Docs

Quickstart

This walkthrough takes you from zero to a successful API response. You will need a Nuansis workspace and permission to manage its API keys.

1. Create a workspace

Section titled “1. Create a workspace”

Sign up at platform.nuansis.co/register with your company email. The workspace is the tenant boundary for everything in the API: balances, collections, beneficiaries, verifications and webhook endpoints all belong to one business.

You can build against the API as soon as the workspace exists. Collecting and paying out real money additionally requires the business to complete KYB in the dashboard.

2. Mint an API key

Section titled “2. Mint an API key”

In the dashboard, open Settings → API keys and create a key. Pick the scopes the integration needs:

  • verification:write — start and check OTP verifications
  • collections:write — create collections, reserved accounts and deposits
  • payouts:write — create transfers, beneficiaries and withdrawals
  • read — read any resource (implied by every *:write scope)

The full key is displayed once, at creation time. Copy it straight into your secret manager. Nuansis stores only sha256(secret) plus a non-secret prefix, so the plaintext cannot be recovered later. The shape is:

nvs_live_sk_<12 hex characters>_<64 hex characters>

See API keys for rotation and revocation, and Authentication for how the key is presented on each request.

3. Make your first request

Section titled “3. Make your first request”

GET /v1/capabilities is authenticated but has no side effects — the safest first call. It tells you which product surfaces are live for this API version.

curl
export NUANSIS_API_KEY="nvs_live_sk_…"


curl https://api.nuansis.co/v1/capabilities \
  -H "Authorization: Bearer $NUANSIS_API_KEY"
Node 18+
const apiKey = process.env.NUANSIS_API_KEY;


const res = await fetch('https://api.nuansis.co/v1/capabilities', {
  headers: { Authorization: `Bearer ${apiKey}` },
});


if (!res.ok) {
  const body = await res.json();
  throw new Error(`${res.status} ${body.error?.code}: ${body.error?.message}`);
}


const body = await res.json();
console.log(body.data);

The response is wrapped in the standard envelope:

{
  "data": {
    "verification": "live",
    "collections": "live",
    "reserved_accounts": "live",
    "payouts": "live",
    "balances": "live",
    "transactions": "live",
    "channels": "live",
    "recipients": "live",
    "beneficiaries": "live",
    "deposits": "live",
    "withdrawals": "live",
    "cards": "coming_soon"
  },
  "meta": { "request_id": "0f4b2f36-4b7e-4f1e-9c2a-6a1f0d8e2b77" }
}

Every response also carries an X-Request-Id header. Send your own X-Request-Id and Nuansis will echo it back instead of generating one — useful for tracing a request across your logs and ours.

4. Create something

Section titled “4. Create something”

Most write endpoints are POST and accept an Idempotency-Key header. A minimal NGN collection:

Terminal window
curl -X POST https://api.nuansis.co/v1/collections \
  -H "Authorization: Bearer $NUANSIS_API_KEY" \
  -H "Idempotency-Key: 3f6c1a9e-collection-001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "NGN",
    "reference": "order-1042",
    "customer": { "name": "Adaeze Okafor", "email": "ada@example.com" },
    "expires_in": 3600
  }'

The 201 response contains the bank account the customer should pay into, plus an expiry. Read Collections before going live, and Idempotency before adding retries.

Test and live keys

Section titled “Test and live keys”

Keys are minted with an environment label, live or test, which is part of the key string and is returned in key metadata. The label is recorded on the key and shown in the dashboard.

The current control API does not expose a separate sandbox host or sandbox data plane: both labels authenticate against the same /v1 endpoints and operate on the same workspace data. Treat test as a labelling convention for your own key management, not as an isolated sandbox.

Next steps

Section titled “Next steps”