Snapcart PPOB API Collection

Version: V.1.0.0

Introduction

This OpenAPI 3.0 service was created to make it easier for partners to integrate their systems with Snapcart's PPOB platform.

Snapcart’s PPOB platform is a digital payment aggregation service that enables the integration of various PPOB products into merchant systems. The platform supports two Transaction Flows: Single-Step and Multi-Step, depending on product characteristics and provider requirements.

Single-Step Transaction Flow

A Single-Step Transaction is completed with a single API call — the Payment Request. This flow is typically used for Prepaid Products such as mobile credit (pulsa) and mobile data packages. However, not all Prepaid Products follow the Single-Step flow. Certain product types still require additional validation steps and must use the Multi-Step flow.

Multi-Step Transaction Flow

A Multi-Step Transaction requires two sequential API calls:

1. Inquiry Request
2. Payment Request

The Inquiry Request is used to validate the customer Identifier (e.g., biller ID, user ID, meter number) and, when applicable, retrieve transaction details such as the Bill Amount or customer information. Once the inquiry is successfully completed, the Payment Request can be performed using the data returned from the inquiry.

Objectives

• Unified business status codes & messages (see Appendix).
• Consistent JSON response envelope across endpoints (see Appendix).
• Clear separation of one-step vs two-step product models.
• Asynchronous processing with request_id + polling for final state.
• Secure API key authentication + client activation + IP allow-listing.
• Optional client-supplied reference_id to correlate your own orders end‑to‑end; echoed in Inquiry/Payment responses, Payment Status, and Client Callback.

All external client-facing endpoints live under: /api/v1/pre-order/ All responses use JSON UTF-8.

IDs and Correlation

• request_id: Snapcart‑generated, returned by Inquiry or Payment; use it for Payment Status queries and to match Client Callbacks. If a Payment call times out, check Payment Status with this request_id before sending a new Payment.
• reference_id: Client‑supplied (optional) identifier you send in Inquiry/Payment; echoed verbatim in subsequent responses and callbacks to help you join with your internal order/checkout records.

Environments

Environment	Base Host Placeholder	Base API Prefix	Example Endpoint
Development	https://{{HostDev}}	/api/v1/pre-order	https://{{HostDev}}/api/v1/pre-order/inquiry
Production	https://{{HostProd}}	/api/v1/pre-order	https://{{HostProd}}/api/v1/pre-order/payment

Authentication

Header	Mandatory	Description
x-api-key	Yes	API key issued per client
Content-Type	Yes (POST)	application/json when sending JSON body

Failure cases:

• Missing API key → "401" Unauthorized (message: API key not found in request)
• Invalid / inactive key → "401"/"403" depending on status (Invalid API key / Client Inactive)

---

Transaction Overview (Flows)

There are two transaction models. The client must know which model a product uses before integrating.

1. Single-step: Payment only

Used by single-step products (e.g. Pulsa, some Game Vouchers) where no preliminary bill calculation is required.

Flow:

1. Client calls Payment directly (no Inquiry). Include reference_id if you want it echoed back in all downstream responses/callbacks.
2. Server returns an immediate queued/pending response (async start).
3. Client obtains final state via:
   • Polling Payment Status, or
   • Pre-Order callback to the client’s registered callback URL once the transaction reaches a final status (Success/Failed).

2. Multi-step: Inquiry → Payment

Used by multi-step products (e.g. BPJS, PPOB Postpaid, Game Voucher) where the final amount must be confirmed first.

Flow:

1. Client calls Inquiry to get bill amount, fee, and a temporary request_id (send reference_id if desired).
2. Client validates balance and optionally shows confirmation to end-user.
3. Client calls Payment with the request_id (and can repeat the same reference_id for continuity).
4. Client obtains final state via:
   • Polling Payment Status, or
   • Pre-Order callback to the client’s registered callback URL once the transaction reaches a final status (Success/Failed).

Asynchronous Payment & Client Callback

Payment execution is asynchronous:

• The initial HTTP 200 from POST /pre-order/payment typically indicates queuing/acknowledgement, not final business success.
• Final business status (Success / Failed / Expired) arrives later.
• Delivery channels for the final state:
  • Polling: GET /pre-order/payment/status/:request_id until a final status.
  • Client Callback: Pre-Order posts a JSON payload to the client’s registered callback URL on final status for both success and error cases.
• Strongly recommended: rely on the Client Callback in production and keep polling minimal as a fallback.

Sequence Diagram — Single-step (Payment only)

Sequence Diagram — Multi-step (Inquiry → Payment)

Endpoint Summary by Flow

Flow Type	Endpoints
One-step	POST /payment → (Callback or Payment Status)
Two-step	POST /inquiry → POST /payment → (Callback or Payment Status)

Notes:

• Always implement Payment Status polling until a final status (Success / Failed / Expired). Prefer the Callback in production for efficiency.
• Client callback is delivered by Pre-Order (to the registered client endpoint) for both success and error outcomes.
• Do not reuse a request_id from an old flow.
• If sent, reference_id is echoed in Inquiry/Payment responses, Payment Status, and Callback to simplify reconciliation.
• Status code list & response envelope details are documented in the Appendix.

---

Best Practices

• Retry only idempotent GET/status calls (not Payment).
• Backoff strategy for transient errors (5xx / 429).
• Include request_id, reference_id, product_code, and timestamps in every support ticket.

Continue to Transaction endpoints for detailed request & response structures.