How to Integrate the KPRA API with Your Business Software

Step 1 — Store your KPRA credentials

KPRA issues its own credential set. In TaxBridge you enter it once on the Authorities / Credentials form, which renders exactly the fields KPRA needs:

pos_id (a string, e.g. K123456), ntn and an API key — all sent inside the request body.

Credentials are AES-256-GCM encrypted at rest and never returned to your app. Don't have production credentials yet? Turn on Use simulator (sandbox) and build your whole integration first — see how to test tax APIs.

Step 2 — Create an API key

Generate a key scoped to the test environment (and optionally pinned to KPRA). The full key — tbk_test_... — is shown once and stored only as a SHA-256 hash. Keep it as a secret; a lost key is regenerated, not recovered.

Step 3 — POST your first KPRA invoice

Send your canonical invoice to POST /api/v1/invoices with the KPRA header and an Idempotency-Key:

curl -X POST https://taxbridge.themetasum.com/api/v1/invoices \
  -H "Authorization: Bearer tbk_test_9f3a21c7b4d6e8f0_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b6d1c4e-7f9a-4a51-8d3c-2e5f7a91b204" \
  -H "X-Tax-Authority: KPRA" \
  -d '{
    "invoiceNumber": "INV-10001",
    "invoiceDate": "2026-08-10T10:30:00",
    "invoiceType": "Sale",
    "currency": "PKR",
    "paymentMode": "Cash",
    "customer": { "name": "Walk-in Customer" },
    "items": [{
      "description": "Chicken Karahi Full", "hsCode": "11001010",
      "quantity": 1, "unitPrice": 1500.00,
      "taxRate": 16, "taxAmount": 240.00, "total": 1740.00
    }],
    "subTotal": 1500.00, "tax": 240.00, "total": 1740.00
  }'

Print the returned qrCode on the receipt and store the submissionId so you can query status later.

The KPRA quirk TaxBridge handles for you

KPRA’s POS ID is a string, not a number — a common source of bugs when integrating directly. TaxBridge validates and formats it for you. Restaurants on RIMS pay a reduced rate.

Step 4 — Go to production

Once your sandbox flow is verified, complete company and branch configuration, store your production credentials and generate a tbk_live_ key. Sandbox and production stay completely separate — a sandbox key never files a real KPRA invoice. See production onboarding.

Frequently asked questions