Response Format & Codes

Overview

All Wallet-as-a-Service (WaaS) API responses follow a standard JSON envelope, regardless of the endpoint or operation.

This consistent structure allows integrators to:

• Reliably detect success or failure
• Handle business-level errors cleanly
• Implement centralized response parsing
• Support observability and reconciliation

---

Standard Response Envelope

Every API response is wrapped in the following structure:

{
  "succeeded": true,
  "code": "200",
  "message": "successful request",
  "data": {},
  "pageMeta": {},
  "errors": {}
}

Response Envelope Fields

Each field in the response envelope has a defined responsibility and should be interpreted consistently across all endpoints.

Field	Type	Description
succeeded	boolean	Indicates whether the request was processed successfully at a business level
code	string	Response code representing either an HTTP status or a business/domain error
message	string	Human-readable explanation of the outcome
data	object	Contains the response payload for successful operations
pageMeta	object	Optional object containing detailed paged infomation about the data returned
errors	object	Optional object containing detailed error information

Interpretation Rules

• succeeded = true indicates a successful business operation
• succeeded = false indicates a failure, even if the HTTP status is 200
• code should always be used for programmatic decision-making
• message is intended for logging and debugging, not user display

---

Success Response Example

When an API request is processed successfully, the response follows the standard envelope and includes a populated data object.

{
  "succeeded": true,
  "code": "200",
  "message": "successful request",
  "data": {
    "walletId": "0701234567",
    "balance": 25000.0,
    "currency": "NGN"
  },
  "pageMeta": {},
  "errors": {}
}

---

Failure Response Example

When a request fails due to validation, compliance, or business rules, the API still returns the standard response envelope with succeeded set to false.

{
  "succeeded": false,
  "code": "25",
  "message": "Sanction screening flagged",
  "data": {},
  "pageMeta": {},
  "errors": {}
}

---

Success Message Formats

The following are the standard success messages returned in the message field for each endpoint:

Authentication & Onboarding

• Merchant Authentication: Merchant Authenticated successfully
• Load Wallet: Wallet Top-up Successful
• Validation: Pre-validation initiated successfully, kindly proceed to face verification with the provided url.
• Create Account: Account opening successful.
• Update Customer Details: Customer details updated successfully
• Upgrade Account: Request has been submitted for processing

Transactions

• Name Enquiry: Successfully retrieved account name
• Wallet to Wallet, Wallet to Access Bank, Wallet to Other Banks, Debit Wallet, Credit Wallet: Successfully completed transaction
• Fetch Banks: Successfully retrieved all bank details

HTTP Status Codes

The API uses standard HTTP status codes to indicate request-level outcomes such as authentication, authorization, or malformed requests.

However, HTTP status codes do not always represent business success or failure.

HTTP Code	Meaning	Description
200	OK	Request was received and processed
400	Bad Request	Invalid or missing request parameters
401	Unauthorized	Authentication failed or token missing
403	Forbidden	Client does not have access to the resource
404	Not Found	Requested resource does not exist
500	Internal Server Error	Server-side failure

Important Notes

• The JSON response envelope is returned even when the HTTP status is not 200
• Business failures may still return HTTP 200
• Always inspect the response code before determining success

Never rely solely on the HTTP status code to determine the outcome of an operation.

---

Business / Domain Error Codes

In addition to HTTP status codes, the API returns business and domain-specific error codes inside the response body.

These codes represent regulatory, validation, and operational outcomes and must be handled explicitly by client applications.

Common Business Error Codes

Code	Description
23	Suspended client or merchant
27	Account has already being opened for user.
31	Invalid account number
32	Cross-client posting not allowed
33	Same account transfer is invalid
34	Incorrect credit bank code, use wallet to Access bank
36	Merchant ID does not exist
37	Transaction reference not found
39	Error occurred while processing transaction
61	Name enquiry failed for account
78	Sanction screening flagged. Unable to process customer validation
87	Validation funds error
88	Insufficient validation balance
99	Generic failure

Usage Guidance

• Business error codes drive application logic, not HTTP status
• Some codes represent terminal failures (e.g. sanctions, suspension)
• Others may be recoverable through retries or user correction

Always design your system to branch logic based on the code field.

---

Error Handling Guidance

Client applications should implement structured error-handling logic based on the response envelope rather than HTTP status alone.

Recommended Handling Flow

1. Inspect the succeeded field
2. If false, evaluate the code
3. Apply business logic based on error category
4. Log the failure with identifiers for traceability

Retry Rules

• Do not retry blindly
• Always confirm whether the error is retryable
• Use status-check endpoints before re-initiating transactions

---