API Overview

The Zentra API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

All API requests should be made to:

https://sandbox.api.usezentra.com

The reviewed gateway contract is rooted at /api/v1/*. When an older page in this workspace still shows a legacy /v1/* example, prefer the reviewed route manifest, the reviewed OpenAPI bundle, and the stronger route-specific pages until that leaf page is reconciled.

Platform Model

Zentra is now documented as a primitive-first BaaS:

reviewed money movement primitives: transfers, payments, and webhook delivery
reviewed optional and tenant-gated rails: identity, virtual accounts, card issuing, and billpay
internal primitives and controls: auth, fees, routing, and operator tooling
reference accelerators: higher-level product flows you can build yourself on top of the primitives

The reviewed public route manifest currently includes transfers, payments, identity, cards, virtual accounts, billpay, and webhooks. Draft, tenant-specific, or reference namespaces still include customers, wallets, analytics, plans, and subscriptions.

Current Documentation Status

The API docs in this workspace are not uniformly complete yet. Some endpoint pages still exist as explicit placeholders while the reviewed OpenAPI contract and the stronger endpoint pages continue to expand. Today, the most trustworthy endpoint-level documentation is concentrated in:

payments
- charge
- refund
- verify
transfers
- overview
- create
- get
- list
- bulk
- resolve-account
- banks
cards
- overview
- create
- list
- fund
- balance
- funding-history
- auto-reload
- jit-fund
- security
- lock
- unlock
virtual accounts
- overview
- create
- list
- get
- close
webhooks
- overview
- configure
- verify-signature
- events

The remaining placeholder backlog is concentrated in draft, tenant-specific, or reference-only namespaces and should not be read as proof of reviewed public support:

customers
wallets
analytics
plans
subscriptions
payments/initialize
a small set of identity endpoint pages that are reviewed but still tenant-gated and not yet documented in full page detail

If a page is explicitly labeled placeholder, tenant-specific, or draft, treat it as backlog or compatibility guidance, not as the endpoint contract itself. When a page and the reviewed route contract disagree, prefer the reviewed public OpenAPI surface, the reviewed route manifest, and the stronger route-specific pages in this workspace. This means the docs are useful as a source of truth for the reviewed surfaces above, but they are not yet complete enough to treat the entire API reference tree as fully implemented contract coverage.

API Versioning

The Zentra API uses versioning in the URL path. The current version is v1. When we make backwards-incompatible changes, we’ll release a new version. Backwards-compatible changes don’t require a new version:

Adding new endpoints
Adding new optional request parameters
Adding new properties to responses
Changing the order of properties in responses

Request Format

All POST, PUT, and PATCH requests must include a Content-Type: application/json header and a JSON body.

curl https://api.usezentra.com/api/v1/transfers \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": 10000,
    "destination_bank_code": "058",
    "destination_account_number": "0123456789",
    "reference": "TRF_123456"
  }'

Response Format

All responses are returned in JSON format with the following structure:

Success Response

{
  "success": true,
  "data": {
    "reference": "TRF_123456",
    "status": "processing",
    "amount_minor": 10000,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid email address",
    "field": "email",
    "status": 400
  }
}

HTTP Status Codes

Zentra uses conventional HTTP response codes:

Code	Meaning	Description
2xx	Success	Request succeeded
`200`	OK	Request successful
`201`	Created	Resource created successfully
`204`	No Content	Request successful, no content to return
4xx	Client Error	Error in the request
`400`	Bad Request	Invalid request format or parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key doesn’t have required permissions
`404`	Not Found	Resource not found
`422`	Unprocessable Entity	Validation errors
`429`	Too Many Requests	Rate limit exceeded
5xx	Server Error	Error on Zentra’s side
`500`	Internal Server Error	Something went wrong
`503`	Service Unavailable	API temporarily offline

Idempotency

To prevent duplicate operations (especially for financial transactions), use idempotency keys. Pass a unique idempotency_key in your request:

curl https://api.usezentra.com/api/v1/transfers \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": 10000,
    "destination_account_number": "0123456789",
    "destination_bank_code": "058",
    "idempotency_key": "unique_key_123"
  }'

If you retry a request with the same idempotency key, you’ll get the same response as the original request.

Idempotency keys are valid for 24 hours. After that, the same key can be reused.

Rate Limiting

API requests are subject to rate limits based on your plan:

Plan	Rate Limit
Sandbox	100 requests/minute
Starter	1,000 requests/minute
Growth	5,000 requests/minute
Enterprise	Custom

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

See Rate Limits for details.

Pagination

List endpoints return paginated results. Use page and limit parameters:

curl "https://api.usezentra.com/api/v1/transfers?page=2&limit=50" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 243,
    "pages": 5
  }
}

See Pagination for details.

Filtering & Sorting

Many list endpoints support filtering and sorting:

# Filter by status
GET /api/v1/transfers?status=completed

# Filter by date range
GET /api/v1/transfers?start_date=2024-01-01&end_date=2024-01-31

# Sort by created_at descending
GET /api/v1/transfers?sort=-created_at

Timestamps

All timestamps are returned in ISO 8601 format (UTC):

2024-01-15T10:30:00Z

Testing

Use our sandbox environment for testing:

Base URL: https://sandbox.api.usezentra.com
API Keys: Use keys starting with sk_sandbox_
Test Data: See Test Data for test cards, BVNs, etc.

Sandbox and production are completely separate environments. Data does not sync between them.

API Resources

Identity

Reviewed, tenant-gated verification rails and decisioning

Virtual Accounts

Optional add-on for inbound collection rails

Transfers

Primitive money movement and payout orchestration

Payments

Optional add-on for charges, refunds, and saved payment methods

Cards

Optional add-on for issuing and card controls

Webhooks

Real-time event notifications

Draft & Reference Namespaces

Customers

Draft customer overlays retained for compatibility

Wallets

Draft wallet overlays retained for compatibility

Analytics

Tenant-specific telemetry and reporting overlays

SDKs

Use our official SDKs for easier integration:

Support

Need help? We’re here for you:

Support routing: Support and escalation paths
Status Page: status.usezentra.com

Next Steps

Authentication

Learn how to authenticate requests

Errors

Understand error responses

Quickstart

Make your first API call

Webhooks

Set up event notifications

API Reference

Transfers

Payments

Identity

Virtual Accounts

Cards

Webhooks

Draft, Tenant-Specific, and Reference APIs

​API Overview

​Base URL

​Platform Model

​Current Documentation Status

​API Versioning

​Request Format

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Idempotency

​Rate Limiting

​Pagination

​Filtering & Sorting

​Timestamps

​Testing

​API Resources

Identity

Virtual Accounts

Transfers

Payments

Cards

Webhooks

​Draft & Reference Namespaces

Customers

Wallets

Analytics

​SDKs

​Support

​Next Steps

Authentication

Errors

Quickstart

Webhooks

API Overview

Base URL

Platform Model

Current Documentation Status

API Versioning

Request Format

Response Format

Success Response

Error Response

HTTP Status Codes

Idempotency

Rate Limiting

Pagination

Filtering & Sorting

Timestamps

Testing

API Resources

Draft & Reference Namespaces

SDKs

Support

Next Steps