Customers

A FossaPay customer represents an individual end user served by your business. The customer becomes the owner of customer-scoped NGN and stablecoin wallets and is isolated to the merchant that created it.

The Customers API does not create business customers. The only accepted type is individual.

Customer lifecycle

Create the individual

Submit the customer’s identity, contact, and residential information to POST /api/v1/customers.

Store the customer ID

Persist the returned FossaPay UUID alongside your own customer identifier.

Provision a wallet

Create an NGN wallet or stablecoin wallet using the customer UUID.

Retrieve and reconcile

Retrieve the customer by UUID or use the paginated list endpoint for operational search and administration.

Creating a customer does not automatically create a wallet or bank account. Wallet provisioning is a separate API operation.

Customer type

Every external customer request must include:

{
  "type": "individual"
}

The field remains required for contract compatibility. Any other value is rejected with HTTP 422 before account creation begins. Do not send a business name as a customer name. Your FossaPay merchant account represents the business; records created through this API represent the individuals that business serves.

Name requirements

The external API accepts up to three personal names, with one name in each field:

Field	Requirement
`firstName`	Required; exactly one given name
`middleName`	Optional; exactly one middle name
`lastName`	Required; exactly one family name

Use this structure:

{
  "firstName": "John",
  "middleName": "Michael",
  "lastName": "Doe"
}

Do not combine multiple names in one field. For example, lastName: "Michael Doe" is invalid. Each name may contain Unicode letters and combining marks. A hyphen, straight apostrophe, or typographic apostrophe may join parts of the same name. Spaces, numbers, and other punctuation are rejected. Leading and trailing whitespace is removed before validation.

There is no Business fallback in the external Customers API. Missing or invalid personal names cause the request to fail instead of substituting a business label.

Required information

Field	Requirement
`firstName`	One valid given name
`middleName`	Optional; one valid middle name
`lastName`	One valid family name
`emailAddress`	Non-empty customer email address; unique within your merchant account
`mobileNumber`	Non-empty customer phone number
`dateOfBirth`	Date string in `YYYY-MM-DD` format
`address`	Non-empty residential address
`city`	Non-empty city of residence
`country`	Supported country
`type`	Must be exactly `individual`

The request body is allowlisted. Unknown fields are rejected rather than silently stored or forwarded.

Create a customer

curl --request POST \
  --url https://api-production.fossapay.com/api/v1/customers \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "John",
    "middleName": "Michael",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "mobileNumber": "+2348012345678",
    "dateOfBirth": "1990-08-15",
    "address": "123 Example Street",
    "city": "Lagos",
    "country": "Nigeria",
    "type": "individual"
  }'

An HTTP 201 response returns the FossaPay customer record:

{
  "status": "success",
  "statusCode": 201,
  "message": "Customer created successfully",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "firstName": "John",
    "middleName": "Michael",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "mobileNumber": "+2348012345678",
    "dob": "1990-08-15",
    "address": "123 Example Street",
    "customerType": "individual",
    "businessId": "22222222-2222-4222-8222-222222222222",
    "createdAt": "2026-09-15T09:00:00+01:00"
  }
}

Store data.id; wallet creation and customer-funded transfer operations require this UUID. Notice that the request field is dateOfBirth, while the response field is dob.

FossaPay currently supports production access only. This request creates a live customer record.

Data handling

FossaPay stores the customer information required to identify the individual and operate the account. During production customer creation:

personal names, date of birth, address, city, customer type, and country identifiers are used for account provisioning;
emailAddress and mobileNumber are retained by FossaPay and are not used for bank account provisioning; and
arbitrary or unknown request properties are rejected and are not forwarded.

Collect only information you are authorized to process. Treat customer identity and contact fields as sensitive personal data throughout your systems.

List customers

GET /api/v1/customers returns only customers owned by the authenticated merchant.

Parameter	Default	Rules
`page`	`1`	Integer greater than or equal to `1`
`limit`	`10`	Integer from `1` to `100`
`search`	Empty	Searches first name, last name, and email address
`sortBy`	`createdAt`	`createdAt`, `firstName`, `lastName`, or `emailAddress`
`sortOrder`	`DESC`	`ASC` or `DESC`

Use the list endpoint for administrative search and pagination. When you already have the customer UUID, use GET /api/v1/customers/{customerId} instead.

Ownership and access

Customer operations are merchant-scoped. An API key can retrieve only customers associated with its merchant account. A UUID obtained from another merchant does not grant access to that record. Persist your own user-to-customer mapping. Do not repeatedly search by personal information to rediscover a customer ID. The public Customers API currently provides create, list, and retrieve operations. It does not expose customer update or deletion endpoints.

Errors and safe retries

Status	Typical cause	Action
`400`	Duplicate email for the merchant, unsupported country, or downstream customer-creation rejection	Correct the conflict or provider requirement before retrying
`401`	Missing or invalid API key	Correct authentication
`404`	Customer UUID not found for the authenticated merchant	Verify your stored merchant/customer mapping
`422`	Missing field, unknown field, invalid name, invalid date format, or a `type` other than `individual`	Correct the request body before retrying
`5xx`	Temporary FossaPay or provider failure	Reconcile before attempting the write again

Customer creation does not provide idempotency semantics. If the connection fails after submission, search your merchant’s customers using the unique email address before retrying. If no record appears but the outcome remains uncertain, retain the request timestamp and contact support instead of repeatedly submitting the same identity.

Operational checklist

Represent only individual end users through the Customers API.
Send no more than one personal name in each supported name field.
Set type to individual.
Keep email addresses unique within your merchant account.
Persist the returned FossaPay customer UUID with your own user ID.
Keep API keys and personal data out of client-side code and unnecessary logs.
Reconcile an ambiguous create request before retrying.
Create the required wallet only after customer creation succeeds.

API reference

Operation	Endpoint	Reference
Create a customer	`POST /api/v1/customers`	Create customer
List customers	`GET /api/v1/customers`	Get all customers
Retrieve a customer	`GET /api/v1/customers/{customerId}`	Get customer by ID

Getting Started

Core Concepts

Guides

AI Tools

Customer lifecycle

Customer type

Name requirements

Required information

Create a customer

Data handling

List customers

Ownership and access

Errors and safe retries

Operational checklist

API reference

Next steps

NGN wallets

Crypto wallets

​Customer lifecycle

​Customer type

​Name requirements

​Required information

​Create a customer

​Data handling

​List customers

​Ownership and access

​Errors and safe retries

​Operational checklist

​API reference

​Next steps

NGN wallets

Crypto wallets

Customer lifecycle

Customer type

Name requirements

Required information

Create a customer

Data handling

List customers

Ownership and access

Errors and safe retries

Operational checklist

API reference

Next steps