BPJS API Integration for Indonesian Developers: A Practical Guide

If you're building HR, ERP or clinic systems for Indonesian organisations, BPJS integration eventually comes up. BPJS Ketenagakerjaan (employment social security) and BPJS Kesehatan (national health insurance) run mandatory programmes for formal employees, so systems that hold Indonesian employee or patient data often need to exchange data with them. I put this guide together while researching BPJS integration for a prospective ERP project for a medium-sized law firm in Indonesia. That project hasn't been built yet, so treat this as a research write-up rather than a field report. Even so, the gap between BPJS's official channels and what developers actually run into turned out to be wide enough to be worth sharing.

BPJS Overview: What Developers Need to Know

There are two separate BPJS bodies. BPJS Ketenagakerjaan (formerly Jamsostek) runs work-accident cover (JKK), death benefit (JKM), old-age savings (JHT), pension (JP) and job-loss cover (JKP, Jaminan Kehilangan Pekerjaan, established by PP 37/2021). BPJS Kesehatan runs national health insurance (JKN). The two have separate systems, separate credentials and separate integration requirements. For HR and ERP systems, the relevant side is BPJS Ketenagakerjaan's reporting and payment channels. For healthcare systems (klinik, rumah sakit), BPJS Kesehatan's PCare and VClaim services are the relevant interfaces.

BPJS Ketenagakerjaan API Architecture

BPJS Ketenagakerjaan doesn't run a public, self-service developer portal. The api-dev.bpjsketenagakerjaan.go.id subdomain this article originally pointed to has since been repurposed for an internal attendance system, a reminder that BPJS subdomains get reorganised without notice, so verify any BPJS URL before building against it. In practice, most HR and payroll systems reach BPJS Ketenagakerjaan through two official web portals rather than a raw API: SIPP Online (sipp.bpjsketenagakerjaan.go.id), where registered employers manage worker data and contribution reports, and EPS (eps.bpjsketenagakerjaan.go.id), for host-to-host contribution payment through partner banks. A live bridging API with issued credentials does exist, but it isn't a self-serve signup: it is negotiated case by case with BPJS's IT partnership team, and most teams never need it because SIPP and EPS already cover reporting and payment.

BPJS Kesehatan PCare and VClaim APIs

BPJS Kesehatan offers several bridging services: VClaim for eligibility checks and claims (used by hospitals), PCare for primary care (puskesmas, klinik pratama), Antrean for queue management at BPJS-partnered facilities, and Apotek for pharmacies. Requests are authenticated with a consumer ID, a Unix timestamp and an HMAC-SHA256 signature computed with the facility's secret key, sent together with a user key header. Production access needs a formal partnership with BPJS Kesehatan; you cannot reach the production services without credentials issued to a partnered facility. Unlike BPJS Ketenagakerjaan, BPJS Kesehatan has an active open-source ecosystem: ssecd/jkn wraps VClaim, PCare, Antrean, Apotek and i-Care for Node.js, Deno and Bun, and aamdsam/bridging-bpjs offers a Laravel/PHP equivalent for VClaim and PCare. Both are worth evaluating before writing a client from scratch.

Applying for BPJS Kesehatan Bridging Access (VClaim / PCare)

Unlike BPJS Ketenagakerjaan, BPJS Kesehatan documents its bridging process for healthcare facilities. Its VClaim 2.0 bridging guide sets out the stages for hospitals: the facility sends a bridging request letter (Surat Permohonan Bridging Sistem) to its BPJS Kesehatan branch office (Kantor Cabang) together with a signed integrity pact (Pakta Integritas); BPJS issues tester credentials, a Consumer ID, Secret Key and User Key, for development; the facility builds against them and goes through a user acceptance test, which passes only when the whole UAT checklist is met; and only then does BPJS issue production credentials, with a second Pakta Integritas. The guide covers hospitals, so clinics and puskesmas integrating PCare should ask their branch office for its current procedure before planning the timeline.

// BPJS Kesehatan bridging (VClaim, PCare, Antrean): HMAC-SHA256 signature
// in Node.js, the pattern the open-source ssecd/jkn client implements.
// BPJS Ketenagakerjaan's bridging API issues its own spec under a PKS.
import crypto from "crypto"

function buildBpjsHeaders(consId: string, secret: string, userKey: string) {
  // Seconds since the Unix epoch, not milliseconds
  const timestamp = Math.floor(Date.now() / 1000).toString()
  const signature = crypto
    .createHmac("sha256", secret)
    .update(consId + "&" + timestamp)
    .digest("base64")

  return {
    "X-cons-id":    consId,
    "X-timestamp":  timestamp,
    "X-signature":  signature,
    "user_key":     userKey, // listed in BPJS Kesehatan's signature docs
    "Content-Type": "application/json",
  }
}
        

Contribution Figures Belong to the Regulation, Not Your Code

Systems that report to BPJS Ketenagakerjaan need contribution amounts, but this guide deliberately does not reproduce the rates or wage caps. They are set by government regulation and by BPJS, they differ by programme and, for work-accident cover, by risk class, and some caps are adjusted periodically, so any figure copied from a blog, this one included, can be out of date by the time you read it. Treat them as dated configuration: store each value with its legal basis and effective date, take it from BPJS or the regulation itself, and test your output against BPJS's own figures before go-live. One structural point that does not change with the numbers: JKP has no separate worker deduction, because under PP 6/2025 it is funded by a central-government contribution plus a recomposition of the JKK contribution.

The Realistic Integration Ladder for BPJS Ketenagakerjaan

Rather than one integration pattern, think of BPJS Ketenagakerjaan access as a ladder, and pick the lowest rung that meets your requirement, since each rung up costs more approval time. Rung 1: prepare the month's worker data and mutations in your HR system and export a SIPP-compatible file for manual upload, with no approval needed. Rung 2: work in SIPP Online directly and manage worker mutations and contribution reports through the portal instead of handling files by hand; it is self-service for registered employers. Rung 3: connect EPS to a partner bank for host-to-host contribution payment, removing the manual bank-transfer step. Rung 4: use a PPOB aggregator such as IAK API for on-demand BPJS Ketenagakerjaan inquiry or payment without a direct BPJS relationship; it is a paid third-party service, but it is live. Rung 5: negotiate a formal PKS for the live bridging API, with real-time checks and full programmatic control, which is only justified at meaningful scale, since approval takes weeks to months. Most HR products for the Indonesian market never go past rung 3.

1. Prepare the month's worker data — At month-end, collect new hires, exits and other worker mutations from your HR system, with contribution figures taken from dated configuration rather than hard-coded values.
2. Generate a SIPP-compatible file — Export the month's worker data and mutations into the file format SIPP Online accepts.
3. Upload via SIPP Online — Submit the file through sipp.bpjsketenagakerjaan.go.id, the self-service employer portal, which needs no PKS or live API access.
4. Pay via EPS or a partner bank — Settle the contribution bill through BPJS's Electronic Payment System or an approved bank payment channel.
5. Store the submission receipt — Save the SIPP confirmation receipt in your ERP or HR system as an audit trail.

# BPJS Integration Patterns (beyond batch reporting via SIPP Online)

## Pattern 2: Real-time JHT Balance Check (negotiated bridging API)
GET https://<cons-id-issued-endpoint>/saldo/...
Headers: X-cons-id, X-timestamp, X-signature
Response: { "kpj": "...", "saldo": "...", "status": "active" }
# Endpoint issued per-company after PKS approval — not publicly documented

## Pattern 3: PPOB Aggregator (no PKS required)
POST https://api.iak.id/api/v1/bill/check
Body: {
  "commands": "inq-pasca",
  "username": "your_registered_phone_number",
  "code": "BPJSTKPU",       // Penerima Upah (salaried); BPJSTKBPU for informal workers
  "hp": "KPJ_or_bill_number",
  "ref_id": "unique_ref_id",
  "sign": "md5(username + api_key + ref_id)"
}
# A paid third-party service: check the aggregator's own terms
# No direct BPJS partnership needed — separate inquiry + payment calls
        

Practical Code: Signature-Based Bridging Authentication in Node.js

BPJS Ketenagakerjaan does not publish the authentication scheme for its bridging API; the specification comes with the credentials under a PKS. BPJS Kesehatan's bridging services, by contrast, are well covered by open-source clients, and the sample below follows ssecd/jkn: an HMAC-SHA256 signature over the consumer ID and a Unix timestamp in seconds joined by an ampersand, keyed with the secret key and base64-encoded, sent in the X-cons-id, X-timestamp and X-signature headers alongside user_key. BPJS Kesehatan's own web-service catalogue documents the same scheme. A critical gotcha: staging sometimes returns different error codes than production, so test with the exact credentials you will use. If you reach rung 5 on the Ketenagakerjaan side, follow the specification BPJS gives you rather than this sample.

Third-Party BPJS Integration Services

For projects where direct BPJS integration is too complex or the PKS timeline is too long, third-party services exist in Indonesia. IAK API (api.iak.id) offers BPJS Ketenagakerjaan inquiry as a postpaid product through its PPOB (payment point online bank) aggregator API, with separate product codes for wage-earning participants (BPJSTKPU) and informal, self-employed participants (BPJSTKBPU). Requests are signed with an MD5 hash of your username, API key and reference ID rather than BPJS's own scheme, a much lower integration bar, which is why PPOB aggregators are popular with HR SaaS platforms. The trade-off: it is a paid third-party service, and you depend on a third party's uptime and data accuracy.

Building a Maintainable BPJS Integration

BPJS rules and API specifications change, and endpoints have moved before. Build your integration with change in mind: keep every contribution parameter in a database table or configuration file with its effective date, not in hard-coded constants; write version-aware API clients that can be updated without rewriting business logic; log every API request and response for debugging; and write automated tests that check your output against examples confirmed with BPJS. When the rules change, usually through a government regulation (Peraturan Pemerintah), you should be able to update your system in one place with confidence.

Sources & Further Reading