Virtual Cards

Overview

A business virtual card is a payment card you issue, on behalf of one of your customers, through your Hyparrow business account. The card is backed by a dedicated linked account and can be debit or prepaid. Because the card is created under your client credentials and tied to a customer, you can issue and track cards for many customers from a single integration. Typical uses include giving customers a spendable card against a wallet balance, or provisioning disposable cards for online payments.

Base URL: https://api.hyparrow.cloud/api/v1Business virtual card endpoints are authenticated with your API key pair:

X-API-Key: pk_live_xxxxxxxxxxxx
X-API-Secret: sk_live_xxxxxxxxxxxx

Test the full create-and-list flow against https://sandbox.hyparrow.cloud/api/v1 with your pk_test_ keys before issuing live cards.

Creating a card charges a flat per-card creation fee (default ₦500) to your wallet. If your wallet balance is too low, the request fails with a message telling you the exact amount to fund. Fees are denominated in kobo internally (₦500 = 50,000 kobo).

Card fields

A virtual card record contains:

Field	Description
`id`	Card UUID
`cardType`	`debit` or `prepaid`
`status`	`active`, `suspended`, or `terminated`
`nameOnCard`	Cardholder name printed on the card
`customerId`	The customer this card belongs to
`clientId`	Your business client ID
`accountId`	The linked account number backing the card
`accountType`	Linked account type (`current` / `savings`)
`pan`	Card number — returned in full only once, masked afterwards
`expiryDate`	Card expiry
`cvv` / `cvv2`	Security codes — returned only once at creation
`createdAt`	When the card was issued

The full PAN, CVV, and CVV2 are returned only once, in the create response. Every subsequent list or fetch returns a sanitized record with the PAN masked (e.g. ************1234) and the CVV fields cleared. Capture and store these securely at creation time — they cannot be retrieved again.

Create a business virtual card

POST /virtual-cards

Field	Required	Notes
`customerId`	yes	UUID of the customer the card is for
`cardType`	yes	`debit` or `prepaid`
`pin`	yes	Numeric card PIN
`nameOnCard`	yes	Cardholder name
`city`	yes	Billing city
`streetAddress`	no	Billing street address
`postalCode`	no	Billing postal code
`state`	no	Billing state

Fund your wallet

Ensure your wallet covers the per-card creation fee.

POST the card details

Send the customer ID, card type, PIN, and billing address.

Store the returned card secrets

The response includes full card details once. Persist them securely before moving on.

curl -X POST https://api.hyparrow.cloud/api/v1/virtual-cards \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "c1a2b3c4-d5e6-7a8b-9c0d-1e2f3a4b5c6d",
    "cardType": "debit",
    "pin": 1234,
    "nameOnCard": "ADA OBI",
    "streetAddress": "12 Marina Road",
    "city": "Lagos",
    "state": "Lagos",
    "postalCode": "101001"
  }'

Response

{
  "success": true,
  "message": "Virtual card created successfully. Save your card details — they will not be shown again.",
  "data": {
    "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "cardType": "debit",
    "status": "active",
    "nameOnCard": "ADA OBI",
    "customerId": "c1a2b3c4-...",
    "clientId": "1a2b3c4d-...",
    "accountId": "7012345678",
    "accountType": "20",
    "createdAt": "2026-06-30T11:30:00Z"
  },
  "card": {
    "pan": "5061234567890123",
    "expiryDate": "06/29",
    "cvv": "123",
    "cvv2": "456"
  }
}

The data object is the stored card record; the card object holds the sensitive details that are surfaced only on this response. Subsequent reads will not include card.

Common failures:

400 invalid customer ID — customerId is not a valid UUID.
Insufficient wallet balance — fund your wallet with the amount shown in the error.
400 for a missing required field (cardType, pin, nameOnCard, or city).

List business virtual cards

GET /virtual-cards returns the cards belonging to your business client. Pass an optional customerId query parameter to filter to a single customer. PANs are masked.

curl "https://api.hyparrow.cloud/api/v1/virtual-cards?customerId=c1a2b3c4-..." \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-...",
      "cardType": "debit",
      "status": "active",
      "nameOnCard": "ADA OBI",
      "customerId": "c1a2b3c4-...",
      "clientId": "1a2b3c4d-...",
      "accountId": "7012345678",
      "pan": "************0123",
      "expiryDate": "06/29",
      "createdAt": "2026-06-30T11:30:00Z"
    }
  ]
}

An invalid customerId value returns 400 invalid customer ID. Omit the parameter to list every card across all of your customers.

Getting Started

Identity

Customers

Accepting Payments

Payouts & Bills

Commerce

Crypto

Developer

Overview

Card fields

Create a business virtual card

Response

List business virtual cards

​Overview

​Card fields

​Create a business virtual card

​Response

​List business virtual cards

Overview

Card fields

Create a business virtual card

Response

List business virtual cards