> ## 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 check

> Returns the current status for a bill reference. Use this when you need a single JSON response or as a **fallback** if the real-time SSE endpoint (`/erp/api/txn-sse`) does not respond within **15 seconds**.

Use this endpoint for **manual transaction status** checks by `billRefNo`.

## request

Send `POST /erp/check-txn` with:

* Header: `x-api-secret`
* Body: `{ "billRefNo": "..." }`

## response behavior

* Returns current transaction state (for example `PAID` or `FAILED`).
* If available, additional fields are returned (amount, receipt URL, merchant details, and more).

## recommended usage

For real-time tracking, start with `GET /erp/api/txn-sse`.\
If SSE does not return a definitive result within **15 seconds**, use this endpoint as fallback.


## OpenAPI

````yaml POST /erp/check-txn
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:
  /erp/check-txn:
    post:
      tags:
        - erp
      summary: Check transaction status (polling)
      description: >-
        Returns the current status for a bill reference. Use this when you need
        a single JSON response or as a **fallback** if the real-time SSE
        endpoint (`/erp/api/txn-sse`) does not respond within **15 seconds**.
      operationId: checkTransactionStatus
      parameters:
        - in: header
          name: x-api-secret
          required: true
          description: API secret key.
          schema:
            type: string
            example: X0Lkj979tyUv1IPGQkd+qsx0N6o1LQPSUpfBa6ZCKvXosp0HVnciXSIyWmgyBl0B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckTxnRequest'
      responses:
        '200':
          description: >-
            Transaction found; `data.status` indicates outcome (for example
            `PAID` or `FAILED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckTxnResponse'
              examples:
                paid:
                  summary: Paid transaction
                  value:
                    status: success
                    timestamp: '2026-05-05T05:12:33.505Z'
                    message: Transaction found successfully
                    data:
                      billRefNo: 5WL30548HD
                      status: PAID OR SETTLED
                      timestamp: '2026-04-29T17:50:57.863Z'
                      message: Payment successful
                      merchantId: '42723792'
                      customerId: ''
                      externalReferenceId: 075SMPC2316706F7
                      amount: 36500
                      payment_type: OTP_ACCOUNT
                      receipt_url: >-
                        https://receipt.starpayethiopia.com/receiptqa/WST-5WL30548HD
                failed:
                  summary: Failed transaction
                  value:
                    status: success
                    timestamp: '2026-05-05T05:14:11.103Z'
                    message: Transaction found successfully
                    data:
                      billRefNo: EU33Q8706U
                      status: FAILED
                      message: ''
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    CheckTxnRequest:
      type: object
      properties:
        billRefNo:
          type: string
          example: 5WL30548HD
      required:
        - billRefNo
    CheckTxnResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        timestamp:
          type: string
          format: date-time
        message:
          type: string
          example: Transaction found successfully
        data:
          $ref: '#/components/schemas/CheckTxnResponseData'
      required:
        - status
        - timestamp
        - message
        - data
    CheckTxnResponseData:
      type: object
      description: >-
        Transaction details when found. Fields present depend on status (for
        example `PAID` includes amount and receipt; `FAILED` may only include
        `billRefNo`, `status`, and `message`).
      properties:
        billRefNo:
          type: string
          example: 5WL30548HD
        status:
          type: string
          description: Transaction status, for example `PAID` or `FAILED`.
          example: PAID
        timestamp:
          type: string
          format: date-time
          description: Present for some successful payments.
        message:
          type: string
          example: Payment successful
        merchantId:
          type: string
          example: '42723792'
        customerId:
          type: string
          example: ''
        externalReferenceId:
          type: string
          example: 075SMPC2316706F7
        amount:
          type: number
          example: 36500
        payment_type:
          type: string
          example: OTP_ACCOUNT
        receipt_url:
          type: string
          format: uri
          example: https://receipt.starpayethiopia.com/receiptqa/WST-5WL30548HD
      required:
        - billRefNo
        - status
    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.
  responses:
    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'

````