> ## Documentation Index > Fetch the complete documentation index at: https://erp-developer.starpayethiopia.com/llms.txt > Use this file to discover all available pages before exploring further. # Transaction status (SSE) > Opens an **SSE** (`text/event-stream`) connection that pushes status updates for the given `billRefNo` in real time. Typical events include an initial status (for example `UNPAID`), then updates when the payment completes. A final event may include `"_closed": true`. Request format example: `/txn-sse?billRefNo=T584KP095O` (gateway route in this spec: `/erp/api/txn-sse?billRefNo=...`). Important: the full HTTP response is an **SSE stream**, not one JSON object. Parse each `data:` event payload as JSON. Raw `text/event-stream` example: ```bash data: {"status":"UNPAID"} data: {"amount":1,"billRefNo":"T584KP095O","externalReference":"DE50JURNL0","merchantId":"698856835bf6c24fd5ff3dac","merchantName":"jimma merchant","paymentChannel":"USSD_PUSH","status":"PAID","transactionId":"a407e6fa-3a77-49db-93fb-02e8a9c2d28f","paidAt":"05 May 2026, 8:15 AM","customerName":"tesfaye","customerPhoneNumber":"+251944719460","commissionAmount":0.02,"redirectUrl":"","paidAmount":0.98,"updatedAt":"2026-05-05T05:15:41.341Z"} data: {"amount":1,"status":"PAID","_closed":true} ``` If you do not receive a definitive update within **15 seconds**, close the stream and use **`POST /erp/check-txn`** with the same `billRefNo` to poll status. Use this endpoint for **real-time transaction status** updates using **Server-Sent Events (SSE)**. The response is **not one JSON object**. It is an SSE stream (`text/event-stream`) containing multiple events over time. ## how SSE works * Your client opens one long-lived HTTP `GET` request to `/erp/api/txn-sse?billRefNo=...`. * Accepted query format is `/txn-sse?billRefNo=T584KP095O` (gateway route: `/erp/api/txn-sse?billRefNo=...`). * The server keeps the connection open and pushes updates as event lines: * `data: {"status":"UNPAID"}` * `data: {"status":"PAID", ...}` * Parse each `data:` line as JSON. * A final event can include `_closed: true`. Do not run `JSON.parse()` on the entire HTTP response body. Parse each `data:` event payload separately. ## when to use fallback If SSE does not provide a definitive result within **15 seconds**, close the stream and call `POST /erp/check-txn` with the same `billRefNo` for manual status check. ## implementation notes * Include the `x-api-secret` header. * Use a request timeout and reconnect strategy in your client. * Do not open multiple SSE streams for the same `billRefNo` unless needed. ## raw SSE stream example ```bash theme={null} data: {"status":"UNPAID"} data: {"amount":1,"billRefNo":"T584KP095O","externalReference":"DE50JURNL0","merchantId":"698856835bf6c24fd5ff3dac","merchantName":"jimma merchant","paymentChannel":"USSD_PUSH","status":"PAID","transactionId":"a407e6fa-3a77-49db-93fb-02e8a9c2d28f","paidAt":"05 May 2026, 8:15 AM","customerName":"tesfaye","customerPhoneNumber":"+251944719460","commissionAmount":0.02,"redirectUrl":"","paidAmount":0.98,"updatedAt":"2026-05-05T05:15:41.341Z"} data: {"amount":1,"billRefNo":"T584KP095O","status":"PAID","_closed":true,"updatedAt":"2026-05-05T05:15:41.341Z"} ``` ## OpenAPI ````yaml GET /api/txn-sse openapi: 3.1.0 info: title: StarPay API version: 1.0.0 description: > StarPay API is a RESTful API that provides access to various functionalities of the StarPay system. This API allows users to manage product categories, including creating, updating, deleting, and retrieving product categories. The API uses JWT for thirdparty and supports various response formats. **Transaction status** Use **real-time** `GET /erp/api/txn-sse` (Server-Sent Events) to follow status updates for a `billRefNo`. If the SSE stream does not yield a usable result within **15 seconds**, call **`POST /erp/check-txn`** with the same `billRefNo` to poll the current transaction status. servers: - url: https://starpayqa.starpayethiopia.com/v1/starpay-api description: Local server security: [] tags: - name: erp - name: thirdparty paths: /api/txn-sse: get: tags: - erp summary: Transaction status (real-time, Server-Sent Events) description: >- Opens an **SSE** (`text/event-stream`) connection that pushes status updates for the given `billRefNo` in real time. Typical events include an initial status (for example `UNPAID`), then updates when the payment completes. A final event may include `"_closed": true`. Request format example: `/txn-sse?billRefNo=T584KP095O` (gateway route in this spec: `/erp/api/txn-sse?billRefNo=...`). Important: the full HTTP response is an **SSE stream**, not one JSON object. Parse each `data:` event payload as JSON. Raw `text/event-stream` example: ```bash data: {"status":"UNPAID"} data: {"amount":1,"billRefNo":"T584KP095O","externalReference":"DE50JURNL0","merchantId":"698856835bf6c24fd5ff3dac","merchantName":"jimma merchant","paymentChannel":"USSD_PUSH","status":"PAID","transactionId":"a407e6fa-3a77-49db-93fb-02e8a9c2d28f","paidAt":"05 May 2026, 8:15 AM","customerName":"tesfaye","customerPhoneNumber":"+251944719460","commissionAmount":0.02,"redirectUrl":"","paidAmount":0.98,"updatedAt":"2026-05-05T05:15:41.341Z"} data: {"amount":1,"status":"PAID","_closed":true} ``` If you do not receive a definitive update within **15 seconds**, close the stream and use **`POST /erp/check-txn`** with the same `billRefNo` to poll status. operationId: transactionStatusSse parameters: - in: query name: billRefNo required: true description: >- Bill reference to subscribe to. Example call format: `/txn-sse?billRefNo=T584KP095O`. schema: type: string example: T584KP095O responses: '200': $ref: '#/components/responses/TxnSseStreamResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' servers: - url: https://checkout.starpayethiopia.com description: Checkout SSE server components: responses: TxnSseStreamResponse: description: >- Open SSE stream. Each event is one or more lines of the form `data: ` per the Server-Sent Events format. Do not parse the entire stream as one JSON object. content: text/event-stream: schema: $ref: '#/components/schemas/TxnSseStreamResponse' examples: sseStream: $ref: '#/components/examples/TxnSseStreamExample' headers: Cache-Control: description: Typically `no-cache` for SSE. schema: type: string example: no-cache, no-transform BadRequest: description: Bad request. content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestError' Unauthorized: description: Unauthorized. content: application/problem+json: schema: $ref: '#/components/schemas/thirdpartyError' NotFound: description: Not found. content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundError' ServerError: description: internal. content: application/problem+json: schema: $ref: '#/components/schemas/serverError' schemas: TxnSseStreamResponse: type: string description: >- SSE text stream payload. This is protocol framing, not a single JSON document. Parse each `data:` payload as JSON; shape varies (minimal status only, full payment detail, or final object with `_closed`). BadRequestError: type: object properties: status: type: string example: error timestamp: type: string example: '2025-05-07T07:31:30.824Z' path: type: string example: /v2/starpay-api/ error: type: object properties: code: type: string example: BadRequestException message: type: string example: Missing required payload data, pk and payload is required thirdpartyError: type: object properties: message: type: string example: Something wrong status: type: string example: error timestamp: type: string example: '2025-05-07T07:31:30.824Z' path: type: string example: /v2/starpay-api/ error: type: object properties: code: type: string example: GEN_004 message: type: string example: An unexpected server error occurred. NotFoundError: type: object properties: message: type: string example: Something wrong status: type: string example: error timestamp: type: string example: '2025-05-07T07:31:30.824Z' path: type: string example: /v2/starpay-api/ error: type: object properties: code: type: string example: ABC_001 message: type: string example: not found serverError: type: object properties: message: type: string example: Something wrong status: type: string example: error timestamp: type: string example: '2025-05-07T07:31:30.824Z' path: type: string example: /v2/starpay-api/ error: type: object properties: code: type: string example: GEN_004 message: type: string example: An unexpected server error occurred. examples: TxnSseStreamExample: summary: Readable event-by-event SSE payload value: streamType: text/event-stream events: - event: data payload: status: UNPAID - event: data payload: amount: 1 billRefNo: T584KP095O externalReference: DE50JURNL0 merchantId: 698856835bf6c24fd5ff3dac merchantName: jimma merchant paymentChannel: USSD_PUSH status: PAID OR SETTLED transactionId: a407e6fa-3a77-49db-93fb-02e8a9c2d28f paidAt: 05 May 2026, 8:15 AM customerName: tesfaye customerPhoneNumber: '+251944719460' commissionAmount: 0.02 redirectUrl: '' paidAmount: 0.98 updatedAt: '2026-05-05T05:15:41.341Z' - event: data payload: amount: 1 billRefNo: T584KP095O status: PAID OR SETTLED _closed: true updatedAt: '2026-05-05T05:15:41.341Z' ````