> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyparrow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fees & tax direction

> Who pays the Hyparrow service fee and who pays VAT — set together, or split them so each lands on a different side.

Every payment Hyparrow settles for you carries two charges:

| Charge                   | Rate               | Cap      |
| ------------------------ | ------------------ | -------- |
| **Hyparrow service fee** | 2.5% of the amount | ₦5,000   |
| **VAT**                  | 7.5% of the amount | uncapped |

**Tax direction** is how you decide who pays them: you (absorbed from your
payout) or your customer (added on top at checkout).

<Note>
  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.
</Note>

## Three fields

| Field                   | Values                          | Meaning                                                |
| ----------------------- | ------------------------------- | ------------------------------------------------------ |
| `tax_direction`         | `merchant`, `customer`, `split` | The umbrella setting — moves **both** charges at once. |
| `service_fee_direction` | `merchant`, `customer`          | Overrides who bears the **2.5% service fee** only.     |
| `vat_direction`         | `merchant`, `customer`          | Overrides who bears the **7.5% VAT** only.             |

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.

```json theme={null}
{
  "service_fee_direction": "merchant",
  "vat_direction": "customer"
}
```

On a ₦100,000 invoice that produces:

|                                              | Amount       |
| -------------------------------------------- | ------------ |
| Invoice total                                | ₦100,000     |
| VAT (7.5%), added on top — customer bears it | + ₦7,500     |
| **Customer pays**                            | **₦107,500** |
| Service fee (2.5%), deducted — you bear it   | − ₦2,500     |
| **Credited to your wallet**                  | **₦97,500**  |

The reverse split works the same way:

```json theme={null}
{
  "service_fee_direction": "customer",
  "vat_direction": "merchant"
}
```

## The four combinations

For a ₦100,000 amount (service fee ₦2,500, VAT ₦7,500):

| `service_fee_direction` | `vat_direction` | Reported as | Customer pays | You receive |
| ----------------------- | --------------- | ----------- | ------------- | ----------- |
| `merchant`              | `merchant`      | `merchant`  | ₦100,000      | ₦90,000     |
| `customer`              | `customer`      | `customer`  | ₦110,000      | ₦100,000    |
| `merchant`              | `customer`      | `split`     | ₦107,500      | ₦97,500     |
| `customer`              | `merchant`      | `split`     | ₦102,500      | ₦92,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:

<CardGroup cols={2}>
  <Card title="Invoices" href="/invoices">
    `POST /invoices/` and `PATCH /invoices/{invoiceId}`
  </Card>

  <Card title="Subscriptions" href="/subscriptions">
    `POST /subscriptions/` — applies to every renewal
  </Card>

  <Card title="Payment links" href="/invoices">
    Set on the link; copied onto each invoice the link creates
  </Card>

  <Card title="Storefronts" href="/products">
    Set once on the shop; applies to every storefront order
  </Card>
</CardGroup>

You can also set all of this from the Hyparrow dashboard — no API call needed.

<Note>
  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.
</Note>

## Reading it back

Checkout responses (`GET /checkout/{invoiceId}`,
`GET /checkout/subscription/{subscriptionId}`, `GET /checkout/pay/{identifier}`)
expose the resolved split alongside the amounts:

```json theme={null}
{
  "totalAmount": 10000000,
  "taxDirection": "split",
  "serviceFeeDirection": "merchant",
  "vatDirection": "customer",
  "serviceFeeRate": 0.025,
  "serviceFee": 0,
  "vatRate": 0.075,
  "vatAmount": 750000,
  "payableAmount": 10750000
}
```

`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:

```json theme={null}
{ "vat_direction": "customer" }
```

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.