Reserved accounts

A reserved account is a persistent NGN bank account assigned to a customer. Unlike a collection, it has no amount and no expiry: the customer can keep paying into the same account number, and each transfer is credited to your wallet.

Use reserved accounts for customers who pay repeatedly — wallets, subscriptions, or balances you hold on their behalf.

Endpoints

Method	Path	Scope	Success
POST	/v1/reserved-accounts	collections:write	201
GET	/v1/reserved-accounts	read	200
GET	/v1/reserved-accounts/:id	read	200

Create a reserved account

POST /v1/reserved-accounts

Field	Type	Required	Notes
currency	string	Yes	Must be NGN
reference	string	Yes	Your customer reference. Used for de-duplication
customer	object	Yes	See below
customer.name	string	Yes	Split into first/last name for the rail
customer.email	string	No	Valid email if present; defaults to an internal address
customer.phone	string	No	Stored with the account metadata
metadata	object	No	Stored under metadata.extra

curl -X POST https://api.nuansis.co/v1/reserved-accounts \
  -H "Authorization: Bearer $NUANSIS_API_KEY" \
  -H "Idempotency-Key: customer-4471-reserved" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "reference": "customer-4471",
    "customer": {
      "name": "Adaeze Okafor",
      "email": "ada@example.com"
    }
  }'

201 Created

{
  "data": {
    "id": 913,
    "status": "active",
    "currency": "NGN",
    "reference": "customer-4471",
    "account": {
      "bank": "Providus Bank",
      "bank_code": "101",
      "account_number": "9909876543",
      "account_name": "Adaeze Okafor"
    },
    "created_at": "2026-10-18T10:26:07.412Z"
  },
  "meta": { "request_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" }
}

De-duplication by reference

If a reserved account with the same reference already exists in the workspace, the existing account is returned. The check is scoped to kind: "reserved", so it does not collide with a collection that used the same reference.

Status values

Status	Meaning
active	The account can receive transfers
inactive	The account has been deactivated

There is no API to deactivate or delete a reserved account. Contact support if an account must be closed.

List reserved accounts

GET /v1/reserved-accounts

Returns an array of reserved accounts, newest first, wrapped in data. There is no pagination parameter on this endpoint; the full set for the workspace is returned.

{
  "data": [
    {
      "id": 913,
      "status": "active",
      "currency": "NGN",
      "reference": "customer-4471",
      "account": {
        "bank": "Providus Bank",
        "bank_code": "101",
        "account_number": "9909876543",
        "account_name": "Adaeze Okafor"
      },
      "created_at": "2026-10-18T10:26:07.412Z"
    }
  ],
  "meta": { "request_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e" }
}

Get a reserved account

GET /v1/reserved-accounts/:id

Returns a single account in the same shape as the create response. An unknown id, or one from another workspace, returns 404 not_found.

{
  "error": { "code": "not_found", "message": "not_found" },
  "request_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
}

Common errors

Status	Code	Cause
400	invalid_request	Missing field, currency other than NGN, invalid email
401	unauthorized	Missing or invalid API key
403	insufficient_scope	Key lacks collections:write on create
404	not_found	Unknown id
429	rate_limited	Request budget exhausted
503	provider_error	The collection rail could not open the account

Webhooks

reserved_account.created fires after a new account is persisted:

{
  "id": 913,
  "reference": "customer-4471",
  "account_number": "9909876543",
  "bank": "Providus Bank",
  "customer": { "name": "Adaeze Okafor", "email": "ada@example.com" }
}

The event is not fired when the create call returns an existing account. See Webhooks.