payment status

Endpoint

GET https://{{host}}/api/v1/payment/status/:request_id

Available Request Headers

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

Available Request Query Params

Name	Value	Type
request_id	01KAAK805PM67SM4YDMZK1HQXX	path

Available Request Body

No body defined.

---

Sample Request and Response

success

Sample Request

Headers

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

Params

Name	Value	Type
request_id	01KAAK805PM67SM4YDMZK1HQCS	path

Body

No body defined.

Sample Response

{
  "data": {
    "order_id": "01KAAKB7V3PD0MHDXWN2MS8JV8",
    "payment_id": "01KAAKB7XZH84V6SJGNHSKGS9Y",
    "reference_id": "your-unique-id-2025-000123",
    "product_code": "VAO2",
    "amount": 10000,
    "biller_code": "200",
    "biller_message": "Transaction successful",
    "request_at": "2025-11-18T04:25:10Z",
    "updated_at": "2025-11-18T04:25:11Z"
  },
  "status_code": "200",
  "status_message": "Transaction successful"
}

---

error

Sample Request

Headers

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

Params

Name	Value	Type
request_id	01KAAK805PM67SM4YDMZK1HQXX	path

Body

No body defined.

Sample Response

{
  "data": null,
  "status_code": "404",
  "status_message": "Transaction not found",
  "error": "Failed to get order"
}

---

Documentation

Retrieve the latest processing state of a transaction using its request_id. Poll this endpoint until a final status is known or until you receive a callback. If you included a reference_id in Inquiry/Payment, it will be echoed here to help correlate with your internal order. Prefer callback for production and use polling as a fallback.

About IDs:

• request_id is generated by Snapcart and is the authoritative correlation key for Payment Status and callback matching. If your Payment call times out, query this endpoint with the known request_id before attempting a new Payment to avoid duplicates.
• reference_id is your client-supplied identifier; it is returned verbatim in responses/callbacks and should be stored together with request_id for reconciliation.

Endpoint

GET /api/v1/pre-order/payment/status/:request_id

Headers

Header	Required	Description
x-api-key	Yes	Client API key issued by Snapcart

Path Parameters

Name	Type	Length	Required	Description
request_id	string	26	Yes	Snapcart-generated correlation ID returned by Inquiry (two-step) or Payment (one-step). Use for status checks and callback correlation; do not reuse across different product_code.

Query Parameters

(None)

Request Body

(None)

---

Response Envelope (Unified)

{
  "status_code": "200",
  "status_message": "Transaction successful",
  "data": { ... }
}

Field	Type	Notes
status_code	string	Unified code (see Appendix).
status_message	string	Unified message mapped from vendor/internal status.
data	object	Current transaction status snapshot.

Data Object

Field	Type	Required	Description
order_id	string	Yes	Internal order identifier.
payment_id	string	Yes	Internal payment identifier.
reference_id	string	Optional	Echo of your client-supplied ID (if provided in Inquiry/Payment).
product_code	string	Yes	Product code used in the transaction.
amount	number	Yes	Final charged or intended amount (bill + fee if applicable).
biller_code	string	Conditional	Upstream vendor response mapping (e.g. "200"). May differ across vendors.
biller_message	string	Conditional	Upstream vendor raw status text (e.g. "Transaction successful").
request_at	string	Yes	ISO8601 timestamp when the transaction was initiated.
updated_at	string	Yes	ISO8601 timestamp when this status snapshot was produced.

---

Sample Response (Success)

{
  "data": {
    "order_id": "01KAAKB7V3PD0MHDXWN2MS8JV8",
    "payment_id": "01KAAKB7XZH84V6SJGNHSKGS9Y",
    "reference_id": "your-unique-id-2025-000123",
    "product_code": "VAO2",
    "amount": 10000,
    "biller_code": "200",
    "biller_message": "Transaction successful",
    "request_at": "2025-11-18T04:25:10Z",
    "updated_at": "2025-11-18T04:25:11Z"
  },
  "status_code": "200",
  "status_message": "Transaction successful"
}

Sample Response (Pending)

{
  "data": {
    "order_id": "01KAAKB7V3PD0MHDXWN2MS8JV8",
    "payment_id": "01KAAKB7XZH84V6SJGNHSKGS9Y",
    "reference_id": "your-unique-id-2025-000123",
    "product_code": "VAO2",
    "amount": 10000,
    "biller_code": "0068",
    "biller_message": "Transaction is being processed",
    "request_at": "2025-11-18T04:25:10Z",
    "updated_at": "2025-11-18T04:25:14Z"
  },
  "status_code": "200",
  "status_message": "Transaction successful"
}

Sample Response (Failed)

{
  "data": {
    "order_id": "01KAAKB7V3PD0MHDXWN2MS8JV8",
    "payment_id": "01KAAKB7XZH84V6SJGNHSKGS9Y",
    "reference_id": "your-unique-id-2025-000123",
    "product_code": "VAO2",
    "amount": 10000,
    "biller_code": "400",
    "biller_message": "Transaction Failed",
    "request_at": "2025-11-18T04:25:10Z",
    "updated_at": "2025-11-18T04:27:42Z"
  },
  "status_code": "200",
  "status_message": "Transaction successful"
}

Sample Response (Inquiry Expired / Two-Step Timeout)

{
  "data": {
    "order_id": "01KAAKB7V3PD0MHDXWN2MS8JV8",
    "payment_id": "01KAAKB7XZH84V6SJGNHSKGS9Y",
    "reference_id": "your-unique-id-2025-000123",
    "product_code": "BPJS-KS",
    "amount": 105000,
    "biller_code": "410",
    "biller_message": "Inquiry expired",
    "request_at": "2025-11-18T04:00:10Z",
    "updated_at": "2025-11-18T04:30:11Z"
  },
  "status_code": "200",
  "status_message": "Transaction successful"
}

Usage Guidelines

Scenario	Action
status_code=200 & message="Transaction is being processed"	Continue polling or await callback.
status_code=200 & message="Transaction successful"	Mark transaction as settled; stop polling.
status_code in 400,402,404,409,410,500+	Terminal failure; apply remedial flow (retry new payment, top-up balance, redo inquiry).
No change in updated_at across polls	Increase poll interval or set max wait threshold.

Polling Recommendation:

• Interval: ~5s
• Max attempts: 30 (≈150s) then alert / fallback to manual review.
• Strongly recommended: rely on callback for production and keep polling minimal as a fallback.

Next Step After Status

• Final success: finalize fulfillment & accounting.
• Final failure (e.g. 400 Transaction failed, 410 Inquiry expired): surface error to end-user; restart appropriate flow.
• Pending persists beyond SLA: escalate internally; continue until callback or manual timeout.

Notes

• reference_id is echoed when provided in Inquiry/Payment; store it alongside request_id for reconciliation and support tracing.
• request_id is Snapcart-generated and must be used for Payment Status queries and callback correlation; if a Payment call times out, check status with this request_id before submitting a new Payment.
• biller_code may not always align 1:1 with status_code (pending codes upstream may still map to unified 200). Always rely on status_code + status_message for authoritative classification.
• additional_info (if later added to status) will follow the same optional pattern as in callbacks.