Checkout

Every invoice you create can be paid on a hosted checkout page. You share a URL, your customer opens it, picks how they want to pay, and Hyparrow settles the invoice and notifies you. The checkout URL is:

CHECKOUT_BASE_URL/pay/{invoiceId}

The endpoints on this page are the public API the hosted checkout page calls. They are unauthenticated, there are no X-API-Key / X-API-Secret headers because the customer paying the invoice is not your API client. The base URL is the same: https://api.hyparrow.cloud/api/v1.

Amounts are in kobo. payableAmount, totalAmount and friends are in the minor unit (100000 = ₦1,000.00).

Payment methods

The customer-facing options on the checkout page are:

Method	Key	Notes
Bank transfer / virtual account	`bankTransfer`	Transfer the exact amount to a temporary account number. NGN only.
USSD	`ussd`	Dial a code generated for the customer’s bank. NGN only.
Card	`card`	Card details are encrypted in-browser and charged via the card network.
OPay	`opay`	Customer is redirected to OPay to authorize.
Crypto	`crypto`	Pay with USDC or USDT on a supported chain (defaults to USDC on Base).

Which methods appear depends on the merchant’s payment preferences and the invoice currency, the NGN-only rails (bank transfer, USSD) are hidden for non-NGN invoices. The active set is returned as allowedPaymentMethods from GET /checkout/{invoiceId}.

End-to-end flow

Customer opens the checkout page

The page calls GET /checkout/{invoiceId} to load the invoice, amounts and allowed payment methods.

Customer picks a method

Depending on the choice, the page calls …/va, …/ussd, …/card, …/opay or …/crypto to start that payment.

Customer pays

Transfer to the virtual account, dial the USSD code, complete the card / OPay redirect, or send crypto to the address.

Page polls for status

The page polls GET /checkout/{invoiceId}/status until paid is true.

Callback fires

Hyparrow POSTs a checkout.payment.* event to the invoice’s checkoutCallbackUrl (if set) as the payment progresses.

Load the checkout

GET /checkout/{invoiceId} Returns sanitized invoice data for rendering the page. Canceled invoices return 404.

{
  "success": true,
  "data": {
    "id": "8f1c2e34-5a6b-47c8-9d0e-112233445566",
    "title": "Website redesign",
    "invoiceNumber": "invoice-hpw-000000042",
    "currency": "NGN",
    "customerName": "Ada Obi",
    "customerEmail": "ada@example.com",
    "subTotal": 350000000,
    "taxTotal": 26250000,
    "discountTotal": 0,
    "shippingFee": 0,
    "totalAmount": 376250000,
    "taxDirection": "customer",
    "serviceFeeDirection": "customer",
    "vatDirection": "customer",
    "serviceFeeRate": 0.025,
    "serviceFee": 500000,
    "vatRate": 0.075,
    "vatAmount": 37500,
    "payableAmount": 377037500,
    "status": "pending",
    "lineItems": [ /* ... */ ],
    "invoiceVAs": [ /* active virtual accounts */ ],
    "allowedPaymentMethods": ["bankTransfer", "card", "opay", "crypto"],
    "clientProfilePicture": "https://…"
  }
}

payableAmount is what the customer actually pays, always collect this figure, never totalAmount. The service fee and VAT are settled independently. serviceFee and vatAmount are what the customer is charged for each: a component the merchant absorbs reports 0 and is deducted from their payout instead. serviceFeeDirection and vatDirection tell you which side each one landed on, and taxDirection summarizes them as merchant, customer, or split when they differ. So a merchant who absorbs the 2.5% but passes VAT to the customer produces serviceFee: 0, a non-zero vatAmount, and taxDirection: "split". Render whichever fee rows are non-zero rather than keying off taxDirection, see Fees & tax direction.

Bank transfer (virtual account)

POST /checkout/{invoiceId}/va Creates (or returns the existing active) virtual account for the invoice.

// body, optional, defaults to 15 minutes
{ "expiryMinutes": 15 }

expiryMinutes accepts 10, 15 or 30; anything else defaults to 15.

// 201 Created
{
  "success": true,
  "message": "Virtual account generated, transfer the exact amount before it expires",
  "data": {
    "accountNumber": "1234567890",
    "accountName": "HYPARROW/Website redesign",
    "bankName": "Wema Bank",
    "bankCode": "035",
    "expiresAt": "2026-06-30T20:15:00Z"
  }
}

If a non-expired VA already exists it is returned with 200 instead of creating a duplicate. GET /checkout/{invoiceId}/va returns the current active, non-expired account, or 404 if there is none (e.g. it expired).

The customer must transfer the exact amount before expiresAt. After expiry the account stops accepting payment, call POST …/va again to mint a fresh one. Bank transfer is NGN only; a non-NGN invoice returns 400.

USSD

POST /checkout/{invoiceId}/ussd Generates a USSD dial code for the customer’s bank.

// body
{ "bankCode": "035" }

{
  "success": true,
  "message": "USSD code generated. Dial the code on your phone to complete payment.",
  "merchantTransactionReference": "chk_ussd_3f9a…",
  "data": {
    "ussdCode": "*945*000*1234#",
    "reference": "…",
    "responseCode": "…",
    "merchantTransactionReference": "chk_ussd_3f9a…"
  }
}

The customer dials the code to authorize the transfer. USSD is NGN only. A checkout.payment.pending callback fires when the code is generated.

Card

POST /checkout/{invoiceId}/card Charges a card via the card network. Card details are encrypted before they leave the browser.

// body
{
  "pan": "5060990580000217499",
  "pin": "1234",
  "expiryDate": "2512",
  "cvv2": "123",
  "amount": "377037500",
  "currency": "NGN"
}

The response carries the network’s responseCode:

00, approved. The invoice is settled and a checkout.payment.completed callback fires.
T0 / S0, processing (e.g. an OTP/3-DS step). A checkout.payment.pending callback fires; keep polling status.
anything else, declined. A checkout.payment.failed callback fires.

{ "success": true, "message": "Card purchase initiated", "data": { "responseCode": "00", "message": "Approved" } }

OPay

POST /checkout/{invoiceId}/opay Initializes an OPay payment and returns a redirectUrl to send the customer to.

{
  "success": true,
  "message": "OPay payment initialized. Redirect customer to the provided URL.",
  "redirectUrl": "https://…",
  "transactionReference": "chk_opay_…",
  "responseCode": "00"
}

After authorizing on OPay the customer is returned to the checkout page, which polls status to confirm. A checkout.payment.pending callback fires on initialization.

Crypto

POST /checkout/{invoiceId}/crypto Generates a stablecoin payment address. The fiat total is converted to USD.

// body, optional, defaults to USDC on Base
{ "chain": "BASE", "token": "USDC" }

// 201 Created
{
  "success": true,
  "data": {
    "id": "…",
    "address": "0xabc…",
    "network": "BASE",
    "asset": "USDC",
    "amountInAsset": "242.000000",
    "amountFiat": 377037500,
    "currencyFiat": "NGN",
    "amountUsd": 242.0,
    "status": "pending",
    "expiresAt": "2026-06-30T20:30:00Z",
    "isActive": true
  }
}

token is USDC or USDT. The customer sends the asset to address before expiresAt (30 minutes). GET /checkout/{invoiceId}/crypto returns the active address. Settlement arrives asynchronously once the on-chain transfer confirms.

Poll status

GET /checkout/{invoiceId}/status The checkout page polls this until the payment lands.

{ "success": true, "data": { "status": "paid", "paid": true } }

paid is true once the invoice is paid (or a receipt exists). Use this as the source of truth on the page; the asynchronous methods (transfer, USSD, OPay, crypto) flip it when settlement confirms.

Payment links

A payment link lets you collect a payment without pre-creating an invoice, useful for a shareable “pay me” page. The public URL is CHECKOUT_BASE_URL/pay/{identifier}, where identifier is the link’s custom slug or its id. GET /checkout/pay/{identifier} returns the link’s page data (name, description, amount, allowed methods):

{
  "success": true,
  "data": {
    "id": "…",
    "slug": "donate",
    "type": "one_time",
    "pageName": "Support our work",
    "amount": 500000,
    "currency": "NGN",
    "allowedPaymentMethods": ["bankTransfer", "card", "opay", "crypto"]
  }
}

POST /checkout/pay/{identifier} turns the customer’s submission into an invoice so the normal payment rails can settle it. If the link has a fixed amount it wins; otherwise the customer-entered amount is used.

// body
{ "amount": 500000, "customerName": "Ada Obi", "customerEmail": "ada@example.com" }

// 201 Created
{
  "success": true,
  "message": "Payment initialized",
  "data": { "invoiceId": "9a0b…" }
}

Hand the returned invoiceId to the standard checkout flow above (…/va, …/card, etc.) to complete payment.

Edge cases

Situation	Behaviour
Invoice already `paid`	The payment-start endpoints return `400 "invoice is already paid"`.
Invoice `canceled`	`GET /checkout/{invoiceId}` and the start endpoints return `404 "invoice not found"`.
Expired virtual account	`GET …/va` returns `404`; mint a new one with `POST …/va`.
Amount mismatch on transfer	Only a transfer matching the invoice amount settles it. Pay the exact `payableAmount`.
Non-NGN invoice	`bankTransfer` and `ussd` are hidden / rejected; use card or crypto.

Checkout callback webhook

If the invoice has a checkoutCallbackUrl, Hyparrow POSTs an event to it as the payment progresses. The body is:

{
  "event": "checkout.payment.completed",
  "timestamp": 1751313600,
  "data": {
    "type": "invoice",
    "invoiceId": "8f1c2e34-5a6b-47c8-9d0e-112233445566",
    "status": "paid",
    "amount": 376250000,
    "currency": "NGN",
    "reference": "chk_card_…",
    "paymentMethod": "card"
  }
}

Events:

checkout.payment.pending, payment started, awaiting settlement (transfer pending, USSD/OPay in progress, card in 3-DS).
checkout.payment.completed, settled; the invoice is paid.
checkout.payment.failed, the attempt failed (e.g. a declined card).

Treat the callback as a notification and confirm with GET /checkout/{invoiceId}/status before fulfilling.

Sandbox

In the sandbox, the hosted checkout URL carries ?sandbox=true and points at the sandbox API (https://sandbox.hyparrow.cloud/api/v1). You don’t need a real bank transfer or card to test, complete the payment instantly:

Use the “Simulate payment” button on the sandbox checkout page, or call POST /checkout/{invoiceId}/simulate-payment directly. It runs the invoice through the normal payment path, marking it paid, issuing a receipt and firing the checkout.payment.completed callback, with simulated money. It is available only on the sandbox deployment (returns 404 in production).

curl -X POST https://sandbox.hyparrow.cloud/api/v1/checkout/{invoiceId}/simulate-payment

{ "success": true, "message": "Sandbox payment completed", "data": { "status": "paid" } }

If the invoice is already paid, it returns 200 with "invoice already paid".

Getting Started

Identity

Customers

Accepting Payments

Payouts & Bills

Commerce

Crypto

Developer

Payment methods

End-to-end flow

Load the checkout

Bank transfer (virtual account)

USSD

Card

OPay

Crypto

Poll status

Payment links

Edge cases

Checkout callback webhook

Sandbox

​Payment methods

​End-to-end flow

​Load the checkout

​Bank transfer (virtual account)

​USSD

​Card

​OPay

​Crypto

​Poll status

​Payment links

​Edge cases

​Checkout callback webhook

​Sandbox

Payment methods

End-to-end flow

Load the checkout

Bank transfer (virtual account)

USSD

Card

OPay

Crypto

Poll status

Payment links

Edge cases

Checkout callback webhook

Sandbox