openapi: 3.1.0
info:
  title: Nomba Accounts Order Management API
  description: The Nomba Accounts API enables developers to manage business accounts on the Nomba platform. It provides endpoints for retrieving account details, fetching the parent account balance, and listing terminals assigned to an account. This API serves as the foundation for account management operations within the Nomba ecosystem.
  version: 1.0.0
  contact:
    name: Nomba Developer Support
    url: https://developer.nomba.com
  termsOfService: https://nomba.com/terms
servers:
- url: https://api.nomba.com
  description: Production Server
- url: https://sandbox.nomba.com
  description: Sandbox Server
security:
- bearerAuth: []
tags:
- name: Order Management
  description: Endpoints for retrieving order details and managing checkout transactions.
paths:
  /v1/checkout/order/{orderReference}:
    get:
      operationId: getOrderDetails
      summary: Get order details by order reference
      description: Retrieves the details of a checkout order using the generated order reference. This can be used to check the current status and details of a payment order.
      tags:
      - Order Management
      parameters:
      - name: orderReference
        in: path
        required: true
        description: The unique order reference generated when the order was created.
        schema:
          type: string
      - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Order details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetailsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    accountId:
      name: accountId
      in: header
      required: true
      description: The unique identifier of the parent business account.
      schema:
        type: string
  schemas:
    OrderDetailsResponse:
      type: object
      properties:
        code:
          type: string
          description: Response status code.
          example: '00'
        description:
          type: string
          description: Human-readable description of the response.
          example: Success
        data:
          type: object
          properties:
            orderReference:
              type: string
              description: The unique order reference.
            amount:
              type: number
              format: double
              description: The order amount.
            currency:
              type: string
              description: The currency of the order.
            status:
              type: string
              description: The current status of the order.
              enum:
              - pending
              - successful
              - failed
              - cancelled
            createdAt:
              type: string
              format: date-time
              description: The date and time the order was created.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error status code.
        description:
          type: string
          description: Human-readable description of the error.
        errors:
          type: array
          description: List of specific error details.
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth2 bearer token obtained from the Nomba Authentication API.
externalDocs:
  description: Nomba Accounts API Documentation
  url: https://developer.nomba.com/nomba-api-reference/accounts/fetch-terminals-assigned-to-an-account