openapi: 3.0.3
info:
  version: 1.0.0
  title: Electrum EPC Testing Platform API
  description: >
    The Electrum EPC Testing Platform API is an API which Corporate Clients can
    use to interact with the Electrum EPC Testing 

    Platform. The API allows Corporate Clients to initiate test transactions and
    to query test result data.
  contact:
    name: Electrum Support
    email: support@electrum.co.za
    url: https://electrum.co.za
  x-logo:
    url: >-
      https://electrumpayments.github.io/qr-payment-service-interface-docs/images/logo-small.png
  license:
    name: proprietary
    url: https://www.electrum.co.za
servers:
  - url: https://sandbox.electrum.dev/epc/testing/platform/api/v1
    description: Electrum EPC Testing Platform API
tags:
  - name: initiation
    description: >-
      Operations that participate in initiating a test transaction through the
      Electrum EPC Testing Platform.
  - name: query
    description: >-
      Operations that participate in querying the status of an existing test
      transaction
paths:
  /tests/{uetr}:
    get:
      tags:
        - initiation
        - query
      summary: Return the set of states for an initiated transaction
      description: >
        This operation is a **synchronous** request.


        Instructs Electrum to collect and return the set of states for an
        initiated transaction. The response of this 

        operation is a list of these states.
      operationId: TestQuery
      parameters:
        - in: path
          name: uetr
          description: The UETR/UUID for the transaction being queried
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: >-
            OK. [RFC9110 -
            200](https://www.rfc-editor.org/rfc/rfc9110#name-200-ok)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '400':
          description: >-
            Bad request. [RFC9110 -
            400](https://www.rfc-editor.org/rfc/rfc9110#name-400-bad-request)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            Not found. [RFC9110 -
            404](https://www.rfc-editor.org/rfc/rfc9110#name-404-not-found)
        '422':
          description: >-
            Unprocessable content. [RFC9110 -
            422](https://www.rfc-editor.org/rfc/rfc9110#name-422-unprocessable-content)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            Too Many Requsts. [RFC6585 -
            429](https://www.rfc-editor.org/rfc/rfc6585.html#section-4)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >-
            Internal server error. [RFC9110 -
            500](https://www.rfc-editor.org/rfc/rfc9110#name-500-internal-server-error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Service unavailable. [RFC9110 -
            503](https://www.rfc-editor.org/rfc/rfc9110#name-503-service-unavailable)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tests:
    post:
      tags:
        - initiation
      summary: Initiates a test transaction from the EPC Testing Platform
      description: >
        This operation is a **synchronous** request.


        Instructs Electrum to initiate a test transaction from the EPC Testing
        Platform. The response of this operation 

        is the UETR/UUID for the initiated transaction
      operationId: Test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiationRequest'
        required: true
      responses:
        '200':
          description: >-
            OK. [RFC9110 -
            200](https://www.rfc-editor.org/rfc/rfc9110#name-200-ok)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiationResponse'
        '400':
          description: >-
            Bad request. [RFC9110 -
            400](https://www.rfc-editor.org/rfc/rfc9110#name-400-bad-request)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            Not found. [RFC9110 -
            404](https://www.rfc-editor.org/rfc/rfc9110#name-404-not-found)
        '422':
          description: >-
            Unprocessable content. [RFC9110 -
            422](https://www.rfc-editor.org/rfc/rfc9110#name-422-unprocessable-content)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            Too Many Requsts. [RFC6585 -
            429](https://www.rfc-editor.org/rfc/rfc6585.html#section-4)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >-
            Internal server error. [RFC9110 -
            500](https://www.rfc-editor.org/rfc/rfc9110#name-500-internal-server-error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Service unavailable. [RFC9110 -
            503](https://www.rfc-editor.org/rfc/rfc9110#name-503-service-unavailable)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    QueryResponse:
      type: object
      required:
        - states
      properties:
        states:
          type: array
          items:
            type: string
    InitiationRequest:
      type: object
      required:
        - testId
        - initiationDetails
      properties:
        testId:
          type: string
        initiationDetails:
          $ref: '#/components/schemas/InitiationDetails'
    InitiationDetails:
      type: object
      required:
        - domain
        - proxy
      properties:
        domain:
          type: string
          description: >
            A BankservAfrica-specific field requirement that associates this
            institution with a specific "domain"

            - which is essentially a type of namespace.


            This value should correspond to the the Corporate Client who is
            initiating the request's domain
        proxy:
          type: string
          description: |
            The value for which the proxy resolution will be performed
        proxyType:
          type: string
          description: >
            The type of proxy, such as MBNO (mobile number) or CUST (custom).
            Initiations will default to `MBNO` if this

            is not set.
          enum:
            - MBNO
            - CUST
        amount:
          type: number
          format: double
          minimum: 0
          description: >
            The payment amount in the denomination of the indicated currency, in
            the

            format '<major units>.<minor units> with the number of minor units
            (fractional digits)

            compliant with the number of decimal places published in ISO 4217.
        creditorReference:
          type: string
          description: |
            The reference for the creditor
    InitiationResponse:
      type: object
      properties:
        uetr:
          description: The UETR/UUID for the newly initiated transaction
          type: string
          format: uuid
    ErrorResponse:
      type: object
      properties:
        reason:
          description: The reason why the test initiation failed
          type: string
        description:
          description: A full description explaining the failure in detail
          type: string
