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

# Initiate payment



## OpenAPI

````yaml POST /erp/initiate-payment
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/initiate-payment:
    post:
      tags:
        - erp
      summary: Initiate payment
      operationId: initiatePayment
      parameters:
        - in: header
          name: x-api-secret
          required: true
          description: API secret key.
          schema:
            type: string
            example: MFUxSN98EV5IUU+RhYZh2f866adcTa4F5HJ2dGI3t8+MH3cvfk/gAZ492TnxwdiI
        - in: header
          name: x-message-id
          required: false
          description: Required when `paymentInitiationType` is `OTP`.
          schema:
            type: string
            example: >-
              0a162ea504918e1c85f64da9733b64bf25ff400394f8e1da6cdfb656e1338b9a8fe47e1b32429f13b1495b075857bf98
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiatePaymentRequest'
      responses:
        '200':
          description: Payment initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiatePaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    InitiatePaymentRequest:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/PaymentCustomer'
        amount:
          type: number
          example: 100
        paymentInitiationType:
          type: string
          enum:
            - USSD_PUSH
            - LOCAL_CARD
            - INTERNATIONAL_CARD
            - QR
            - REFERENCE
            - OTP
            - CASH
            - IN_APP_PUSH
          example: USSD_PUSH
        items:
          type: array
          items:
            $ref: '#/components/schemas/PaymentItem'
        customerVat:
          type: number
          example: 0.03
        swift_code:
          type: string
          example: telebirr
        callbackURL:
          type: string
          format: uri
          example: http://localhost:2222/starpay/complete_payment
        currency:
          type: string
          example: ETB
      required:
        - customer
        - amount
        - paymentInitiationType
        - items
        - customerVat
        - swift_code
        - callbackURL
        - currency
    InitiatePaymentResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        timestamp:
          type: string
          format: date-time
        message:
          type: string
          example: Success
        data:
          $ref: '#/components/schemas/InitiatePaymentResponseData'
      required:
        - status
        - timestamp
        - message
        - data
    PaymentCustomer:
      type: object
      properties:
        fullName:
          type: string
          example: Walk-in Customer
        phoneNumber:
          type: string
          example: '+251944719460'
        email:
          type: string
          format: email
          example: customer@gmail.com
        accountNumber:
          type: string
          description: Required when payment type is OTP.
          example: '5075361069011'
      required:
        - fullName
        - phoneNumber
        - email
    PaymentItem:
      type: object
      properties:
        productId:
          type: string
          example: 6812220726f547936d6c1976
        quantity:
          type: integer
          example: 1
        item_name:
          type: string
          example: mobile
        unit_price:
          type: number
          example: 500
      required:
        - productId
        - quantity
        - item_name
        - unit_price
    InitiatePaymentResponseData:
      type: object
      properties:
        bill_ref:
          type: string
          example: NC61HO4977
        customer_name:
          type: string
          example: ''
      required:
        - bill_ref
        - customer_name
    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'

````