Transaction status (real-time, Server-Sent Events)

curl --request GET \
  --url https://checkout.starpayethiopia.com/api/txn-sse

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://checkout.starpayethiopia.com/api/txn-sse",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://checkout.starpayethiopia.com/api/txn-sse"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://checkout.starpayethiopia.com/api/txn-sse")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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"
      }
    }
  ]
}

{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "BadRequestException",
    "message": "Missing required payload data, pk and payload is required"
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "ABC_001",
    "message": "not found"
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

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:

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.

GET

api

txn-sse

Transaction status (real-time, Server-Sent Events)

curl --request GET \
  --url https://checkout.starpayethiopia.com/api/txn-sse

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://checkout.starpayethiopia.com/api/txn-sse",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://checkout.starpayethiopia.com/api/txn-sse"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://checkout.starpayethiopia.com/api/txn-sse")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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"
      }
    }
  ]
}

{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "BadRequestException",
    "message": "Missing required payload data, pk and payload is required"
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "ABC_001",
    "message": "not found"
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

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

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"}

Query Parameters

billRefNo

string

required

Bill reference to subscribe to. Example call format: /txn-sse?billRefNo=T584KP095O.

Example:

"T584KP095O"

Response

Open SSE stream. Each event is one or more lines of the form data: <json> per the Server-Sent Events format. Do not parse the entire stream as one JSON object.

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).

Get started

Api Reference

Transaction status (SSE)

how SSE works

when to use fallback

implementation notes

raw SSE stream example

Query Parameters

Response

​how SSE works

​when to use fallback

​implementation notes

​raw SSE stream example

Query Parameters

Response

how SSE works

when to use fallback

implementation notes

raw SSE stream example