e-Bupot

The e-Bupot module covers withholding-tax receipts (Bukti Potong) across all DJP CTAS variants. It is structured around eight bupot variants grouped into five endpoint families. Two of the families serve multiple variants through an in-body discriminator; the other three are dedicated to a single variant each.

Like e-Billing and SPT — but unlike e-Faktur — this module wraps DJP soft errors as HTTP 400 rather than returning them inside an HTTP 200 envelope. Several conventions specific to e-Bupot are described in section 7.3; read that section before any individual endpoint reference.

7.1 The eight variants

DJP CTAS defines eight kinds of withholding receipt. Sipajak exposes all of them. The variant determines which endpoint family the client uses, which detail object is required in the request body, and which response shape is returned.

BPPU, BPMP, and BP21 share the bpu-a0-21 endpoint family; the variant is selected by a discriminator field in the request body (see section 7.3.2). BPA1 and BPA2 share the a1-a2 family; the variant is selected by which detail block is populated. BPNR, BPCY, and BPSP each have a dedicated family with no in-body discriminator — the URL itself identifies the variant.

7.2 Endpoint summary

Every variant family supports the same four operations: validate (pre-flight), create, update (replacement), and cancel. Plus three cross-cutting endpoints serve all variants.

7.2.1 Variant operations

7.2.2 Cross-cutting endpoints

7.2.3 Reference catalogues

Each of the eight variants exposes its own reference catalogue. The path prefix carries the variant code; the operations are uniform. Detail in section 7.11.

7.3 Module conventions

Five conventions apply across the entire e-Bupot module. Internalise these once; the per-family references that follow assume familiarity with each.

7.3.1 Soft errors return HTTP 400

Like e-Billing and SPT — and unlike e-Faktur — e-Bupot wraps DJP business errors as HTTP 400 with a BadRequestException envelope. The original DJP envelope is nested at body.response with the diagnostic at body.response.statusMessage.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
  "response": {
    "status": "0",
    "statusMessage": "tanggal_Dokumen salah!",
    "uuid": "08fc9756-d96a-4413-8e61-12fc3eb24066",
    "correlation_id": "14645a75-20d4-4cfc-953a-76372ca1dc56",
    "status_code": 400
  },
  "status": 400,
  "options": {},
  "message": "Bad Request Exception",
  "name": "BadRequestException",
  "correlation_id": "14645a75-20d4-4cfc-953a-76372ca1dc56"
}

Branch error-handling code on HTTP status (200 vs 400) first, then read body.response.statusMessage for the DJP-localised diagnostic.

7.3.2 The fgJnsBupot discriminator

Three variants — BPPU, BPMP, and BP21 — share the bpu-a0-21 endpoint family. The client identifies which variant is being submitted via a top-level fgJnsBupot string in the request body.

On verify and cancel operations, BPCY, BPSP, and BPMP all use fgJnsBupot = "BPU" regardless of which create endpoint was used originally — the unified cancel/verify path expects the discriminator even though the create flow does not. BPNR is the exception: its verify operation uses fgJnsBupot = "BPNR26".

7.3.3 Date format and field types

Request-body dates use DDMMYYYY (eight characters, no separator) — the same convention as e-Faktur. Two fields and one nested datetime have specific notes:

Two further type inconsistencies to be aware of: tahunPajak is a string in BPU/BPMP/BP21 and an integer in BPNR/BPCY/BPSP/BPA1/BPA2; masaPajak is always a two-character string ("01" through "12") regardless of variant.

7.3.4 Field naming case landmines

Important. The same conceptual field uses DIFFERENT capitalisation across variants. This is a DJP-side inconsistency that Sipajak forwards verbatim — clients must match the case exactly per variant.

Furthermore, the values that statusPPh / statusPph can take are themselves stylised differently per variant:

The dokReferensi item field tanggal_Dokumen is also worth highlighting on its own: it is snake_case with a capital D on Dokumen. Not camelCase, not all-lowercase. Preserve verbatim.

7.3.5 Signing

e-Bupot uses the same out-of-band certificate registration as e-Faktur — the .p12 file is uploaded once during organisation onboarding; each create / update / cancel request carries only the plaintext passphrase. The signing fields are:

Sensitive material. passphrasePenandatangan travels as a plaintext body field. The TLS layer is the only protection in transit. Client implementations MUST NOT log this field, MUST NOT echo it in error messages, and SHOULD store it in a secrets-management tool.

7.4 BPPU, BPMP, BP21 — the bpu-a0-21 family

The three highest-volume variants — Bupot Unifikasi (BPPU), Bupot Pegawai Tidak Tetap (BPMP / A0), and PPh 21 monthly (BP21) — share four endpoints. The variant is selected by the fgJnsBupot discriminator (see section 7.3.2). The request envelope is identical across variants; the per-variant detail goes into one of three dataDetil* wrapper objects.

In production traffic, BP21 dominates this family — at the time of writing, 99% of /v2/ebupot/create-bpu-a0-21 traffic carries fgJnsBupot = "21". BPPU and BPMP traffic is concentrated on UAT/staging.

7.4.1 Common request fields

Every operation in this family carries the same top-level fields. The detail object below the common fields is variant-specific.

7.4.2 Detail object — BPPU (fgJnsBupot = "BPU")

The dataDetilBpu wrapper carries the PPh 22/23/4(2)/15 calculation fields.

7.4.3 Detail object — BPMP (fgJnsBupot = "A0")

BPMP uses dataDetilA0. It does not carry a dpp; the PPh is computed against penghasilanKotor (gross income) instead.

Note: dataDetilA0 does NOT carry a dokReferensi array, unlike most other variants. Reference documents are not applicable for non-employee PPh 21 withholdings.

7.4.4 Detail object — BP21 (fgJnsBupot = "21")

BP21 uses dataDetilBp21. It extends the BPPU shape with cumulative income tracking and a normative-income factor.

7.4.5 Example — create BPPU

POST /v2/ebupot/create-bpu-a0-21

POST /v2/ebupot/create-bpu-a0-21 HTTP/1.1
Host: gateway-integration.sipajak.com
Authorization: Basic <base64-encoded credentials>
npwp: 1234567890123000
Content-Type: application/json
{
  "fgTransaction": "NEW",
  "noBupot": "",
  "idBupot": "",
  "revNo": "1",
  "npwpPemotong": "1234567890123000",
  "idTku": "1234567890123000000000",
  "masaPajak": "12",
  "tahunPajak": "2025",
  "fgNpwpNik": true,
  "npwp": "2345678901234000",
  "nik": "3201234567890001000000",
  "nama": "Budi Santoso",
  "fgJnsBupot": "BPU",
  "tglPemotongan": "01122025",
  "dataDetilBpu": {
    "sertifikatInsentifDipotong": "9",
    "nomorSertifikatInsentif": "",
    "kodeObjekPajak": "28-404-02",
    "pasalPPh": "Pasal 4 Ayat 2",
    "statusPPh": "FINAL",
    "dpp": 10000000,
    "tarif": 7.5,
    "pphDipotong": 750000,
    "kap": "411128",
    "kjs": "100",
    "dokReferensi": [
      {
        "dokReferensi": "ANNOUNCEMENT",
        "nomorDokumen": "REF-2025-001",
        "tanggal_Dokumen": "02122025"
      }
    ]
  },
  "npwpNikPenandatangan": "1234567890123000",
  "namaPenandatangan": "Budi Santoso",
  "dcPenandatangan": "1",
  "serialNumberPenandatangan": "1",
  "userId": "user-xxxxxxxx",
  "passphrasePenandatangan": "<certificate passphrase>"
}

Example response — success

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "status": "1",
    "statusMessage": "Success",
    "result": {
      "nomorBupot": "25000ISSF",
      "idBupot": "c56dd8d5-3468-4fa6-bbbb-d5c6c6a121e5",
      "namaObjekPajak": "Deposit interest placed domestically (IDR currency sourced from DHE
tenor 1 month)",
      "pphDipotong": 750000,
      "tanggalSP2D": "",
      "approvalCode": "",
      "timestamp": "2025-12-09 11:22:51"
    },
    "uuid": "2612e728-80a7-4ded-ab70-e13e0cc2ef73"
  }
}

Result fields

7.4.6 Validate, Update, Cancel

Validate, update, and cancel mirror the create request structure. The validate endpoint runs the same DJP-side validation as create but does not persist the bupot — use it as a pre-flight check before committing. Update replaces a previously-issued bupot (fgTransaction = "EDIT"; noBupot and idBupot identify the original). Cancel revokes a previously-issued bupot and carries only the identifying fields plus tglPembatalan.

Cancel request body — minimal:

{
  "npwpPemotong": "1234567890123000",
  "idTku": "1234567890123000000000",
  "tahunPajak": "2025",
  "noBupot": "25000ISSF",
  "idBupot": "c56dd8d5-3468-4fa6-bbbb-d5c6c6a121e5",
  "fgJnsBupot": "BPU",
  "tglPembatalan": "15122025",
  "npwpNikPenandatangan": "1234567890123000",
  "namaPenandatangan": "Budi Santoso",
  "dcPenandatangan": "1",
  "serialNumberPenandatangan": "1",
  "userId": "user-xxxxxxxx",
  "passphrasePenandatangan": "<certificate passphrase>"
}

Cancel response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "status": "1",
    "statusMessage": "Success",
    "approvalCode": "",
    "uuid": "..."
  }
}

Note: cancel responses do NOT carry a result object. There is no echoed nomorBupot, no timestamp. The bupot's identity is implicit (the client supplied it in the request).

7.5 BPNR — PPh 26 Non-Resident

Bupot PPh 26 for payments to non-resident counterparties. Uses a dedicated endpoint family (no fgJnsBupot in the body) and a distinct counterparty schema oriented around foreign-resident identity rather than NPWP / NIK.

7.5.1 Endpoint summary

7.5.2 Delta from the bpu-a0-21 family

BPNR shares the common envelope (fgTransaction, npwpPemotong, idTku, masaPajak, tahunPajak, signing fields). The differences are in counterparty fields and detail-object shape.

Removed (compared to bpu-a0-21):

• fgJnsBupot — not present in BPNR body (URL identifies the variant)
• fgNpwpNik, npwp, nik, nama — replaced by the foreign-resident counterparty fields below
• dataDetilBpu / dataDetilA0 / dataDetilBp21 wrapper — BPNR sends detail fields flat at top level (no wrapper)

Added (foreign-resident counterparty):

Detail fields (flat at top level — no wrapper):

Response shape: identical to bpu-a0-21 except tanggalSP2D is omitted from the result object.

7.6 BPCY — Cumulative Payment

Bupot Cumulative Payment is used for SPT correction line items. Its endpoint family has no in-body discriminator and a simplified counterparty schema — the withholding entity itself is treated as the counterparty (used in scenarios where a previously declared withholding is being corrected).

7.6.1 Endpoint summary

7.6.2 Delta from the bpu-a0-21 family

• No fgJnsBupot in request body (URL discriminates)
• No separate counterparty NPWP/NIK fields — the withholding entity's own npwpPemotong is reused for both sides
• Detail fields are flat at the top level (no wrapper); shape is otherwise the BPPU detail shape
• Casing inversion: pasalPph / statusPph — lowercase p (like BPNR, not BPU)
• statusPph value form differs: "Final" or "Tidak Final" — title case, Indonesian. Not the uppercase enum form. Response shape: as bpu-a0-21 minus tanggalSP2D; approvalCode is null (not empty string) in observed responses.

7.7 BPSP — Self-Payment

Bupot Self-Payment is used when the withholding entity itself remits tax to DJP directly (Surat Setoran Pajak line items). Like BPCY, the counterparty resolves to the withholding entity itself; the detail object extends BPCY's with fields tracking domestic vs foreign income split.

7.7.1 Endpoint summary

7.7.2 Delta from BPCY

BPSP shares the BPCY envelope plus seven additional income-split fields in the detail block:

Casing rules identical to BPCY: lowercase pasalPph / statusPph; title-case Indonesian status values.

7.8 BPA1, BPA2 — Annual Employee Year-End

BPA1 (private-sector employees) and BPA2 (government employees) cover the year-end summary of an employee's PPh 21 withholdings. They share a single endpoint family. The variant is selected by which of two detail blocks is populated in the request body.

7.8.1 Endpoint summary

7.8.2 Variant selection by payload

The request body carries a fgJnsBupot field set to "A1" or "A2" plus exactly one populated detail block:

7.8.3 Counterparty fields (employee)

The counterparty schema is richer than for the other families — these endpoints serve year-end aggregates for known employees:

7.8.4 Detail object — BPA1 (private-sector A1)

dataDetilBupotA1 carries the year-end gross-up and salary components:

The request body also carries year-end aggregate fields at the TOP level (not inside the detail wrapper): pkpSetahunDisetahunkan, pph21Terutang, pph21DapatDikreditkan, pph21DariBupotSebelumnya, pph21KurangLebihBayar, pph21SetahunDisetahunkan, totalPenghasilanNeto*, totalPenghasilanBruto, totalPengurang, blnPenghasilanDisetahunkan, noBupotSebelumnya, pph21WithheldDtp.

7.8.5 Detail object — BPA2 (government A2)

dataDetilBupotA2 has government-employee-specific fields and a different income structure:

7.8.6 Response shape — BPA1 / BPA2 create

Different response shape. Unlike the other variant families which return ~7 fields in result, BPA1 / BPA2 create responses return 16 fields. Response result includes the year-end aggregates that DJP computed server-side, not just the bupot identifier. Plan client-side parsing accordingly.

Note: pphDipotong and tanggalSP2D are NOT present in BPA1 / BPA2 responses (which the prior families do return). Postman's example response — modelled on BPPU — is not representative for A1 / A2 and should be ignored when integrating these variants.

7.9 verify-document

POST /v2/ebupot/verify-document

Refreshes the DJP-side state of a previously-issued bupot. Used for reconciliation — to confirm a bupot's status after creation, after a cancel, or as part of a periodic batch check. Returns the current DJP state including the bupot's signing status.

7.9.1 Request

fgJnsBupot on verify routes all variants through one path. The verify-document endpoint applies regardless of which create endpoint originally issued the bupot. The fgJnsBupot value on verify is BPU for BPPU/BPMP/BP21/BPCY/BPSP, and BPNR26 for BPNR. There is no value for A1/A2 verify in current code — verify these via the year-end reconciliation reports rather than this endpoint.

7.9.2 Example

POST /v2/ebupot/verify-document HTTP/1.1
Host: gateway-integration.sipajak.com
Authorization: Basic <base64-encoded credentials>
npwp: 1234567890123000
Content-Type: application/json
{
  "npwpPemotong": "1234567890123000",
  "tahunPajak": "2025",
  "noBupot": "25000IFL6",
  "idBupot": "a983bdea-ad66-4660-a002-9bc9d58c093f",
  "fgJnsBupot": "BPU",
  "userId": "user-xxxxxxxx"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "status": "1",
    "statusMessage": "Success",
    "result": {
      "idPenerimaPenghasilan": "2345678901234000",
      "statusBupot": "NORMAL-DONE",
      "kodeObjekPajak": "24-104-05",
      "pphDipotong": 20000,
      "dokReferensi": [
        {
          "dokReferensi":
"https://coretaxdjp.pajak.go.id/.../DocumentExternalLink/6c52b2b3-...",
          "nomorDokumen": "REF-2025-001",
          "tanggal_Dokumen": "2025-11-25 00:00:00"
        }
      ],
      "timestamp": "2025-12-10 08:40:39"
    },
    "uuid": "..."
  }
}

Two specifics worth noting on the response. First, the result.statusBupot value is a hyphen-joined composite of two enums: <document-status>-<signing-status>. "NORMAL-DONE" means document status NORMAL with signing status DONE. The full enum is documented in section 7.12. Second, the tanggal_Dokumen format inside dokReferensi here is YYYY-MM-DD HH:mm:ss, NOT the DDMMYYYY used in create requests — the verify response always uses the full datetime form.

7.10 Calculation utilities

Two local calculator endpoints help clients compute PPh 21 amounts before issuing a bupot. They run pure math — they do not call DJP, do not persist anything, and do not require authentication. Treat them as utilities, not part of the transactional flow.

Unauthenticated by design. These two endpoints are intentionally public — no Basic Auth, no npwp header required. They exist as helper calculators for client integrations and consumer-facing tooling. The intentional public exposure is consistent with the fact that the calculations are pure functions of the input — no DJP credential, no PII access. Do not infer that other Sipajak endpoints are similarly unauthenticated.

7.10.1 PPh 21 / BPMP calculator

POST /calculation

Computes monthly PPh 21 owed under the standard non-final brackets. Used by BPMP (employee withholding) and BP21 (PPh 21 monthly) workflows to derive pphDipotong before submission.

Request fields broadly mirror the dataDetilBp21 / dataDetilA0 input shape — gross income, PTKP status, deductions, etc. — and the response returns the computed tax with a per-bracket breakdown. The response is wrapped in the standard Sipajak {status_code, message, data} envelope.

7.10.2 BPA1 year-end calculator

POST /calculation/bpa1

Computes the year-end gross-up PPh 21 settlement for BPA1. Implements the progressive bracket schedule plus the gross-up factor when tunjanganPPhGrossUp is enabled.

7.11 Reference catalogues

Each variant has its own reference catalogue exposed under /v1/ref-{variant}/* — an unauthenticated set of read-only GETs used to populate client UI dropdowns and validate input. Eight variant prefixes are available: bppu, bpnr, bpcy, bpsp, bp21, bpmp, bpa1, bpa2.

7.11.1 Endpoint pattern

7.11.2 Common query parameters

7.11.3 Response envelope

{
  "status_code": 200,
  "message": "OK",
  "data": {
    "count": 166,
    "limit": 10,
    "page": 0,
    "data": [
      { "tax_object": "Bunga Deposito yang Ditempatkan di Dalam Negeri (IDR, tenor 1 bulan)"
},
      { "tax_object": "Bunga Deposito yang Ditempatkan di Dalam Negeri (IDR, tenor 3 bulan)"
}
    ]
  }
}

Schema diverges by variant. The per-variant reference tables do not share an identical schema. ref-bppu through ref-bp21 follow the canonical seven-category model. ref-bpa1 substitutes a gross_up factor for tax_rate. ref-bpa2 is minimal — it lacks facility_code, facility_name, tax_rate, tax_base, and income_tax_status entirely. Client code that consumes references should branch on variant or accept the missing columns gracefully.

7.11.4 No client-side caching guidance

Reference data changes infrequently (typically annually, when DJP issues an updated bracket table). Aggressive caching is safe — daily or weekly refresh is appropriate. Reference endpoints do not appear in audit logs (no decorator), so they cannot be debugged via the standard reconciliation flow — keep this in mind when troubleshooting integrations.

7.12 Status enums

The verify-document response's result.statusBupot field is a hyphen-joined composite of a document-status enum and a signing-status enum: <statusBupot>-<statusSigningBupot>. Both halves are listed below.

7.12.1 Document status

7.12.2 Signing status

Examples of the composite statusBupot value:

• NORMAL-DONE — bupot is effective and fully signed
• SUBMITTED-SIGNING_IN_PROGRESS — bupot accepted by DJP, signing pending
• CANCELLED-DONE — cancellation complete and signed
• INTERFACE_INVALID-FAILED — bupot rejected; check the DJP error returned at create time

7.13 Error catalogue

DJP returns Bahasa Indonesia messages for business-level failures via body.response.statusMessage. The table below lists representative messages observed in production and staging traffic on the bpu-a0-21 endpoints. The message space is shared across variants — counterparty errors, period errors, and validation errors follow the same pattern.

7.14 Error handling reference