Khyber PakhtunkhwaSales tax on services⚡ Sandbox + Production

KPRA API Integration

Submit invoices to the Khyber Pakhtunkhwa Revenue Authority through one canonical TaxBridge API. Sandbox, production, authentication, error handling and logs — without studying the KPRA API directly.

Start KPRA Sandbox View Documentation

KPRA covers sales tax on services in Khyber Pakhtunkhwa.

POST /api/v1/invoices

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: PRA" \
  -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
  }'

KPRA in one call

Integrate KPRA Without the KPRA-Specific Work

You send TaxBridge one canonical invoice. TaxBridge applies KPRA’s field names, casing, money identity and success rules, then returns a single normalized result.

Authority	Khyber Pakhtunkhwa Revenue Authority
Jurisdiction	Khyber Pakhtunkhwa
Covers	Sales tax on services
Header	`X-Tax-Authority: KPRA`
Registration	kpra.gov.pk

POST /api/v1/invoices

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
  }'

How KPRA Integration Works

Four steps from account to your first approved KPRA invoice.

1. Register & get approved

Create your TaxBridge company and verify your email. An admin approves the company for production access.

2. Subscribe & store KPRA credentials

Pick a plan for KPRA and fill the credential form. For KPRA: pos_id (a string, e.g. K123456), ntn and an API key — all sent inside the request body.

3. Create an API key

Generate a test or live key, optionally pinned to KPRA. The full key is shown once and stored only as a hash.

4. Post an invoice

Send your canonical invoice with X-Tax-Authority: KPRA. Print the returned qrCode and keep the submissionId.

KPRA authority 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.

🔑

Credentials, encrypted

Your KPRA credentials are AES-256-GCM encrypted at rest and never returned to your app.

🧪

Sandbox & simulator

Test KPRA end-to-end before you hold production credentials.

⚠

Normalized errors

KPRA rejections come back as a single status with a readable authorityMessage.

📋

Full request logs

Every KPRA submission is logged with request, response and status for debugging.

🏢

Multi-branch

Run many outlets under one company — each branch’s KPRA submissions are tracked separately.

🔄

Idempotent retries

A repeated Idempotency-Key replays the stored KPRA result with no double submission.

KPRA responses your code handles

HTTP	Meaning	What your code does
`201`	Approved by the authority	Print `qrCode`, store `submissionId`
`200`	Idempotent replay (`duplicate:true`)	Treat like the original — no quota consumed
`400 INVALID_INVOICE`	Normalizer rejected it; `details[]` lists every problem	Fix and resubmit — no quota consumed
`402 QUOTA_EXCEEDED`	Plan limit hit or subscription expired	Upgrade or renew
`409 DUPLICATE_INVOICE`	Invoice number already approved for this authority + environment	Do not resubmit
`422`	Authority rejected it (`status:"REJECTED"`)	Read `authorityMessage`, fix the data
`429`	Rate limit or sandbox soft cap	Honour `Retry-After`
`502 / 504`	Authority errored or timed out	Retry with the same `Idempotency-Key`

KPRA API — FAQ

What is KPRA API integration?

KPRA API integration connects your software to the Khyber Pakhtunkhwa Revenue Authority system (including RIMS for restaurants) for sales tax on services in KP. TaxBridge translates your canonical invoice into KPRA’s body format and credentials.

What software needs KPRA integration?

Restaurants, hotels, guest houses, wedding halls and other KP service providers and their POS, ERP or billing software, especially in Peshawar, Abbottabad and Mardan.

Why is the KPRA POS ID a string?

KPRA issues a string POS ID such as K123456 (not a number), which is a common bug when integrating directly. TaxBridge validates and formats it for you.

How does KPRA authenticate?

KPRA uses ntn, pos_id and an API key sent inside the request body. You store them once in TaxBridge, encrypted at rest.

Also integrating another province? See PRA · FBR · SRB or the unified tax API.