Ghana — GRA E-VAT

The gh-gra adapter integrates with the Ghana Revenue Authority's Certified Invoicing System. Invoices are certified by GRA and come back with the signature, receipt number and QR that a compliant Ghanaian receipt must carry.

Adapter status

Built against GRA's published integration specification (VCIS/VSDC API 8.2) and verified end to end against GRA's test environment: invoices, refunds, refund cancellations and purchase records certified; duplicate submission and timeout recovery exercised. Production behaviour is confirmed per merchant during their GRA onboarding.

How a merchant gets connected

GRA issues credentials to taxpayers, not to software vendors. Your merchant — not you, and not Koolbase — onboards with GRA:

The merchant contacts GRA and is assigned a relationship manager.
GRA prepares their E-VAT environment and issues their company reference (TIN plus branch code, e.g. C0012345678-001) and a security key.
Joint testing, then GRA sign-off and go-live scheduling. GRA estimates around a month for API integrations.
The merchant hands you the company reference and security key. You store the key (encrypted, write-only) and activate their register.

Bring your own credentials

This is the same model as connecting a payment provider: the merchant owns the relationship with the authority, you hold the credential on their behalf. Koolbase never contacts GRA for you, and no vendor-level certification is required to integrate.

Document kinds

The kind field selects the transaction type. All kinds consume a fiscal number from the register's chain.

kind	Use	Certified?
INVOICE	A sale.	Yes
REFUND	Full reversal of a certified invoice. Requires `original_invoice_number`.	Yes
PARTIAL_REFUND	Partial reversal — reduced quantities and amounts. Requires `original_invoice_number`.	Yes
REFUND_CANCELATION	Reverses a refund. Minimal body — no line items. Requires `reference` (the refund) and `original_invoice_number`.	Yes
PURCHASE	A purchase you received, reported for input-tax purposes.	No — acknowledged only

A certified invoice is never “undone”

Once GRA has certified an invoice, GRA has it. The correction is a REFUND or PARTIAL_REFUND — a new transaction with its own certification, referencing the original. Voiding applies only to intents the authority never accepted.

Refund semantics

Two identifiers do different jobs, and mixing them up is the most common integration error:

original_invoice_number — the certified invoice being refunded. GRA resolves the refund against this; if it doesn't name a stamped invoice you get E701.
reference — the refund's own identity, your reference for this credit.

await Koolbase.fiscal.submit(
  deviceId: registerId,
  clientRef: refund.id,
  payload: {
    'kind': 'REFUND',
    'reference': 'REF-0001',                             // this refund
    'original_invoice_number': 'C0012345678-001-00004391', // the sale
    // ...same currency, totals, items shape as an invoice
  },
);

GRA enforces refund arithmetic on its side: refunding more than an invoice's remaining balance returns E727.

Tax fields

Ghana's VAT under Act 1151 (effective 1 January 2026) is 15% VAT plus NHIL 2.5% and GETFund 2.5% on the same taxable value. The COVID-19 Health Recovery Levy is abolished and is not sent for current-dated invoices.

Field	Meaning
levy_a	NHIL — 2.5%
levy_b	GETFund — 2.5%
levy_d	CST — 5% (communications services)
levy_e	Tourism levy — 1%
item_category	`""` standard · `CST` · `TRSM` tourism · `EXM` exempt/zero-rated · `RNT` rent · `EXC_PLASTIC` plastic excise
calculation_type	`INCLUSIVE` (unit price includes tax) or `EXCLUSIVE`
sale_type	`NORMAL` or `EXPORT`
discount_type	`GENERAL` (per line, tax exempt) or `SELECTIVE` (on total, taxable)
currency	GHS, USD, EUR or GBP (with `exchange_rate`)

What GRA returns

{
  "num": "C0012345678-001-00004391",   // your invoice number
  "ysdcid": "E000001001",              // SDC identity
  "ysdcrecnum": "1001-6317-NS1345",    // GRA receipt number
  "ysdcregsig": "ULOE-AVYC-F3KO-457H", // invoice signature
  "ysdcintdata": "YKPV-HVY6-CUI3-...", // internal data
  "ysdcmrc": "00:0C:29:0D:90:D0",      // machine registration code
  "ysdcmrctim": "2026/08/18 19:16:32", // received at GRA
  "ysdctime":   "2026/08/18 19:16:32", // stamped
  "qr_code": "https://verification.vat-gh.com?data=..."
}

Error codes

When GRA refuses a document the intent moves to attention and the authority's own message is preserved. The codes you're most likely to meet:

Code	GRA says	What it means for you
E700	Invoice has already been signed	Handled automatically — the engine fetches and adopts the original certification. You never see this as a failure.
E701	Invoice was not found	A refund's `original_invoice_number` doesn't name a certified invoice. Fix it and resubmit as a new transaction.
E727	Invoice Already Refunded	The refund exceeds what remains refundable on that invoice.
E900	Invalid Security Key	The merchant's credential is wrong, expired or revoked at GRA. Store a fresh one and attach it to the device.

Receipt requirements

A certified receipt shows the invoice number, the GRA signature, the receipt number, and the QR code encoded from the returned qr_code URL — clear and readable at a minimum of 2.5 cm × 2.5 cm. Scanning it takes a customer to GRA's verification page for that transaction.

Flutter Quickstart

Management API