Money Transfer

Overview

The Money Transfer API sends funds from your Hyparrow wallet to any Nigerian bank account over the bank network. The flow is always the same: list the supported banks, resolve the recipient’s account name from their account number, initiate the transfer, then poll for the final status. When you initiate a transfer, Hyparrow debits the principal from your wallet before calling the bank network, then books the fee as a separate debit only after the network accepts the transfer. If the network rejects the transfer, the principal debit is automatically reversed, so a rejected transfer never leaves your wallet short. If the network does not answer (a timeout), the transfer is treated as submitted, never reversed on a guess, and its outcome comes by webhook. See Unknown outcome.

Base URL: https://api.hyparrow.cloud/api/v1Auth: every request requires X-API-Key and X-API-Secret headers.Sandbox: point at https://sandbox.hyparrow.cloud/api/v1 and use your pk_test_ key. Simulate outcomes with magic amounts, an amount ending in .01 is rejected at submission (the send returns 400, the principal is reversed, no fee is charged and transfer.reversed fires), and .99 stays pending (accepted, never settles) so you can test status polling. Everything else is accepted and later settles, firing transfer.settled.

Amounts are in kobo. All transfer amounts are integers in minor units passed as strings, "500000" means ₦5,000.00. Fees are quoted in Naira and charged on top of the principal.

The transfer flow

List banks

GET /money-transfer/banks returns supported banks. Each entry has a bankCode, use this exact value for inquiry and send.

Resolve the account name

POST /money-transfer/account-inquiry (or GET) with the account number and bank code returns the registered account name. Show it to the user to confirm.

Send

POST /money-transfer/send debits the wallet (principal first, then fee on success) and initiates the transfer over the bank network.

Poll status

GET /money-transfer/status?reference=<transferCode|clientReference> (or POST) returns the current status until it settles.

List banks

curl https://api.hyparrow.cloud/api/v1/money-transfer/banks \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET"

Response

{
  "success": true,
  "data": {
    "banks": [
      {
        "bankCode": "058",
        "code": "0001",
        "bankName": "Guaranty Trust Bank",
        "logo": "https://.../gtb.png"
      },
      {
        "bankCode": "044",
        "code": "0002",
        "bankName": "Access Bank",
        "logo": "https://.../access.png"
      }
    ]
  }
}

Always use the bankCode field (the CBN code) for account-inquiry and send. The separate code field is an internal identifier and is not used for transfers.

Resolve the account name

Confirm the recipient before you send. Supply the accountNumber and the bankCode from the bank list. This endpoint accepts both GET (query params) and POST (JSON body).

Account inquiry (GET)

curl "https://api.hyparrow.cloud/api/v1/money-transfer/account-inquiry?accountNumber=0123456789&bankCode=058" \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET"

Account inquiry (POST)

curl -X POST https://api.hyparrow.cloud/api/v1/money-transfer/account-inquiry \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "accountNumber": "0123456789", "bankCode": "058" }'

Response

{
  "success": true,
  "data": {
    "accountName": "JANE DOE",
    "accountNumber": "0123456789",
    "bankCode": "058"
  }
}

The accountName you get back is what you pass as recipientName when you send.

Account couldn’t be resolved. If the name lookup fails on every network, you get a 503 with a retry-friendly message instead of an error code. Do not proceed to send, re-check the account number and bank, then retry shortly:

{
  "success": false,
  "error": "We couldn't verify this account right now. Please double-check the account number and bank, then try again in a moment."
}

Send a transfer

POST /money-transfer/send initiates the transfer. The wallet is checked for the principal plus the fee up front; the principal is debited before the bank network is called, and the fee is debited only after the network accepts.

Request body

Field	Required	Description
`amount`	yes	Principal in kobo, as a string
`recipientAccount`	yes	Beneficiary account number
`recipientBankCode`	yes	`bankCode` from the bank list
`recipientName`	yes	Beneficiary name (from account inquiry)
`senderPhone`	yes	Sender phone number
`senderEmail`	yes	Sender email
`senderLastname`	yes	Sender last name
`senderOthernames`	yes	Sender other names
`narration`	no	Free-text note for the transfer
`clientReference`	no	Your own reference for this transfer, up to 128 characters. It is also the idempotency key. Strongly recommended, see below

Send a clientReference.Without one, the only handle on a transfer is the transferCode we return, so a send whose response you never receive (a timeout, a dropped connection, a crash between the call and your database write) leaves you holding nothing we can look up. GET /money-transfer/status answers 404 Transfer not found for a transfer that may well have been delivered, and from your side a settled payout is indistinguishable from one that never happened.With one, the transfer is resolvable by a reference you generated before the call, so it is recoverable no matter what happens to the response. It is stored against the transaction, echoed on the transfer.settled, transfer.failed and transfer.reversed webhooks, and accepted by the status endpoint in place of the transferCode.

Idempotency

A clientReference names exactly one transfer, for good. It is never expired or reused.

You send	You get
A new `clientReference`	A new transfer
The same `clientReference`, same `amount`, `recipientAccount` and `recipientBankCode`	`200` with the original transfer and `IdempotentReplay: true` (header `X-Idempotent-Replayed: true`). Nothing is sent again, whatever state the original is in
The same `clientReference` with a different amount or destination	`409` with `code: "CLIENT_REFERENCE_CONFLICT"`. Nothing is sent
Two identical requests at the same moment	One transfer. The check runs under the same wallet lock as the debit, so the second request waits and then gets the replay

A replay returns the transfer as it stands, including Status: "reversed" if the first attempt was rejected. To try again after a rejection, send a new clientReference.

409 Response

{
  "success": false,
  "error": "clientReference has already been used for a different transfer (amount or destination differs). Nothing was sent.",
  "code": "CLIENT_REFERENCE_CONFLICT",
  "transferCode": "14531719772800000"
}

You can also send an Idempotency-Key header, which works across all money routes. A key is remembered for 24 hours; a repeat with the identical body replays the first successful response, and a repeat with a different body gets 422 IDEMPOTENCY_KEY_REUSED. Only successful responses are remembered, so a request refused with a 4xx (for example insufficient balance) can be retried with the same key once the cause is fixed. For transfers, clientReference is the stronger guarantee: it never expires and it holds across keys.

Send

curl -X POST https://api.hyparrow.cloud/api/v1/money-transfer/send \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500000",
    "recipientAccount": "0123456789",
    "recipientBankCode": "058",
    "recipientName": "JANE DOE",
    "senderPhone": "08030000000",
    "senderEmail": "sender@example.com",
    "senderLastname": "Smith",
    "senderOthernames": "John",
    "narration": "Invoice 1042",
    "clientReference": "TXF_1787089056995_aa8c1807"
  }'

Response

{
  "success": true,
  "message": "Transfer initiated successfully and wallet debited",
  "data": {
    "TransferCode": "14531719772800000",
    "FeeClass": "default",
    "Fee": 2500,
    "TransactionID": "9f1c2b7e-2a3d-4f6a-8b1e-7c0d9e2f1a34",
    "WalletBalance": 1247500,
    "Status": "pending",
    "ClientReference": "TXF_1787089056995_aa8c1807",
    "responseCode": "00",
    "responseMessage": "Transaction Successful"
  }
}

Status: "pending" means accepted and not yet settled. The final outcome arrives on transfer.settled or transfer.failed, normally within about 10 minutes. Keep data.TransferCode, it is the reference you use to check status. If you sent a clientReference, you can check status with that instead and do not need to have received this response at all.

Wallet debit and fees

The total debited is principal + fee:

The wallet must cover the principal and the fee, or the send is rejected before anything is charged.
The principal is debited first (atomically, with a row lock) so funds can’t leak if the network call partially fails.
The fee is a flat amount based on your transfer fee class and the amount tier. It is booked as a separate debit and only after the network accepts the transfer, a failed or reversed transfer is never charged a fee.

data.Fee is the fee in kobo, data.FeeClass is the fee class applied, and data.WalletBalance is your remaining balance after principal + fee.

Fee schedule

GET /money-transfer/fee-class returns the fee ladder for your own account, so you can quote the fee before sending and reconcile it after.

Fee class

curl https://api.hyparrow.cloud/api/v1/money-transfer/fee-class \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET"

Response

{
  "success": true,
  "feeClass": "default",
  "data": [
    { "max": 10000,  "fee": 25 },
    { "max": 39000,  "fee": 35 },
    { "max": 50000,  "fee": 47 },
    { "max": 100000, "fee": 58 },
    { "max": 150000, "fee": 69 },
    { "max": null,   "fee": 77 }
  ]
}

Field	Description
`feeClass`	The class assigned to your account. Everyone is on `default` unless Hyparrow moves you to another schedule.
`data[].max`	Inclusive upper bound of the band, in Naira. `null` marks the top tier, which applies to everything above the last band.
`data[].fee`	Flat fee for that band, in Naira.

Tiers come back ordered ascending: to price a transfer, convert the principal to Naira and take the fee of the first band whose max is null or >= amount. A ₦5,000 transfer on the response above costs ₦25; a ₦200,000 transfer costs ₦77.

Read the ladder, don’t hardcode it. Fee tiers are tunable at runtime and your class can change, so a copied table will silently drift. Fetch this endpoint (cache it briefly if you like) and quote from the response. Note the unit switch: transfer amounts are in kobo, but the fee ladder is in Naira, data.Fee on the send response is in kobo.

Check status

GET /money-transfer/status?reference=<transferCode> (or POST with a JSON body) returns both Hyparrow’s local transaction record and the latest network status. reference accepts either the transferCode from the send response or the clientReference you sent with the transfer. Both are scoped to the calling merchant: you can only ever read your own transfers, by either name for them. Looking up by clientReference is what makes a transfer recoverable when the send response was lost.

Status

curl "https://api.hyparrow.cloud/api/v1/money-transfer/status?reference=14531719772800000" \
  -H "X-API-Key: $HYPARROW_KEY" \
  -H "X-API-Secret: $HYPARROW_SECRET"

Response

{
  "success": true,
  "data": {
    "transaction": {
      "id": "9f1c2b7e-2a3d-4f6a-8b1e-7c0d9e2f1a34",
      "reference": "14531719772800000",
      "amount": 500000,
      "fee": 2500,
      "currency": "NGN",
      "status": "success",
      "settlementStatus": "delivered",
      "type": "bank_transfer",
      "responseCode": "90000",
      "responseMessage": "Successful",
      "createdAt": "2026-06-30T10:00:00Z",
      "completedAt": "2026-06-30T10:00:05Z"
    },
    "provider": {
      "ResponseCode": "90000",
      "TransactionResponseCode": "90000",
      "TransactionStatus": "Completed"
    }
  }
}

Read settlementStatus to know where the money is:

`settlementStatus`	Meaning
`pending`	Debited and submitted; no verdict from the network yet
`delivered`	The beneficiary was credited
`failed`	Declined downstream. The debit stands until it is reversed
`reversed`	The money was credited back to your wallet

status is the ledger row’s own state and reads success from the moment of the debit, so it does not tell you whether the transfer landed. provider is the network’s live answer, fetched on each call.

Edge cases

Insufficient balance. If the wallet can’t cover principal + fee, the send is rejected before any debit, and the error spells out the shortfall:

{
  "success": false,
  "error": "Insufficient wallet balance. Available: ₦40.00, Required: ₦5,025.00 (₦5,000.00 transfer + ₦25.00 fee)"
}

Rejected transfer is reversed. If the bank network refuses the transfer at submission, Hyparrow credits the principal back to your wallet straight away (a reversal transaction referenced REV_<code>), charges no fee, sends transfer.reversed, and returns 400 (or 502 if the request never left Hyparrow). The transfer’s settlementStatus is reversed.

{
  "success": false,
  "error": "Transfer rejected by network",
  "transferCode": "14531719772800000",
  "status": "reversed",
  "data": { }
}

Unknown outcome (202)

If the bank network does not answer (a timeout, a dropped connection, a 5xx), the transfer may or may not have gone through, and refunding on a guess is how a payout ends up sent twice. So Hyparrow treats it as submitted: the principal and fee stay debited and you get 202 Accepted with the transferCode.

202 Response

{
  "success": true,
  "message": "Transfer submitted but the bank network did not confirm receipt. Do not resend: the final outcome will arrive on transfer.settled or transfer.failed, or query GET /money-transfer/status with this transferCode.",
  "data": {
    "TransferCode": "14531719772800000",
    "Status": "pending",
    "Fee": 2500
  }
}

Do not resend. Wait for the webhook or poll status. If the network never received it, the transfer is failed and reversed (principal and fee) after review, and transfer.reversed tells you.

A pending transfer (a .99 amount in sandbox, or a slow settlement in production) has been accepted but not yet settled. Poll /money-transfer/status until settlementStatus moves to delivered, failed or reversed, or wait for the webhook. The principal stays debited while pending.

Getting Started

Identity

Customers

Accepting Payments

Payouts & Bills

Commerce

Crypto

Developer

Overview

The transfer flow

List banks

Resolve the account name

Send a transfer

Request body

Idempotency

Wallet debit and fees

Fee schedule

Check status

Edge cases

Unknown outcome (202)

​Overview

​The transfer flow

​List banks

​Resolve the account name

​Send a transfer

​Request body

​Idempotency

​Wallet debit and fees

​Fee schedule

​Check status

​Edge cases

​Unknown outcome (202)

Overview

The transfer flow

List banks

Resolve the account name

Send a transfer

Request body

Idempotency

Wallet debit and fees

Fee schedule

Check status

Edge cases

Unknown outcome (202)