Deposits

POST /v1/deposits is the channel-oriented way to open a money-in surface. It dispatches on channel and returns a channel-specific payload. For a customer-specific collection with their name and email, use Collections instead — the deposit endpoint always uses the business as the account holder.

Endpoints

Method	Path	Scope	Success
POST	/v1/deposits	collections:write	201
GET	/v1/channels	read	200

Channels

GET /v1/channels returns the catalog with the status currently in force:

{
  "data": [
    { "id": "card", "label": "Card", "status": "coming_soon", "currencies": ["NGN", "USD", "GBP", "EUR"] },
    { "id": "collection_va", "label": "Bank transfer (one-off account)", "status": "live", "currencies": ["NGN"] },
    { "id": "reserved_va", "label": "Bank transfer (reserved account)", "status": "live", "currencies": ["NGN"] },
    { "id": "open_banking", "label": "Open banking", "status": "coming_soon", "currencies": ["NGN", "USD", "GBP", "EUR"] }
  ],
  "meta": { "request_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }
}

Statuses are configuration-driven. Each channel has a shipped default (card and open_banking default to coming_soon; both VA channels default to live), which an operator can override per deployment. Always read GET /v1/channels rather than hard-coding availability.

Create a deposit

POST /v1/deposits

Field	Type	Required	Notes
channel	string	Yes	card, collection_va, reserved_va, or open_banking
currency	string	No	Defaults to NGN; must be supported by the channel
amount	number	Conditional	Required for collection_va; minimum 1. Ignored elsewhere
reference	string	No	De-duplication reference for one-off accounts
expires_in	integer	No	Seconds a one-off account stays open. Minimum 60, default 3600

collection_va — one-off account

curl -X POST https://api.nuansis.co/v1/deposits \
  -H "Authorization: Bearer $NUANSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "collection_va",
    "currency": "NGN",
    "amount": 75000,
    "reference": "invoice-2091",
    "expires_in": 1800
  }'

{
  "data": {
    "channel": "collection_va",
    "status": "pending",
    "account": {
      "bank": "Providus Bank",
      "bank_code": "101",
      "account_number": "9901234567",
      "account_name": "Acme Studio Ltd",
      "expires_at": "2026-10-18T11:26:07.412Z"
    }
  },
  "meta": { "request_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e" }
}

reserved_va — persistent account

Returns the workspace’s existing reserved account for the currency, creating one on first use.

{
  "data": {
    "channel": "reserved_va",
    "status": "active",
    "account": {
      "bank": "Providus Bank",
      "bank_code": "101",
      "account_number": "9909876543",
      "account_name": "Acme Studio Ltd"
    }
  },
  "meta": { "request_id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f" }
}

open_banking — redirect

Returns a redirect URL only when the channel is live and a redirect URL has been configured for the deployment. Otherwise it fails with 400 invalid_request and Open banking is not available yet.

{
  "data": {
    "channel": "open_banking",
    "status": "pending",
    "redirect_url": "https://pay.example.com/session/abc123"
  },
  "meta": { "request_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70" }
}

card — not available

Card deposits have no acquirer wired. The endpoint fails rather than half-working:

{
  "error": {
    "code": "invalid_request",
    "message": "Card deposits are not available yet. No card provider is configured."
  },
  "request_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7081"
}

Why invalid_request and not coming_soon?

The deposits service throws an internal channel_not_available code, which is not part of the public error vocabulary. The public filter normalises it to invalid_request and preserves the explanatory message. Use GET /v1/channels — or POST /v1/cards, which does return coming_soon — when you need a machine-readable capability signal.

Response differences

Channel	status	Payload
collection_va	pending	account with expires_at
reserved_va	active	account without expiry
open_banking	pending	redirect_url only
card	—	400 invalid_request

The deposit response does not include a database id. If you need to read the account back later, use Collections (which returns id) or Reserved accounts.

Common errors

Status	Code	Cause
400	invalid_request	Unknown channel, currency unsupported by the channel, channel not live, missing amount for collection_va
401	unauthorized	Missing or invalid API key
403	insufficient_scope	Key lacks collections:write
429	rate_limited	Request budget exhausted
503	provider_error	The collection rail failed while opening the account