# BPJS API Integration for Indonesian Developers: A Practical Guide > Integrating with BPJS Ketenagakerjaan and BPJS Kesehatan from HR, ERP and clinic systems: access paths, authentication, the approval process and the undocumented gotchas. URL: https://www.matthewswong.com/en/blog/bpjs-api-integration/ - Author: Matthews Wong (https://www.matthewswong.com/en/about/) - Published: 2025-06-10 - Updated: 2026-10-13 - Category: Web Dev > **Key takeaway:** BPJS integration is not a single public API. Most companies report to and pay BPJS Ketenagakerjaan through the SIPP Online and EPS portals, a live bridging API needs a formal PKS agreement, and BPJS Kesehatan's VClaim and PCare access is open to partnered healthcare facilities that apply through their branch office. This guide covers access paths and authentication, and deliberately does not reproduce contribution rates or wage caps. > **Disclaimer** > This is general technical information for developers, not legal, tax, payroll or employment advice. BPJS programmes, contribution rates, wage caps and access procedures are set by government regulation and by BPJS, and they change, so this article does not reproduce them. Take every figure from BPJS or the regulation itself, and confirm requirements with your BPJS branch office or a qualified adviser before relying on them. Reviewed on 13 October 2026. 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. > Timestamps are a common source of BPJS bridging failures. The signature covers the request timestamp, so if your server clock drifts, requests start failing in ways that look like credential problems. Run NTP time synchronisation on your integration server, send the timestamp in seconds rather than milliseconds, and log the timestamp you sent alongside the response code when debugging authentication failures. ## 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. 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. Generate a SIPP-compatible file Export the month's worker data and mutations into the file format SIPP Online accepts. 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. Pay via EPS or a partner bank Settle the contribution bill through BPJS's Electronic Payment System or an approved bank payment channel. Store the submission receipt Save the SIPP confirmation receipt in your ERP or HR system as an audit trail. ## 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. > **The BPJS PKS Requirement** > If you actually need rung 5, the live bridging API, budget for a real approval process, not a signup form. BPJS Ketenagakerjaan will expect a formal legal entity (PT or CV, not an individual or freelance contract) as the signing party; a documented use case that justifies real-time access, since batch reporting through SIPP already covers most needs; a technical point of contact who can pass BPJS's security and integration review; and patience, because the cycle from first request to a signed PKS and production credentials commonly takes weeks to months, and BPJS controls the timeline. If you're building for a client, the client's legal entity, not your development shop, is almost always the party that must sign, so confirm this before quoting a delivery date. It's worth asking BPJS's partnership team whether your use case even needs the live API, since SIPP Online, EPS or a PPOB aggregator often meets the real business requirement with far less approval effort. ## 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. BPJS Ketenagakerjaan's old-age savings programme: a lump-sum benefit paid from accumulated employer and employee contributions when a worker retires, resigns or reaches a qualifying age. A monthly pension benefit under BPJS Ketenagakerjaan, funded by contributions capped at a government-set wage base that is adjusted periodically. Job-loss cover established by PP 37/2021 and, under PP 6/2025, funded by a central-government contribution plus a recomposition of the JKK contribution rather than a payroll deduction, giving cash benefits, labour-market information and job training to laid-off formal workers. The formal cooperation agreement an organisation signs with BPJS before it can use a live, real-time bridging API instead of portal reporting or batch file uploads. BPJS Ketenagakerjaan's self-service web portal where registered employers report worker data and monthly contributions without API credentials or a PKS. A keyed hash that combines a shared secret with request data to produce a signature; BPJS Kesehatan's bridging services use it to verify that a request came from an authorised facility and was not altered. ## Sources & Further Reading - SIPP Online: BPJS Ketenagakerjaan employer reporting portal - BPJS Ketenagakerjaan: EPS (Electronic Payment System) explainer - Jaminan Kehilangan Pekerjaan (JKP): official programme portal - HFIS: BPJS Kesehatan health facility information system - ssecd/jkn: BPJS Kesehatan (JKN) bridging library for Node.js, Deno and Bun - aamdsam/bridging-bpjs: BPJS Kesehatan VClaim and PCare bridging for Laravel/PHP - IAK API: BPJS Ketenagakerjaan postpaid inquiry documentation - PP 6/2025 on the JKP programme (JDIH BPK) - BPJS Kesehatan web-service catalogue: creating the request signature - BPJS Kesehatan: VClaim 2.0 bridging stages and guidelines (PDF) ## Source links - https://sipp.bpjsketenagakerjaan.go.id/ - https://www.bpjsketenagakerjaan.go.id/artikel/18917/artikel-bayar-iuran-bpjs-ketenagakerjaan-makin-mudah-dengan-eps-serta-kanal-pembayarannya.bpjs - https://jkp.go.id/tentang - https://hfis.bpjs-kesehatan.go.id/hfis/ - https://github.com/ssecd/jkn - https://github.com/aamdsam/bridging-bpjs - https://api.iak.id/api/postpaid/core/products/bpjs-ketenagakerjaan/pu/inquiry - https://peraturan.bpk.go.id/Details/314623/pp-no-6-tahun-2025 - https://dvlp.bpjs-kesehatan.go.id:8888/trust-mark/tpl/katalogws/createsignature.html - https://dvlp.bpjs-kesehatan.go.id:8888/trust-mark/doc/TAHAPAN_PELAKSANAAN_BRIDGING_VCLAIM_VERSI_2_FINAL.pdf ## FAQ ### What authentication do BPJS bridging APIs use? BPJS Kesehatan's bridging services, such as VClaim and PCare, authenticate each request with a consumer ID, a Unix timestamp in seconds and an HMAC-SHA256 signature over the consumer ID and timestamp keyed with the secret key, sent as X-cons-id, X-timestamp and X-signature headers alongside a user_key header. BPJS Ketenagakerjaan does not publish its bridging scheme; it comes with credentials issued under a PKS. ### Why do my BPJS bridging requests fail even though my credentials look correct? Clock drift is a common cause. The signature covers the request timestamp, so if your server clock drifts, requests fail in ways that look like credential problems. Run NTP time synchronisation on the integration server, send the timestamp in seconds rather than milliseconds, and log the timestamp you sent alongside each response code to isolate the issue. ### Do I need a PKS agreement before I can go live with BPJS Ketenagakerjaan? Only if you need the live bridging API for real-time access. Most HR systems never reach that tier, because SIPP Online covers reporting and EPS covers host-to-host payment. If you do need it, expect BPJS to ask for a formal legal entity as the signing party, a documented use case, a technical contact who can pass security review, and patience: the cycle commonly takes weeks to months. ### Where should my system get BPJS contribution rates from? From BPJS and the regulation itself, not from a blog post. Rates and wage caps are set by government regulation and BPJS, differ by programme and risk class, and some caps are adjusted periodically, so this guide deliberately does not reproduce them. Store each value as dated configuration with its legal basis and effective date, and test your output against BPJS's own figures before go-live. ### What if direct BPJS integration is too complex or the PKS timeline too long? Use a PPOB aggregator. IAK API offers BPJS Ketenagakerjaan inquiry as a postpaid product, with separate product codes for wage-earning participants (BPJSTKPU) and informal participants (BPJSTKBPU), and no direct BPJS partnership. Requests are signed with an MD5 hash instead of BPJS's own scheme. The trade-off is that it is a paid third-party service, and you depend on its uptime and data accuracy. ### How do I get access to BPJS Ketenagakerjaan for a new HR system? Start at the bottom of the ladder: prepare worker data and mutations in your HR system and export a SIPP-compatible file for manual upload, with no approval needed. Then work in SIPP Online (sipp.bpjsketenagakerjaan.go.id) directly, and add EPS for host-to-host payment through a partner bank. Pursue the live bridging API, which needs a negotiated PKS, only if your product genuinely needs real-time access. ### How does a health facility apply for BPJS Kesehatan VClaim or PCare bridging access? The facility must already be a BPJS Kesehatan partner. Under BPJS Kesehatan's VClaim 2.0 bridging guide, it sends a bridging request letter and a signed Pakta Integritas to its branch office, receives tester credentials (Consumer ID, Secret Key and User Key), builds against them, and must pass the full UAT checklist before production credentials are issued. The guide covers hospitals, so clinics on PCare should confirm the procedure with their branch office. --- - HTML version: https://www.matthewswong.com/en/blog/bpjs-api-integration/ - Bahasa Indonesia: https://www.matthewswong.com/id/blog/bpjs-api-integration/ - Site index for agents: https://www.matthewswong.com/llms.txt - Sitemap: https://www.matthewswong.com/sitemap.xml - API description (OpenAPI): https://www.matthewswong.com/openapi.json