> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onecluster.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API Changelog

> Public changes to the UnionVelocity API, newest first.

Every public-facing change to the UnionVelocity API lives here, newest first. Each entry shows the version, the release date, and a complete list of what changed for you.

We follow semantic versioning:

* **Major** (v1 to v2): breaking changes. You'll need to update your integration before the cutover date.
* **Minor** (v1.0 to v1.1): new features added in a backwards-compatible way. Your existing calls keep working.
* **Patch** (v1.0.0 to v1.0.1): bug fixes that don't change behaviour you can observe from outside.

<Info>
  Breaking changes get a minimum 90-day deprecation notice before the old behaviour is removed. We email the technical contact on your partner account and post the notice here.
</Info>

***

## Documentation refresh, 30 June 2026

This release is documentation-only. No API behaviour changed.

* **Renamed:** the product is now **UnionVelocity** (previously Pegasus). The brand change is visible in the docs, the marketing site, and partner-facing UI. Your API keys, base URLs, and integration code do not change.
* **Portal-only flows moved out of the public API reference.** Onboarding, API key management, and production access were never meant to be called from your code: they happen in the partner portal at [ubn-ui.onecluster.co](https://ubn-ui.onecluster.co). The endpoint pages have been removed from the public docs. The portal flows themselves haven't changed.
* **Sandbox base URL canonicalised:** the sandbox is reached at `https://api-partner.onecluster.co`. The legacy `dev-api.onecluster.co` host is being retired. Update your sandbox config if you still point at the old host.
* **Editorial refresh:** clearer language, fewer hedges, more direct examples. If a page reads better than the last time you visited, that's why.
* **New:** [System Status](/resources/status) page with a link to [status.onecluster.co](https://status.onecluster.co) for live operational health.

***

## v1.1.0, 26 April 2026

### Billing & Wallet

* **New:** prepaid pay-as-you-go billing with a lien-capture-release model on every chargeable call.
* **New:** wallet is auto-created on go-live approval, with a permanent Virtual Account for funding.
* **New:** `GET /api/v1/billing/wallet` returns your wallet balance and VA funding details.
* **New:** `GET /api/v1/billing/statement` returns a paginated wallet statement with per-endpoint cost tracking.
* **New:** `GET /api/v1/billing/pricing` returns the current per-call pricing table.
* **New:** `402 Payment Required` is returned when your wallet balance is below the cost of the call. Top up and retry.
* **Changed:** sandbox base URL is now `https://api-partner.onecluster.co`. Production remains `https://api.onecluster.co`.

***

## v1.0.0, 25 March 2026

**Initial public release of the UnionVelocity platform.**

<AccordionGroup>
  <Accordion title="KYC Verification">
    Automated identity verification for individuals and businesses. PII is masked in every response.

    * `POST /api/v1/kyc/bvn/verify`: verify a Bank Verification Number against the central bank registry. Returns the name-match result and masked identity fields.
    * `POST /api/v1/kyc/nin/verify`: verify a National Identification Number against the NIMC database. Returns the name-match result and masked identity fields.
    * `POST /api/v1/kyc/cac/lookup`: look up a company by its Corporate Affairs Commission registration number. Returns company status, registered address, and director information.

    BVN, NIN, date of birth, and phone numbers are never returned in full.
  </Accordion>

  <Accordion title="Virtual Accounts">
    Create and manage virtual bank accounts issued under Union Bank's licence.

    * `POST /api/v1/accounts`: create a virtual account. Two types:
      * **STATIC**: a permanent account number assigned to a customer. Right for wallets, savings products, and any case where the customer has a stable account identity.
      * **DYNAMIC**: a single-use account number for one specific expected payment. Closes after the payment arrives or after a configurable timeout.
    * `GET /api/v1/accounts/{accountNumber}`: retrieve account details and current balance.
    * `GET /api/v1/accounts/{accountNumber}/statement`: paginated transaction history.
  </Accordion>

  <Accordion title="Payments">
    Send outbound transfers across the Nigerian interbank network.

    * `POST /api/v1/payments/account-enquiry`: confirm a destination account name before sending. Always do this first; you'll catch typos before money moves.
    * `POST /api/v1/payments/transfer`: initiate an outbound transfer. Two schemes:
      * **NIP (NIBSS Instant Payment)**: real-time, 24/7, seconds to settle. Maximum ₦10,000,000 per transaction.
      * **NEFT (Nigeria Electronic Funds Transfer)**: scheduled batch, same-day or next-day settlement. No per-transaction maximum.
    * Idempotency is supported on every transfer. Send the same request with the same idempotency key twice, you'll get back the original response, not a second transaction.
    * `GET /api/v1/payments/{reference}/status`: poll the final outcome.
  </Accordion>

  <Accordion title="Collections">
    Receive inbound payments from customers into your virtual accounts.

    * Each virtual account can receive inbound NIP transfers from any Nigerian bank.
    * Real-time webhook notifications fire on every incoming credit.
    * `GET /api/v1/collections/accounts/{accountNumber}/transactions`: query received payments with sender name, sender bank, and narration.
  </Accordion>

  <Accordion title="Webhooks">
    Event-driven notifications for asynchronous operations.

    * `POST /api/v1/collections/webhooks`: register a webhook endpoint URL for your partner account.
    * `GET /api/v1/collections/webhooks`: list all registered webhook endpoints.
    * `DELETE /api/v1/collections/webhooks/{webhookId}`: remove a webhook endpoint.
    * `GET /api/v1/collections/webhooks/deliveries`: delivery history with HTTP status codes, response times, and retry attempts.
    * Automatic retry with exponential backoff: failed deliveries are retried up to 5 times over 24 hours.
    * Every delivery is signed with HMAC-SHA256 via the `X-UBN-Signature` header. Verify it to confirm authenticity.

    **Events at launch:**

    | Event                        | Trigger                                    |
    | ---------------------------- | ------------------------------------------ |
    | `payment.transfer.success`   | Outbound transfer completed                |
    | `payment.transfer.failed`    | Outbound transfer failed                   |
    | `collection.received`        | Inbound credit landed in a virtual account |
    | `kyc.verification.completed` | A KYC check returned a result              |
    | `account.created`            | New virtual account provisioned            |
  </Accordion>

  <Accordion title="Sandbox Environment">
    Full production-equivalent testing environment.

    * Sandbox base URL: `https://api-partner.onecluster.co`
    * Pre-configured test data for BVN, NIN, CAC, and account-number verification.
    * Same rate limits as production; backoff logic that works in sandbox works in production.
    * Instant transfer settlement. You don't wait for batch windows when developing.
  </Accordion>
</AccordionGroup>

### Security at launch

The following controls are active in every environment from day one:

| Control                     | Detail                                                                 |
| --------------------------- | ---------------------------------------------------------------------- |
| API key hashing             | Argon2id. Raw keys are never stored.                                   |
| Document encryption at rest | AES-256 on all uploaded KYB documents.                                 |
| Encryption in transit       | TLS 1.3 on every API endpoint.                                         |
| Mutual TLS (mTLS)           | Required for production payment and KYC calls.                         |
| Request signing             | HMAC-SHA256 on every payment and KYC request.                          |
| Environment isolation       | Sandbox and production share no data and no infrastructure.            |
| WORM audit logging          | Immutable record of every API call and data-access event.              |
| Circuit-breaker protection  | Automatic failure isolation for upstream payment-network dependencies. |

### Standards and compliance

| Standard                    | Status                                                                            |
| --------------------------- | --------------------------------------------------------------------------------- |
| OpenAPI 3.1.0 specification | Full spec published at `/api-reference/openapi.yaml`.                             |
| RFC 7807 Problem Details    | Every error response uses the standard `type`, `title`, `status`, `detail` shape. |
| NDPR compliance             | PII minimisation, consent capture, immutable audit trail.                         |
| CBN KYC guidelines          | BVN / NIN verification aligned to the current CBN KYC circular.                   |