Transactions

Overview

A transaction is the canonical record of money moving into or out of your account. Almost every money-related action in Hyparrow produces one: a customer funding their virtual account, a bank transfer you send out, a bill payment, a card charge, an invoice being paid, or a paid verification check. You don’t create transactions directly. They are written for you when the underlying action happens, then updated as the bank network confirms the outcome. The Transactions endpoints let you list and read those records for reconciliation, reporting, and reacting to payments.

Every amount is in kobo, the minor unit of the Naira. 1 NGN = 100 kobo, so a transaction amount of 50000 means ₦500.00. The currency field is NGN.

Base URL & authentication

Item	Value
Base URL	`https://api.hyparrow.cloud/api/v1`
Auth header 1	`X-API-Key: pk_live_xxx`
Auth header 2	`X-API-Secret: sk_live_xxx`

Test against the sandbox first: send requests to https://sandbox.hyparrow.cloud/api/v1 with a pk_test_ key (and its matching sk_test_ secret). Sandbox transfers and payments generate real-shaped transactions you can list and fetch without moving live money.

The transaction record

Each transaction carries a stable id (UUID), a unique reference, a type, a status, and an amount in kobo. Optional link fields (customerId, invoiceId, productId, subscriptionId, receiptId) connect the transaction back to whatever produced it.

Transaction types

`type`	Meaning
`virtual_account`	Money received into a customer’s virtual account.
`bank_transfer`	An outbound transfer to a bank account.
`bill_payment`	A bill or utility payment.
`card_payment`	A card charge.
`account_inquiry`	A name/account lookup against the bank network.
`credit` / `debit`	A generic credit or debit to your balance.
`invoice_payment`	Payment against an invoice.
`product_purchase`	Payment for a product.
`subscription_payment`	A recurring subscription charge.
`verification_payment`	A paid verification (e.g. identity/account check).
`ussd_payment`	A payment initiated over USSD.
`virtual_card`	A virtual-card related transaction.
`transfer_fee`	A fee charged on a transfer.

Transaction statuses

`status`	Meaning
`pending`	Created, awaiting processing.
`processing`	In flight on the bank network.
`completed` / `success`	Money has moved successfully.
`failed`	The action did not complete.
`canceled`	The action was canceled before completion.

How transactions relate to other actions

Payments (virtual accounts): when a customer funds their virtual account, a virtual_account transaction is recorded and attributed to that customerId.
Transfers: sending money out creates a bank_transfer (and may add a separate transfer_fee), moving from pending to processing to completed/failed.
Verifications: a paid lookup produces a verification_payment (or account_inquiry) record so the spend is auditable.
Invoices, products, subscriptions: paying one links the transaction via invoiceId, productId, or subscriptionId.

Typical flow

An action happens

A customer pays into their virtual account, you send a transfer, or a verification runs. Hyparrow writes a transaction in pending.

The bank network processes it

The status advances to processing, then settles as completed/success or failed. A completedAt timestamp is set on success.

You list or fetch it

Poll GET /transactions (or fetch a single one by id) to reconcile, or react to the change via webhooks.

List transactions

GET /transactions Lists transactions for the authenticated account, newest first, with pagination and optional filters.

Query parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number.
`limit`	integer	`20`	Results per page.
`type`	string	—	Filter by a transaction type (e.g. `virtual_account`).
`status`	string	—	Filter by a status (e.g. `completed`).
`dateFrom`	string	—	Inclusive start date, `YYYY-MM-DD`.
`dateTo`	string	—	Inclusive end date, `YYYY-MM-DD`.

curl "https://api.hyparrow.cloud/api/v1/transactions?type=virtual_account&status=completed&page=1&limit=20" \
  -H "X-API-Key: pk_live_xxx" \
  -H "X-API-Secret: sk_live_xxx"

curl "https://api.hyparrow.cloud/api/v1/transactions?dateFrom=2026-06-01&dateTo=2026-06-30" \
  -H "X-API-Key: pk_live_xxx" \
  -H "X-API-Secret: sk_live_xxx"

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "b71e0c2d-9f48-4a1c-8e3b-2d6a7c4f1e90",
      "customerId": "9f1c2e6a-3b4d-4c8e-9a12-7d6f5b8c0e21",
      "type": "virtual_account",
      "status": "completed",
      "amount": 50000,
      "currency": "NGN",
      "reference": "HYP-TXN-20260630-0001",
      "description": "Inbound transfer to virtual account",
      "channel": "bank_transfer",
      "senderName": "Chidi Eze",
      "senderAccountNumber": "0123456789",
      "senderBankCode": "058",
      "metadata": {},
      "completedAt": "2026-06-30T10:02:11Z",
      "createdAt": "2026-06-30T10:02:05Z",
      "updatedAt": "2026-06-30T10:02:11Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

The pagination.totalPages value is derived from total and limit, so you can loop until page reaches totalPages.

Get a transaction

GET /transactions/{transactionId} Retrieves a single transaction by its UUID. The transaction must belong to your account.

curl "https://api.hyparrow.cloud/api/v1/transactions/b71e0c2d-9f48-4a1c-8e3b-2d6a7c4f1e90" \
  -H "X-API-Key: pk_live_xxx" \
  -H "X-API-Secret: sk_live_xxx"

Response

200 OK

{
  "success": true,
  "data": {
    "id": "b71e0c2d-9f48-4a1c-8e3b-2d6a7c4f1e90",
    "customerId": "9f1c2e6a-3b4d-4c8e-9a12-7d6f5b8c0e21",
    "type": "virtual_account",
    "status": "completed",
    "amount": 50000,
    "currency": "NGN",
    "reference": "HYP-TXN-20260630-0001",
    "description": "Inbound transfer to virtual account",
    "channel": "bank_transfer",
    "responseCode": "00",
    "responseMessage": "Successful",
    "senderName": "Chidi Eze",
    "senderAccountNumber": "0123456789",
    "senderBankCode": "058",
    "metadata": {},
    "completedAt": "2026-06-30T10:02:11Z",
    "createdAt": "2026-06-30T10:02:05Z",
    "updatedAt": "2026-06-30T10:02:11Z"
  }
}

For an inbound virtual_account payment, the senderName, senderAccountNumber, and senderBankCode fields tell you who paid. For outbound and other transaction types these may be absent.

Errors & edge cases

Status	When	Example `error`
`400 Bad Request`	`transactionId` is not a valid UUID.	`"invalid transaction ID"`
`401 Unauthorized`	Missing or invalid `X-API-Key` / `X-API-Secret`.	`"user not authenticated"`
`404 Not Found`	No transaction with that id belongs to your account.	`"transaction not found"`

{
  "success": false,
  "error": "invalid transaction ID"
}

Other things to keep in mind:

Transactions are immutable history — you read them, you never edit them. The bank network advances status and sets completedAt.
A transaction can sit in pending/processing briefly before settling; reconcile on completed/success or failed, not on creation.
Use reference (unique per transaction) as your idempotent key when matching Hyparrow records to your own ledger.
Filters combine: passing type, status, and a dateFrom/dateTo range narrows the list to transactions matching all of them.

Getting Started

Identity

Customers

Accepting Payments

Payouts & Bills

Commerce

Crypto

Developer

Overview

Base URL & authentication

The transaction record

Transaction types

Transaction statuses

How transactions relate to other actions

Typical flow

List transactions

Query parameters

Response

Get a transaction

Response

Errors & edge cases

​Overview

​Base URL & authentication

​The transaction record

​Transaction types

​Transaction statuses

​How transactions relate to other actions

​Typical flow

​List transactions

​Query parameters

​Response

​Get a transaction

​Response

​Errors & edge cases

Overview

Base URL & authentication

The transaction record

Transaction types

Transaction statuses

How transactions relate to other actions

Typical flow

List transactions

Query parameters

Response

Get a transaction

Response

Errors & edge cases