Subscriptions

Overview

A subscription is a recurring billing agreement that links a customer to one of your products at a fixed interval. Hyparrow tracks the billing period, the next billing date, and a complete payment history for each subscription. A subscription always belongs to a customer and a product, and bills in one of these intervals:

Interval	Bills every
`daily`	1 day
`every_3_days`	3 days
`weekly`	7 days
`biweekly`	14 days
`monthly`	1 month
`quarterly`	3 months
`biannual`	6 months
`yearly`	1 year

Base URL: https://api.hyparrow.cloud/api/v1Authenticate every request with both headers:

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

Use https://sandbox.hyparrow.cloud/api/v1 with pk_test_ keys to dry-run a full billing cycle — generate a virtual account, simulate a transfer, and confirm the status moves to active without moving real money.

Subscription amounts in API responses are in naira (e.g. 4500.00), derived from the product price. Where you reconcile against transactions or webhook deliveries elsewhere in the Hyparrow API, money is denominated in kobo (1 naira = 100 kobo).

Lifecycle

A subscription moves through a small set of states:

pending_payment

Created but not yet paid. No service period has started. This is the initial status of every new subscription.

active

The first payment has been collected. currentPeriodStart, currentPeriodEnd, and nextBillingAt are set, and the subscription will bill again at the interval you chose.

canceled

Cancelled by you via the cancel endpoint. Billing stops; no further renewals are attempted.

expired

A renewal was missed and the grace window (graceDays, default 3) elapsed without payment.

Create a subscription

POST /subscriptions/

Field	Required	Notes
`customerId`	yes	UUID of an existing customer
`productId`	yes	UUID of the product to bill
`interval`	yes	One of the billing intervals above
`paymentMethod`	no	`card`, `manual`, or `va` (defaults to `va`)
`graceDays`	no	Days after a missed payment before expiry
`tax_direction`	no	`merchant` (default) or `customer`
`checkoutCallbackUrl`	no	URL notified when a checkout payment changes status
`metadata`	no	Arbitrary key/value object

curl -X POST https://api.hyparrow.cloud/api/v1/subscriptions/ \
  -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",
    "productId": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "interval": "monthly",
    "graceDays": 3,
    "tax_direction": "merchant"
  }'

{
  "success": true,
  "message": "Subscription created",
  "data": {
    "id": "5d6e7f80-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "customerId": "c1a2b3c4-...",
    "productId": "8f1c2d3e-...",
    "interval": "monthly",
    "amount": 4500.00,
    "currency": "NGN",
    "paymentMethod": "va",
    "status": "pending_payment",
    "graceDays": 3,
    "createdAt": "2026-06-30T10:20:00Z"
  }
}

The subscription starts in pending_payment. To activate it, collect the first payment — usually by generating a virtual account (below).

Generate a virtual account to collect payment

A virtual account (VA) is a temporary, dedicated bank account number. Your customer transfers the exact subscription amount to it; once the transfer lands, Hyparrow records the payment and moves the subscription to active. POST /subscriptions/{subscriptionId}/generate-va expiryMinutes must be one of 10, 15, or 30.

Generate the account

Call generate-va. You receive an account number, bank name, and an expiry timestamp.

Show it to the customer

Display the account details and the exact amount. Transfers must arrive before expiresAt.

Wait for confirmation

When the transfer settles, the subscription becomes active and a payment is recorded. If you have a webhook configured, a subscription.payment.completed event is delivered.

curl -X POST https://api.hyparrow.cloud/api/v1/subscriptions/5d6e7f80-.../generate-va \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "expiryMinutes": 30 }'

{
  "success": true,
  "message": "Virtual account generated — pay the exact amount before it expires",
  "data": {
    "id": "9a0b1c2d-...",
    "subscriptionId": "5d6e7f80-...",
    "accountNumber": "7012345678",
    "accountName": "HYPARROW / ACME STORE",
    "bankName": "Sterling Bank",
    "bankCode": "232",
    "expiresAt": "2026-06-30T10:50:00Z",
    "isActive": true
  }
}

Customers must transfer the exact amount. The account expires at expiresAt; after that you must generate a fresh one.

Fetch the active virtual account

GET /subscriptions/{subscriptionId}/va returns the current active VA (useful for re-displaying details), or 404 if none is active.

curl https://api.hyparrow.cloud/api/v1/subscriptions/5d6e7f80-.../va \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

Mark a subscription as paid

For payments collected outside the VA flow (for example a confirmed manual bank transfer), record the payment directly with POST /subscriptions/{subscriptionId}/pay. This advances the billing period and activates the subscription.

curl -X POST https://api.hyparrow.cloud/api/v1/subscriptions/5d6e7f80-.../pay \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "MANUAL-2026-0042", "payerName": "Ada Obi" }'

{
  "success": true,
  "message": "Subscription marked as paid",
  "data": {
    "id": "p1a2b3c4-...",
    "subscriptionId": "5d6e7f80-...",
    "amount": 4500.00,
    "currency": "NGN",
    "reference": "MANUAL-2026-0042",
    "payerName": "Ada Obi",
    "paymentSource": "manual",
    "periodStart": "2026-06-30T10:55:00Z",
    "periodEnd": "2026-07-30T10:55:00Z",
    "paidAt": "2026-06-30T10:55:00Z"
  }
}

Cancel a subscription

POST /subscriptions/{subscriptionId}/cancel stops all future billing.

curl -X POST https://api.hyparrow.cloud/api/v1/subscriptions/5d6e7f80-.../cancel \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

{
  "success": true,
  "message": "Subscription canceled",
  "data": { "id": "5d6e7f80-...", "status": "canceled", "canceledAt": "2026-06-30T11:00:00Z" }
}

Get and list subscriptions

curl https://api.hyparrow.cloud/api/v1/subscriptions/5d6e7f80-... \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

curl "https://api.hyparrow.cloud/api/v1/subscriptions/?status=active&page=1&limit=20" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

The list endpoint supports page, limit, and a status filter, and returns pagination metadata:

{
  "success": true,
  "data": [ { "id": "5d6e7f80-...", "interval": "monthly", "status": "active", "amount": 4500.00 } ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Payment history

GET /subscriptions/{subscriptionId}/payments lists every recorded payment for a subscription, paginated. Each entry shows the amount, reference, payer, payment source, and the billing period it covers.

curl "https://api.hyparrow.cloud/api/v1/subscriptions/5d6e7f80-.../payments?page=1&limit=20" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

{
  "success": true,
  "data": [
    {
      "id": "p1a2b3c4-...",
      "subscriptionId": "5d6e7f80-...",
      "amount": 4500.00,
      "currency": "NGN",
      "reference": "MANUAL-2026-0042",
      "payerName": "Ada Obi",
      "paymentSource": "manual",
      "periodStart": "2026-06-30T10:55:00Z",
      "periodEnd": "2026-07-30T10:55:00Z",
      "paidAt": "2026-06-30T10:55:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

To be notified of renewals automatically rather than polling this endpoint, configure a webhook URL and listen for the subscription.payment.completed event. See the Webhooks guide.

Getting Started

Identity

Customers

Accepting Payments

Payouts & Bills

Commerce

Crypto

Developer

Overview

Lifecycle

Create a subscription

Generate a virtual account to collect payment

Fetch the active virtual account

Mark a subscription as paid

Cancel a subscription

Get and list subscriptions

Payment history

​Overview

​Lifecycle

​Create a subscription

​Generate a virtual account to collect payment

​Fetch the active virtual account

​Mark a subscription as paid

​Cancel a subscription

​Get and list subscriptions

​Payment history

Overview

Lifecycle

Create a subscription

Generate a virtual account to collect payment

Fetch the active virtual account

Mark a subscription as paid

Cancel a subscription

Get and list subscriptions

Payment history