Skip to main content
Every payment Hyparrow settles for you carries two charges: Tax direction is how you decide who pays them: you (absorbed from your payout) or your customer (added on top at checkout).
The rates above are the current published values. Read the live figures from the checkout response (serviceFeeRate, vatRate) rather than hardcoding them — a rate change should not require a release on your side.

​
Three fields

Each component field defaults to tax_direction, and tax_direction itself defaults to merchant. Send only what you want to change. split is a derived label, not something you need to set: whenever the two components end up on different sides, Hyparrow reports tax_direction back to you as "split". Sending "tax_direction": "split" on its own carries no direction of its own — pair it with the component fields, or just send the component fields alone.

​
Setting a split

The common case: you absorb the 2.5% service fee as a cost of doing business, but VAT is passed to the end customer.
On a ₦100,000 invoice that produces: The reverse split works the same way:

​
The four combinations

For a ₦100,000 amount (service fee ₦2,500, VAT ₦7,500): Whichever way you set it, Hyparrow’s total take is the same ₦10,000 — the split only decides which side of the transaction each half comes from.

​
Where you can set it

The three fields behave identically everywhere they appear:

Invoices

POST /invoices/ and PATCH /invoices/{invoiceId}

Subscriptions

POST /subscriptions/ — applies to every renewal

Payment links

Set on the link; copied onto each invoice the link creates

Storefronts

Set once on the shop; applies to every storefront order
You can also set all of this from the Hyparrow dashboard — no API call needed.
A payment link or shop copies its resolved split onto each invoice it creates. Editing the link later changes future invoices, never ones already issued.

​
Reading it back

Checkout responses (GET /checkout/{invoiceId}, GET /checkout/subscription/{subscriptionId}, GET /checkout/pay/{identifier}) expose the resolved split alongside the amounts:
serviceFee and vatAmount are what the customer is charged for each component — a component you absorb reports 0 here and is deducted from your payout instead. payableAmount is always the figure to collect. Invoice and subscription objects carry tax_direction, service_fee_direction and vat_direction directly.

​
Invoices and receipts

Customer-facing documents itemize only the components the customer actually paid. On the split above, the invoice PDF and the receipt show a VAT (7.5%) row and no service-fee row — what you absorbed is between you and Hyparrow, and does not appear on your customer’s paperwork.

​
Updating an existing record

On PATCH /invoices/{invoiceId}, all three fields are optional and independent. Send just the one you want to move:
Omitting all three leaves the invoice’s current split untouched. Paid invoices cannot be edited.

​
Backwards compatibility

Nothing changes for integrations that don’t send the new fields.
  • tax_direction: "merchant" and tax_direction: "customer" behave exactly as they always have, moving both components together.
  • Invoices, subscriptions, links and shops created before splits existed keep their original behaviour.
  • A record whose components sit on the same side reports tax_direction as merchant or customer, never split — so you only ever see "split" on records that actually are.