Skip to main content
A customer is a person or business your business serves. Sakawave holds the identity record; you hold the relationship. Nothing about a customer moves money on its own — a customer becomes financially useful once you open a wallet account for them. Only business clients can manage customers. A non-business client receives 409 client_not_a_business on every operation here.

​
The object

type and jurisdiction cannot be changed after creation. Everything else in the table is mutable through PATCH, subject to the type rules.

​
Lifecycle

A customer has three states, and only two transitions. Active. Visible to reads, countable in lists, eligible to hold accounts and cards. Archived. Hidden, not deleted. The record disappears from GET and LIST — both answer 404 — while ledger history and completed transfers keep their references to it. Archiving also releases the customer’s externalReference and identity numbers, so those values can be reused by a new customer.
Archiving is terminal. A customer archived by mistake must be created again, which mints a new id, and the old id stays referenced by history.

​
What this service does not do

  • It does not verify anyone. Storing a BVN records that you hold one; it does not check it. Every customer sits at tier 1.
  • It does not hold money. Balances live on accounts, not customers.
  • It does not deduplicate people. Two customers with the same name and address are two customers. Uniqueness is enforced on externalReference and identity numbers, nothing else.
  • It does not delete. DELETE archives.

​
Events

Archiving emits nothing. If you mirror customers locally, reconcile archives by listing customers and treating an absent record as archived.

​
Next

Introduction

What the service is for, and when to reach for it.

Get started

One successful call in under ten minutes.

Setup and configuration

Keys, environments, limits, and webhook wiring.

Use cases

Complete flows, with the error branches that actually happen.