inquiry

Endpoint

POST https://{{host}}/api/v1/inquiry

Available Request Headers

Key	Value
Content-Type	application/json
x-api-key	51f4b8ad3a4c9f0859253700436f0a343d05602761c306c4cb514215fdf33c5a

Available Request Query Params

No Params

Available Request Body

{
  "bill_number": "081230000009",
  "product_code": "TELKOM_POSTPAID",
  "reference_id": "your-unique-id-2025-000123"
}

Sample Request and Response

success

Sample Request

Headers

Key	Value
Content-Type	application/json
x-api-key	51f4b8ad3a4c9f0859253700436f0a343d05602761c306c4cb514215fdf33c5a

Params

No Params

Body

{
  "bill_number": "081230000009",
  "product_code": "TELKOM_POSTPAID",
  "reference_id": "your-unique-id-2025-000123"
}

Sample Response

{
  "data": {
    "request_id": "01KAGRHEMR0341YR52FFQ4SX1S",
    "product_code": "TELKOM_POSTPAID",
    "bill_number": "081230000009",
    "bill_amount": 5500,
    "reference_id": "your-unique-id-2025-000123",
    "additional_info": {
      "serial_number": "03357875092/112023/05/0003",
      "idtrx": "01KAGRHEMR0341YR52FFQ4SX1S",
      "balance": "50.850"
    },
    "biller_code": "200",
    "biller_message": "Transaction successful"
  },
  "status_code": "200",
  "status_message": "Transaction successful"
}

error

Sample Request

Headers

Key	Value
Content-Type	application/json
x-api-key	51f4b8ad3a4c9f0859253700436f0a343d05602761c306c4cb514215fdf33c5a

Params

No Params

Body

{
  "bill_number": "081230000009",
  "product_code": "TELKOM_POSTPAID",
  "reference_id": "your-unique-id-2025-000123"
}

Sample Response

{
  "data": null,
  "status_code": "500",
  "status_message": "Third party error",
  "error": "inquiry failed"
}

Documentation

Starts an inquiry for products that require bill / fee computation or preliminary validation prior to Payment. Returns a temporary request_id (billing products) or validation data (game voucher) plus normalized amount components. Use the request_id in the subsequent Payment call when returned. If you provide a reference_id in the request, it will be echoed back in responses and status/callbacks for easier end‑to‑end reconciliation on your side.

Endpoint

POST /api/v1/pre-order/inquiry

Headers

Header	Required	Description
x-api-key	Yes	Client API key issued by Snapcart
Content-Type	Yes	application/json

Query Parameters

(None)

Request Body

Send only product-relevant identification fields. Unused fields must be omitted.

Field	Type	Length	Required	Description
product_code	string	1–64	Yes	Product code assigned to the client.
bill_number	string	8–18	Conditional	Billing identifier (BPJS / postpaid). Required for billing products.
user_id	string	1–32	Conditional	Game voucher player ID (if product requires player validation).
zone_id	string	1–16	Conditional	Game voucher zone / region (if required by the vendor).
reference_id	string	1–100	Optional	Your client‑supplied correlation ID. Echoed back in Inquiry/Payment responses, Payment Status, and Callback. Use letters, digits, dash, underscore; case‑sensitive. Avoid PII (Personally Identifiable Information).

Notes:

Provide only one identification set: (bill_number) OR (user_id + zone_id) depending on product family.
item_code appears only if a product variant must be locked at inquiry (most products resolve item at payment).
reference_id helps you trace the flow across your systems; Snapcart treats it as opaque and returns it verbatim in downstream responses.
request_id is Snapcart‑generated and is the authoritative key for Payment Status and callback matching; see “About request_id” below.

About request_id

Snapcart generates request_id and returns it in Inquiry/Payment responses (billing flows and some product families).
Use request_id for Payment Status polling and to match Callback events.
If your Payment call times out, query Payment Status using the known request_id before retrying Payment to avoid duplicate charges.
Do not reuse a request_id across different product_code or new flows; generate a fresh flow when needed.

Sample Request (BPJS / Postpaid)

{
  "product_code": "TELKOM_POSTPAID",
  "bill_number": "081230000009",
  "reference_id": "your-unique-id-2025-000123"
}

Sample Request (Game Voucher User Validation)

{
  "product_code": "ML-DIAMONDS-86",
  "user_id": "Player123",
  "zone_id": "SEA",
  "reference_id": "your-unique-id-2025-000123"
}

Successful Response (Game Voucher)

Game voucher inquiries often only validate the player and return enrichment like in‑game name (IGN). Amount fields may be 0.0 because cost is determined at payment.

{
  "data": {
    "ign": "1234"
  },
  "status_code": "200",
  "status_message": "Transaction successful"
}

Field notes (game voucher):

Field	Type	Description
ign	string	In‑game name resolved from vendor/player lookup.

Successful Response (PPOB Postpaid / BPJS)

{
  "data": {
    "request_id": "01K9Y5K0YP9B1MPKCEVJCACZ3B",
    "product_code": "TELKOM_POSTPAID",
    "bill_number": "081230000009",
    "bill_amount": 5500,
    "reference_id": "your-unique-id-2025-000123",
    "additional_info": {
      "serial_number": "03357875092/112023/05/0003",
      "idtrx": "01K9Y5K0YP9B1MPKCEVJCACZ3B",
      "balance": "50.850"
    },
    "biller_code": "200",
    "biller_message": "Transaction successful"
  },
  "status_code": "200",
  "status_message": "Transaction successful"
}

Field explanations (BPJS / Postpaid):

Field	Type	Description
request_id	string	Correlation ID required for subsequent Payment & status polling.
product_code	string	Echo of requested product.
bill_number	string	Billing identifier provided in request.
bill_amount	number	Base bill amount before any fee (fee may be calculated later).
reference_id	string	Echo of your client‑supplied ID for reconciliation across your systems.
additional_info	object	Product/vendor specific enrichment (may differ per product; can be empty).
serial_number	string	Vendor reference / composed billing serial (inside additional_info).
idtrx	string	Vendor transaction reference (inside additional_info).
balance	string	Client or vendor reported balance context (string format).
biller_code	string	Raw upstream biller response code.
biller_message	string	Raw upstream biller response message.

Additional Info Object

Aspect	Details
Optional Presence	May be `{}` for products that return no extra enrichment.
Schema Variability	Keys differ per product_code (do not hard‑code globally).
Usage	Display or logging; do not rely for core logic.

Do not fail parsing if fields under additional_info are missing. Design clients to ignore unknown keys.

Error Responses (Examples)

Validation Error (missing product_code):

{
  "status_code": "400",
  "status_message": "Bad request",
  "error": "Required field (product_code)"
}

Incorrect Bill Number:

{
  "status_code": "400",
  "status_message": "Incorrect bill number",
  "error": "Bill number validation failed"
}

Product Not Found:

{
  "status_code": "404",
  "status_message": "Product not found",
  "error": "Inactive or invalid product_code"
}

Insufficient Balance (still returns computed bill data when applicable):

{
  "status_code": "402",
  "status_message": "Insufficient balance",
  "error": "Insufficient balance - current balance 50.850"
}

Next Step After Inquiry

If status_code:

"200" (success context): For billing products proceed to Payment using request_id before any expiry SLA. For game voucher, proceed directly to Payment; no request_id might be needed if not returned.
"402" Insufficient balance: Top-up wallet, then repeat inquiry (do not attempt Payment).
Other failure (4xx / 5xx): Fix the issue (payload/product config) and re-initiate inquiry.

Payment Endpoint: POST /api/v1/pre-order/payment
Minimal body:

{
  "product_code": "TELKOM_POSTPAID",
  "request_id": "01K9Y5K0YP9B1MPKCEVJCACZ3B",
  "reference_id": "your-unique-id-2025-000123"
}

(Include user_id / zone_id / item_code if required by product).

Notes

Do not reuse a request_id for another product_code.
Inquiry does not finalize the transaction; Payment step is required.
additional_info can be empty and differs for each product_code—never rely on a fixed shape.
Always log: request_id (if present), product_code, bill_amount, any additional_info keys, and your reference_id for audit/reconciliation.

Endpoint​

Available Request Headers​

Available Request Query Params​

Available Request Body​

Sample Request and Response​

success​

Sample Request​

Headers​

Params​

Body​

Sample Response​

error​

Sample Request​

Headers​

Params​

Body​

Sample Response​

Documentation​

Endpoint​

Headers​

Query Parameters​

Request Body​

About request_id​

Sample Request (BPJS / Postpaid)​

Sample Request (Game Voucher User Validation)​

Successful Response (Game Voucher)​

Successful Response (PPOB Postpaid / BPJS)​

Additional Info Object​

Error Responses (Examples)​

Next Step After Inquiry​

Notes​

Endpoint

Available Request Headers

Available Request Query Params

Available Request Body

Sample Request and Response

success

Sample Request

Headers

Params

Body

Sample Response

error

Sample Request

Headers

Params

Body

Sample Response

Documentation

Endpoint

Headers

Query Parameters

Request Body

About request_id

Sample Request (BPJS / Postpaid)

Sample Request (Game Voucher User Validation)

Successful Response (Game Voucher)

Successful Response (PPOB Postpaid / BPJS)

Additional Info Object

Error Responses (Examples)

Next Step After Inquiry

Notes