openapi: 3.0.0
info:
  description: >-
    The Electrum Prepaid Utility Service describes an interface for facilitating
    the purchase
                      of prepaid tokens for
                      utilities such as electricity and water. One or more tokens for a requested value
                      are issued by an
                      upstream provider (typically a payments aggregator) against a specified meter number.
                      The tokens (each
                      being a sequence of usually 20 digits) are printed on the customer receipt and are
                      input manually on
                      the meter's keypad for the value to be redeemed.
  version: 3.16.0
  title: Prepaid Utility Service Interface
  contact:
    name: Electrum API
    url: https://electrum.co.za/contact
    email: api@electrum.co.za
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
paths:
  /events/tokenPurchases:
    post:
      summary: notifyTokenPurchase
      description: >-
        An event notification to signal that a successful token purchase was
        performed. This operation is for informational purposes only.
        Implementations that do not need to subscribe to this event may simply
        return an HTTP status code `501`.
      operationId: notifyTokenPurchase
      parameters:
        - name: purchaseId
          in: query
          description: The id of the original purchase request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseResponse'
        description: A token purchase response
        required: true
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /faultReports/{requestId}:
    post:
      summary: createFaultReport
      description: >-
        Reports a technical fault on a specified meter. This resource is used
        when a customer wishes to report a technical fault to the utility with
        whom the meter is reqistered.
      operationId: createFaultReport
      parameters:
        - name: requestId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FaultReportRequest'
        description: A fault report
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaultReportResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /keyChangeTokenRequests/{requestId}:
    post:
      summary: createKeyChangeTokenRequest
      description: >-
        Requests a key change token for a specified meter. This resource is used
        when the utility has updated a meter's encryption key and the customer
        required a token to input the new key to the meter. Key change tokens
        are typically supplied as part of a normal purchase, so this operation
        is rarely used.
      operationId: createKeyChangeTokenRequest
      parameters:
        - name: requestId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyChangeTokenRequest'
        description: A key change token request
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyChangeTokenResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /keyChangeTokenRequests/{requestId}/confirmations/{confirmationId}:
    post:
      summary: confirmKeyChange
      description: Confirms that key change tokens have been provided successfully.
      operationId: confirmKeyChange
      parameters:
        - name: requestId
          in: path
          description: The randomly generated UUID of the original request.
          required: true
          schema:
            type: string
        - name: confirmationId
          in: path
          description: The randomly generated UUID of this confirmation.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyChangeConfirmation'
        description: A key change confirmation
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicAdvice'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /meterLookups/{lookupId}:
    post:
      summary: createMeterLookup
      description: >-
        Request information about a specified meter, including customer and
        utility details. This resource is used to verify that a meter number is
        valid and registered with the correct details. It also confirms whether
        the meter is recognised by a provider and that tokens can be issued
        against it.
      operationId: createMeterLookup
      parameters:
        - name: lookupId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeterLookupRequest'
        description: A meter information lookup request.
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeterLookupResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /tokenPurchases/{purchaseId}:
    post:
      summary: createTokenPurchaseRequest
      description: >-
        Requests that the provider issue a token against the meter for a given
        monetary value. In the case that the meter and/or utility supports the
        issue of free tokens under a basic service support tariff scheme, then
        any free tokens due will also be returned. If the requested amount is 0
        and a free token is due to the meter, then only this free token will be
        returned. A portion of the request amount may be used by the provider to
        offset outstanding debt or service charges owed by the customer, in
        which case the value of the token returned may be less than the request
        amount (see interface documentation for further details).
      operationId: createTokenPurchaseRequest
      parameters:
        - name: purchaseId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/PurchaseRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /tokenPurchases/{purchaseId}/confirmations/{confirmationId}:
    post:
      summary: confirmTokenPurchase
      description: >-
        Confirms that a purchase has been completed successfully (i.e. the
        tokens have been issued to the customer and payment has been received by
        the merchant). It is typical that token providers do not support
        confirmations (aka advices), but certain point-of-sale integrations may
        require support for these. A confirmation request must be sent
        repeatedly until an HTTP response code indicating a final state has been
        received (i.e. either `202` or `4xx`).
      operationId: confirmTokenPurchase
      parameters:
        - name: purchaseId
          in: path
          description: The randomly generated UUID of the original purchase request.
          required: true
          schema:
            type: string
        - name: confirmationId
          in: path
          description: The randomly generated UUID of this confirmation.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmationAdvice'
        description: A token purchase confirmation
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicAdviceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /tokenPurchases/{purchaseId}/retry:
    post:
      summary: retryPurchaseRequest
      description: >-
        If no response was received to a purchase request due to a timeout or
        temporary communications failure, PoS may retry the same purchase
        request by calling this resource. The original purchase request will be
        resubmitted to the provider. If the provider had received the original
        request, it will respond by returning any tokens that were already
        issued. If not, then either new tokens may be issued as per a normal
        purchase or the retry will be declined.
      operationId: retryPurchaseRequest
      parameters:
        - name: purchaseId
          in: path
          description: The randomly generated UUID of the original purchase request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
        description: The original token purchase request.
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /tokenPurchases/{purchaseId}/reversals/{reversalId}:
    post:
      summary: reverseTokenPurchase
      description: >-
        Notifies that a purchase was not completed successfully. This can occur
        if the original request timed out or if payment was unsuccessful. Many
        providers, however, do not support reversals and once a token has been
        issued the merchant becomes liable for the cost irrespective of payment
        failure or timeout. The token may still be retrieved by a reprint
        request, which merchants may use to help accommodate this scenario. A
        reversal request must be sent repeatedly until an HTTP response code
        indicating a final state has been received (i.e. either `202` or `4xx`).
      operationId: reverseTokenPurchase
      parameters:
        - name: purchaseId
          in: path
          description: The randomly generated UUID of the original purchase request.
          required: true
          schema:
            type: string
        - name: reversalId
          in: path
          description: The randomly generated UUID of this reversal.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReversalAdvice'
        description: A token purchase reversal.
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicAdviceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /tokenPurchases/{trialId}/trial:
    post:
      summary: trialTokenPurchaseRequest
      description: >-
        This operation is identical to the 'createTokenPurchaseRequest'
        operation except that no tokens are returned and this operation carries
        no financial impact. This operation allows the customer to make an
        informed choice about the transaction outcome before committing to
        purchase electricity. This operation serves to inform a customer exactly
        what the outcome of their purchase is: the service charges which will be
        levied, the debt recovery charges, the number of units which will be
        provided etc. If a customer is dissatisfied with the details in the
        response, the customer may abort the transaction without any
        consequences.
      operationId: trialTokenPurchaseRequest
      parameters:
        - name: trialId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/PurchaseRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /tokenReprints/{reprintId}:
    post:
      summary: requestTokenReprint
      description: >-
        Requests a reprint of a token that was previously issued for a specified
        meter. The request can be for either the last token issued for that
        meter, or for a specific transaction reference, depending on what the
        provider supports.
      operationId: requestTokenReprint
      parameters:
        - name: reprintId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenReprintRequest'
        description: A token reprint request.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
servers:
  - url: https://[placeholder].dev/prepaidutility/v3
components:
  requestBodies:
    PurchaseRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PurchaseRequest'
      description: A token purchase request.
      required: true
  securitySchemes:
    httpBasic:
      description: >-
        HTTP basic authentication. If you are doing a client side integration,
        Electrum will provide the username and password to the client. If you
        are doing a server side implementation, you will be expected to provide
        these credentials.
      type: http
      scheme: basic
    oauth2:
      description: >-
        OAuth2 password authentication, where the token URL, client ID, client
        secret, username, and password will be provided by Electrum if you
        implementing a client side integration. If you are doing a server side
        implementation, you will be expected to provide these credentials.
      type: oauth2
      flows:
        password:
          tokenUrl: >-
            https://auth.electrum.dev/auth/realms/Example-Realm/protocol/openid-connect/token
          scopes: {}
  schemas:
    AccountPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            srcAccountId:
              type: string
              description: Source AccountId from which this payment will be made.
            srcCustomerId:
              type: string
              description: Source CustomerId from which this payment will be made.
            destAccountId:
              type: string
              description: Destination AccountId to which this payment will be made.
            destCustomerId:
              type: string
              description: Destination CustomerId to which this payment will be made.
          description: Model for an account-to-account payment method
    Address:
      type: object
      properties:
        addressLine1:
          type: string
          description: First line of street address.
          pattern: ^.{1,100}
        addressLine2:
          type: string
          description: Second line of street address (if required).
          pattern: ^.{1,100}
        city:
          type: string
          description: >-
            The city where the owner is located. Note: if this field ever needs
            to be translated to another API with shorter fields, the field will
            be truncated from the right.
          pattern: ^.{1,30}
        region:
          type: string
          description: The state or region where the owner is located.
          pattern: '[A-Z]{2}'
        country:
          type: string
          description: >-
            The owner's resident country expressed as an ISO 3166-1 Alpha-2
            code.
          pattern: '[A-Z]{2}'
        postalCode:
          type: string
          description: The owner's postal code.
          pattern: '[A-Za-z0-9 -]{1,20}'
      description: Details of a customer's address
    Amounts:
      type: object
      properties:
        requestAmount:
          $ref: '#/components/schemas/LedgerAmount'
        approvedAmount:
          $ref: '#/components/schemas/LedgerAmount'
        feeAmount:
          $ref: '#/components/schemas/LedgerAmount'
        balanceAmount:
          $ref: '#/components/schemas/LedgerAmount'
        additionalAmounts:
          type: object
          description: >-
            Any additional amounts that are involved in a transaction which
            don't appropriately fit into the other amount fields.
          additionalProperties:
            $ref: '#/components/schemas/LedgerAmount'
      description: Amounts which make up the transaction. Absent amounts have zero value.
    An32TokenPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - token
          properties:
            token:
              type: string
              description: 32 character alphanumeric code which identifies a token
              pattern: '[a-zA-Z0-9]{32}'
          description: Model for token-based payments
    Barcode:
      type: object
      required:
        - data
        - encoding
      properties:
        data:
          type: string
          description: Data to be encoded in the barcode
        encoding:
          type: string
          description: Specifies the encoding used in the barcode
      description: Used to indicate barcode information for a slip line.
    BasicAdvice:
      type: object
      required:
        - id
        - requestId
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
      description: The data required in all advice messages
    BasicAdviceResponse:
      type: object
      required:
        - id
        - requestId
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
      description: Basic advice response information.
    CardPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - pan
          properties:
            posInfo:
              $ref: '#/components/schemas/PosInfo'
            pin:
              $ref: '#/components/schemas/Pin'
            pan:
              type: string
              description: Primary account number that uniquely identifies this card.
              pattern: '[0-9]{1,19}'
            expiryDate:
              type: string
              description: The card expiry date, in YYMM format.
              pattern: '[0-9]{4}'
            threeDSecureData:
              $ref: '#/components/schemas/ThreeDSecureData'
            encryptedPin:
              $ref: '#/components/schemas/EncryptedPin'
          description: Model for card-based payments
    ConfirmationAdvice:
      type: object
      required:
        - id
        - requestId
        - tenders
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        tenders:
          type: array
          description: An array of tenders used to pay for the transaction
          items:
            $ref: '#/components/schemas/Tender'
      description: >-
        Represents an advice message confirming successful completion of a
        transaction.
    Customer:
      type: object
      properties:
        firstName:
          type: string
          description: The customer's first name(s)
        lastName:
          type: string
          description: The customer's last name
        address:
          type: string
          description: The customer's address
        dateOfBirth:
          type: string
          format: date-time
          description: The customer's date of birth
        status:
          type: string
          description: >-
            The status of this customer on the Giftcard system. For example:
            active, inactive
        msisdn:
          type: string
          description: >-
            This must conform to the ITU E.164 numbering plan
            (https://www.itu.int/rec/T-REC-E.164/en) e.g. 27821234567 for a
            South African number.
          pattern: ^\+?[1-9]\d{0,14}
        emailAddress:
          type: string
          description: >-
            The customer's email address. This address must conform to RFC 5322
            3.4.1 addr-spec (https://tools.ietf.org/html/rfc5322#section-3.4.1).
        addressDetails:
          $ref: '#/components/schemas/Address'
        profileId:
          type: string
          description: The customer's profile ID. Used to uniquely identify a customer.
      description: A customer who ultimately requests a transaction be performed.
    DebtRecoveryCharge:
      type: object
      required:
        - amount
        - balance
        - description
      properties:
        amount:
          $ref: '#/components/schemas/TaxableAmount'
        description:
          type: string
          description: >-
            Description of this debt recovery charge (e.g. municipal rates
            arrears).
        balance:
          $ref: '#/components/schemas/LedgerAmount'
        receiptNum:
          type: string
          description: Receipt number for this charge.
      description: >-
        Represents a charge deducted from the purchase to recover outstanding
        debt.
    EncryptedPin:
      type: object
      required:
        - pinBlock
      properties:
        pinBlock:
          type: string
          description: Hexadecimal string representing the encrypted PIN to be used.
          pattern: '[a-fA-F0-9]{16}|[a-fA-F0-9]{32}'
        encryptionParameters:
          $ref: '#/components/schemas/EncryptionParameters'
      description: >-
        A PIN required to authorise a transaction. EncryptionParameters should
        be provided where the service will be performing operations on the
        encrypted PIN, such as PIN translation. Only the PIN block need be
        provided where the service is expected to forward it to a third party,
        where the calling client and said third party have agreed upon
        encryption parameters beforehand.
    EncryptionParameters:
      type: object
      required:
        - accountNumber
      properties:
        pinBlockFormat:
          type: string
          description: >-
            PIN block format that was used when encrypting the PIN. Defaults to
            ISO_9564_FORMAT_0.
          default: ISO_9564_FORMAT_0
          enum:
            - ISO_9564_FORMAT_0
            - ISO_9564_FORMAT_1
            - ISO_9564_FORMAT_3
            - ISO_9564_FORMAT_4
        accountNumber:
          type: string
          description: >-
            12 digit account number used when encrypting the PIN. When account
            number is a card number (PAN), this is the rightmost 12 digits
            excluding the check digit.
          pattern: '[0-9]{12}'
        keyIndex:
          type: integer
          format: int32
          description: >-
            Index of the key under which the PIN block is encrypted. Where keys
            are exchanged in TR-31 KeyBlock format, this should be set to the
            key version number field of the key used for encryption. If this
            field is not populated, the most recently exchanged key will be
            used. Note that omitting this field may require a higher level of
            synchronization during automated key exchange in some environments.
      description: >-
        Parameters pertaining to the generation of the PIN block. Required if
        the service is to perform any operations on the encrypted PIN, such as
        translation.
    ErrorDetail:
      type: object
      required:
        - errorMessage
        - errorType
        - id
        - requestType
      properties:
        errorType:
          type: string
          description: The type of error that occurred.
          enum:
            - DUPLICATE_RECORD
            - FORMAT_ERROR
            - FUNCTION_NOT_SUPPORTED
            - GENERAL_ERROR
            - INVALID_AMOUNT
            - ROUTING_ERROR
            - TRANSACTION_NOT_SUPPORTED
            - UNABLE_TO_LOCATE_RECORD
            - UPSTREAM_UNAVAILABLE
            - UNKNOWN_METER_ID
            - TRANSACTION_DECLINED
            - INVALID_MERCHANT
            - INVALID_AN32_TOKEN
            - DO_NOT_HONOR
            - INVALID_MSISDN
            - INVALID_LOYALTY_CARD
            - UTILITY_INVALID
            - SYSTEM_MALFUNCTION
            - METER_KEY_INVALID
            - AMOUNT_TOO_LOW
            - AMOUNT_TOO_HIGH
            - NO_FREE_UNITS_DUE
            - INSUFFICIENT_FUNDS
            - LIMIT_EXCEEDED
            - METER_ID_BLOCKED
            - OUTCOME_UNKNOWN
        errorMessage:
          type: string
          description: A short description of the error.
        requestType:
          type: string
          description: The type of request being processed when the error occurred.
          enum:
            - METER_LOOKUP_REQUEST
            - TOKEN_PURCHASE_REQUEST
            - TOKEN_PURCHASE_RETRY_REQUEST
            - TOKEN_REPRINT_REQUEST
            - FAULT_REPORT_REQUEST
            - KEY_CHANGE_TOKEN_REQUEST
            - CONFIRMATION_ADVICE
            - REVERSAL_ADVICE
            - NOTIFY_TOKEN_PURCHASE
            - TOKEN_PURCHASE_TRIAL_REQUEST
        id:
          type: string
          description: The UUID of the message for which error occurred.
        originalId:
          type: string
          description: >-
            The UUID of the original request message in the case of an error
            occurring for an advice message.
        detailMessage:
          type: object
          description: An optional free-form description of the failure condition.
      description: Represents the outcome of a completed transaction.
    FaultReportRequest:
      type: object
      required:
        - client
        - contactNumber
        - faultType
        - id
        - meter
        - originator
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        meter:
          $ref: '#/components/schemas/Meter'
        customer:
          $ref: '#/components/schemas/Customer'
        contactNumber:
          type: string
          description: Contact telephone number of the person reporting the fault.
        faultType:
          type: string
          description: Type of fault that is being reported.
          enum:
            - SERIOUS_BOX_DAMAGE
            - FIRE_WATER_DAMAGE
            - METER_DEAD
            - KEEPS_TRIPPING
            - NO_TRIP
            - DISPLAY_LIGHTS_BUTTONS
            - NETWORK_FAULT_REPORT
            - INCORRECT_SGC
            - INCORRECT_TI
            - CONVERTED_FRM_CONVENTIONAL
            - METER_CHANGED_OUT
            - NEW_INSTALLATION
        faultDescription:
          type: string
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
      description: Data required to report a fault related to a specific meter.
    FaultReportResponse:
      type: object
      required:
        - client
        - description
        - id
        - originator
        - reference
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        reference:
          type: string
          description: Reference number for the fault report.
        description:
          type: string
          description: Description of the fault.
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
      description: Represents a response to a fault report.
    HashedPinParameters:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The name of the hashing algorithm.
      description: >-
        A collection of parameters required to reliably reproduce the hashed
        value (excluding the actual PIN value).
    Institution:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: >-
            The institution's ID. API implementations should take care to set
            this field as appropriate for the implementation.
        name:
          type: string
          description: The institutions's name
      description: Originating, acquiring, processing, or receiving institution details
    KeyChangeConfirmation:
      type: object
      required:
        - id
        - requestId
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
      description: Represents an advice message confirming successful change of a key.
    KeyChangeData:
      type: object
      properties:
        newSupplyGroupCode:
          type: string
          description: >-
            New supply group code. Only relevant if this has been changed by the
            utility and a key change token has been issued.
          pattern: '[0-9]{6}'
        newKeyRevisionNumber:
          type: string
          description: >-
            New key revision number. Only relevant if this has been changed by
            the utility and a key change token has been issued.
          pattern: '[0-9]{1}'
        newTariffIndex:
          type: string
          description: >-
            New tariff index. Only relevant if this has been changed by the
            utility and a key change token has been issued.
          pattern: '[0-9]{2}'
      description: Represents updated meter encryption key data.
    KeyChangeTokenRequest:
      type: object
      required:
        - client
        - id
        - meter
        - originator
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        meter:
          $ref: '#/components/schemas/Meter'
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
      description: Represents a request for a key change token.
    KeyChangeTokenResponse:
      type: object
      required:
        - client
        - id
        - meter
        - originator
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        meter:
          $ref: '#/components/schemas/Meter'
        tokens:
          type: array
          description: List of tokens issued for the key change.
          items:
            $ref: '#/components/schemas/Token'
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
      description: Represents a response to a key change token request.
    LedgerAmount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: integer
          format: int64
          description: Amount in minor denomination, e.g. R799.95 is encoded as 79995
        currency:
          type: string
          description: >-
            Three digit currency number from ISO 4217, e.g. South African Rand
            is encoded as 710
          pattern: '[0-9]{3}'
        ledgerIndicator:
          type: string
          description: >-
            Indicates whether this amount is a debit or a credit. Only required
            when the amount can be either a debit or a credit
          enum:
            - DEBIT
            - CREDIT
      description: >-
        An amount object only containing value and currency, and optionally an
        indicator of DEBIT/CREDIT
    LoyaltyCardPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - cardNumber
          properties:
            cardNumber:
              type: string
              description: >-
                Primary account number of the loyalty programme card used to
                make a payment
              pattern: '[0-9]{16}'
          description: Model for payments made using loyalty programme cards
    Merchant:
      type: object
      required:
        - merchantId
        - merchantName
        - merchantType
      properties:
        merchantType:
          type: string
          description: The assigned four digit merchant category code
          pattern: '[0-9]{4}'
        merchantId:
          type: string
          description: The assigned merchant identifier. Also known as card acceptor id
        merchantName:
          $ref: '#/components/schemas/MerchantName'
      description: Merchant related data. Must be included if available
    MerchantName:
      type: object
      required:
        - city
        - country
        - name
        - region
      properties:
        name:
          type: string
          description: The merchant or trading as name associated with the merchant
        city:
          type: string
          description: The city where the merchant is located
        region:
          type: string
          description: The state or region where the merchant is located
        country:
          type: string
          description: The country where the merchant is located
      description: A container object representing the Merchant Name and Location
    Meter:
      type: object
      required:
        - meterId
      properties:
        meterId:
          type: string
          description: Unique identifier for the meter (e.g. serial number).
          pattern: '[a-zA-Z0-9]{0,20}'
        track2Data:
          type: string
          description: >-
            Track 2 data stored on the magnetic stripe of a card that is
            supplied with certain meters. This data contains all meter details.
            It can be used as an alternative means of input at PoS and may be
            required by some providers.
          pattern: '[a-zA-Z0-9=]{34}'
        serviceType:
          type: string
          description: >-
            Type of service dispensed by this meter (e.g. electricity, water or
            gas).
          pattern: '[a-zA-Z0-9]{0,12}'
        supplyGroupCode:
          type: string
          description: Code used to identify a group of suppliers.
          pattern: '[0-9]{6}'
        keyRevisionNum:
          type: string
          description: Key revision number of the meter.
          pattern: '[0-9]{1}'
        tariffIndex:
          type: string
          description: Code representing the tariff associated with this meter.
          pattern: '[0-9]{2}'
        tokenTechCode:
          type: string
          description: >-
            The means by which tokens are supplied for this meter (typically
            either numeric token or magnetic track).
          pattern: '[0-9]{2}'
        algorithmCode:
          type: string
          description: Code used to identify token encryption algorithm used by the meter.
          pattern: '[0-9]{2}'
        keyChangeData:
          $ref: '#/components/schemas/KeyChangeData'
      description: Data associated with a prepaid utility meter
    MeterLookupRequest:
      type: object
      required:
        - client
        - id
        - meter
        - originator
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        meter:
          $ref: '#/components/schemas/Meter'
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
      description: Represents a request for information about a meter.
    MeterLookupResponse:
      type: object
      required:
        - client
        - customer
        - id
        - meter
        - originator
        - thirdPartyIdentifiers
        - time
        - utility
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        meter:
          $ref: '#/components/schemas/Meter'
        customer:
          $ref: '#/components/schemas/Customer'
        utility:
          $ref: '#/components/schemas/Utility'
        minAmount:
          $ref: '#/components/schemas/LedgerAmount'
        maxAmount:
          $ref: '#/components/schemas/LedgerAmount'
        arrearsAmount:
          $ref: '#/components/schemas/LedgerAmount'
        bsstDue:
          type: boolean
          description: >-
            Boolean flag indicating whether a free basic service support token
            is owing on this meter. Not all meters support this and typically
            only one free token is issued per calendar month. If the value of
            this field is true, then a purchase request with an amount of 0 can
            be sent and the response will contain the free token.
          default: false
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
      description: Represents a response to a meter lookup request.
    Originator:
      type: object
      required:
        - institution
        - merchant
        - terminalId
      properties:
        institution:
          $ref: '#/components/schemas/Institution'
        terminalId:
          type: string
          description: >-
            The ID that uniquely identifies each device or system in an
            originator's institution capable of sending requests. Required for
            transactions initiated from physical card entry or point-of-sale
            devices
        merchant:
          $ref: '#/components/schemas/Merchant'
        operatorId:
          type: string
          description: >-
            The ID that uniquely identifies the person operating the terminal
            specified by the terminalId field.
        channelId:
          type: string
          description: >-
            The ID that uniquely identifies the originator's channel that this
            transaction was received through.
      description: >-
        The Originator object encapsulates data relating to the originator of
        the transaction
    PaymentMethod:
      type: object
      required:
        - type
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          description: The general method of payment used
          enum:
            - AN_32_TOKEN
            - LOYALTY_CARD
            - CARD
            - ACCOUNT
            - REWARD
            - WALLET
            - QR
        name:
          type: string
          description: The specific method of payment used
        amount:
          $ref: '#/components/schemas/LedgerAmount'
        issuer:
          $ref: '#/components/schemas/Institution'
        pin:
          $ref: '#/components/schemas/Pin'
        proxy:
          type: string
          description: >-
            An alternative identifier for the customer's source of funds. Acts
            as a stand in for the customer identifier. E.g. a customer's MSISDN
            or email address.
          minLength: 0
          maxLength: 40
        proxyType:
          type: string
          description: An enumerated value describing the type of value used as the proxy.
          enum:
            - MSISDN
            - EMAIL
            - UNKNOWN
      description: Base model for all payment types
    Pin:
      type: object
      required:
        - type
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          description: Whether the PIN is communicated in the clear or encrypted.
          enum:
            - CLEAR_PIN
            - ENCRYPTED_PIN
            - HASHED_PIN
      description: Base model for capturing either a clear PIN or encrypted PIN
    PinClear:
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          required:
            - pin
          properties:
            pin:
              type: string
              description: A clear PIN
              pattern: .{0,20}
          description: A clear PIN required to authorise a transaction.
    PinEncrypted:
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          required:
            - pinBlock
          properties:
            pinBlock:
              type: string
              description: Hexadecimal string representing the encrypted PIN to be used.
              pattern: '[a-fA-F0-9]{16}|[a-fA-F0-9]{32}'
            encryptionParameters:
              $ref: '#/components/schemas/EncryptionParameters'
          description: >-
            A PIN required to authorise a transaction. EncryptionParameters
            should be provided where the service will be performing operations
            on the encrypted PIN, such as PIN translation. Only the PIN block
            need be provided where the service is expected to forward it to a
            third party, where the calling client and said third party have
            agreed upon encryption parameters beforehand.
    PinHashed:
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          required:
            - hash
          properties:
            hash:
              type: string
              description: A hashed PIN expressed as an ASCII string of hexadecimal values.
              pattern: '[0-9,A-F]{1,512}'
            hashedPinParameters:
              $ref: '#/components/schemas/HashedPinParameters'
          description: >-
            A PIN, required to authorise a transaction, which has been hashed
            according to some hashing algorithm.
    PosEntryMode:
      type: object
      required:
        - panEntryMode
        - pinEntryCapability
      properties:
        panEntryMode:
          type: string
          description: Describes the method by which the PAN was captured.
          enum:
            - UNKNOWN
            - MANUAL
            - MAGSTRIPE_NO_CVV
            - BARCODE
            - OCR
            - ICC_CVV
            - CONTACTLESS_ICC
            - MAGSTRIPE_CVV
            - CONTACTLESS_MAGSTRIPE
            - ICC_NO_CVV
            - ORIG_MODE
            - FALLBACK
        pinEntryCapability:
          type: string
          description: Describes whether the PIN can be entered.
          enum:
            - UNKNOWN
            - CAN_ACCEPT
            - CANNOT_ACCEPT
      description: Describes how the PAN and PIN were captured by the POS.
    PosInfo:
      type: object
      properties:
        entryMode:
          $ref: '#/components/schemas/PosEntryMode'
        posConditionCode:
          type: string
          description: Describes the circumstances of the transaciton at the POS.
          enum:
            - NORMAL_PRESENTMENT
            - CUSTOMER_NOT_PRESENT
            - CUSTOMER_PRESENT_AND_CARD_NOT_PRESENT
            - CUSTOMER_IDENTITY_VERIFIED
            - PUBLIC_UTILITY_TERMINAL
            - CUSTOMER_TERMINAL
            - MANUAL_REVERSAL
            - UNATTENDED_TERMINAL_AND_CARD_CAN_BE_RETAINED
            - UNATTENDED_TERMINAL_AND_CARD_CANNOT_BE_RETAINED
      description: POS related data.
    PurchaseRequest:
      type: object
      required:
        - client
        - id
        - meter
        - originator
        - purchaseAmount
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        meter:
          $ref: '#/components/schemas/Meter'
        purchaseAmount:
          $ref: '#/components/schemas/LedgerAmount'
        utilityType:
          type: string
          description: >-
            Type of utility purchase being requested (e.g. electricity, water,
            gas).
        msisdn:
          type: string
          description: >-
            Mobile phone number of the customer to which the outcome of a
            transaction can be communicated. This should conform to the ITU
            E.164 numbering plan (https://www.itu.int/rec/T-REC-E.164/en), but a
            10-digit number beginning with zero is also acceptable.
          pattern: (^\+?[1-9]\d{1,14})|(^[0][0-9]{9})
        tenders:
          type: array
          description: >-
            An array of tenders used to pay for the transaction. This is used if
            payment is tendered at the point of sale. A Tender differs from a
            PaymentMethod in that the former represents a payment that has
            already been collected at the point of sale, whereas the latter
            represents a payment that still needs to be collected from a third
            party.
          items:
            $ref: '#/components/schemas/Tender'
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        paymentMethods:
          type: array
          description: >-
            An array of payment methods to be used as payment for the
            transaction. This is used if payment is not tendered at the point of
            sale, but is effected through one or more calls to third party
            payment providers as part of the request. A PaymentMethod differs
            from a Tender in that the former represents payment that still needs
            to be collected from a third party, whereas the latter represents
            payment that has already been collected at the point of sale.
          items:
            $ref: '#/components/schemas/PaymentMethod'
      description: Represents a token purchase request.
    PurchaseResponse:
      type: object
      required:
        - client
        - customer
        - id
        - meter
        - originator
        - thirdPartyIdentifiers
        - time
        - utility
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        purchaseTotal:
          $ref: '#/components/schemas/LedgerAmount'
        taxTotal:
          $ref: '#/components/schemas/LedgerAmount'
        amounts:
          $ref: '#/components/schemas/Amounts'
        meter:
          $ref: '#/components/schemas/Meter'
        customer:
          $ref: '#/components/schemas/Customer'
        utility:
          $ref: '#/components/schemas/Utility'
        utilityType:
          type: string
          description: >-
            Type of utility purchase being requested (e.g. electricity, water,
            gas).
        tokens:
          type: array
          description: List of tokens issued for the purchase.
          items:
            $ref: '#/components/schemas/Token'
        debtRecoveryCharges:
          type: array
          description: >-
            List of charges that have been levied in order to reclaim
            outstanding debts associated with the meter.
          items:
            $ref: '#/components/schemas/DebtRecoveryCharge'
        serviceCharges:
          type: array
          description: List of service charges levied against this meter.
          items:
            $ref: '#/components/schemas/ServiceCharge'
        vatInvoiceNumber:
          type: string
          description: The VAT invoice number corresponding to this specific transaction.
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
      description: Represents the response to a token purchase request.
    QrPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - tranId
          properties:
            tranId:
              type: string
              description: >-
                The unique transaction identifier related to this transaction.
                In QRs styled on the EMVCo specification, the tranId is embedded
                in sub-Tag 00 of the Electrum MAIT.
            partnerPaymentToken:
              type: string
              description: A payment token received from the Partner.
          description: >-
            Model for QR-based payments. This payment method should be used when
            a QR code is presented for payment.
    ReversalAdvice:
      type: object
      required:
        - id
        - requestId
        - reversalReason
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        reversalReason:
          type: string
          description: The reason for the reversal
          enum:
            - TIMEOUT
            - CANCELLED
            - RESPONSE_NOT_FINAL
            - REFUND
            - VOID
      description: Represents a request to reverse a previous transaction transaction.
    RewardPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - rewardCode
          properties:
            rewardCode:
              type: string
              description: A code used to recognise the reward programme
              minLength: 0
              maxLength: 40
          description: >-
            Model for reward-based payments. This payment method should be used
            when the payment is offset using a reward programme
    ServiceCharge:
      type: object
      required:
        - amount
        - description
      properties:
        amount:
          $ref: '#/components/schemas/TaxableAmount'
        description:
          type: string
          description: Description of this service charge (e.g. connection fee).
      description: Represents a service charge deducted from the purchase amount.
    SlipData:
      type: object
      properties:
        messageLines:
          type: array
          description: >-
            An array of text lines and optional formatting to be printed on the
            customer slip.
          items:
            $ref: '#/components/schemas/SlipLine'
        slipWidth:
          type: integer
          format: int32
          description: The width of the slip in normal (unformatted) characters.
        issuerReference:
          type: string
          description: >-
            An identifier that is printed on the customer slip and uniquely
            identifies the payment on the service provider's system. This value
            is used by the customer to request a refund when the service
            supports this function, and it is thus important that this number is
            unique.
          pattern: '[A-Z0-9]{1,40}'
      description: Data that may be printed on the customer slip for information purposes
    SlipLine:
      type: object
      required:
        - text
      properties:
        barcode:
          $ref: '#/components/schemas/Barcode'
        text:
          type: string
          description: Text contained on the line
        fontWidthScaleFactor:
          type: number
          format: double
          description: >-
            Scale factor for font width. Assume 1.0 (i.e. normal size) if not
            present.
        fontHeightScaleFactor:
          type: number
          format: double
          description: >-
            Scale factor for font height. Assume 1.0 (i.e. normal size) if not
            present.
        line:
          type: boolean
          description: Denotes a solid line on the slip. Assume false if not present.
          default: false
        cut:
          type: boolean
          description: >-
            Indicates the slip should be cut at this line. Assume false if not
            present.
          default: false
      description: A line of text to be printed on the till slip
    TariffBlock:
      type: object
      required:
        - rate
        - units
      properties:
        units:
          type: number
          description: Number of units in this tariff block.
        rate:
          type: number
          description: Tariff rate for this block in minor denomination.
      description: Represents a block of units charged at a specific tariff.
    TaxableAmount:
      type: object
      required:
        - amount
        - currency
      properties:
        tax:
          type: integer
          format: int64
          description: >-
            Tax amount. Only present and non-zero if the amount field is
            exclusive of tax.
        taxType:
          type: string
          description: Description of the type of tax (e.g. VAT).
        taxRate:
          type: number
          description: Rate at which tax is levied, expressed as a percentage.
        amount:
          type: integer
          format: int64
          description: Amount in minor denomination, e.g. R799.95 is encoded as 79995
        currency:
          type: string
          description: >-
            Three digit currency number from ISO 4217, e.g. South African Rand
            is encoded as 710
          pattern: '[0-9]{3}'
        ledgerIndicator:
          type: string
          description: >-
            Indicates whether this amount is a debit or a credit. Only required
            when the amount can be either a debit or a credit
          enum:
            - DEBIT
            - CREDIT
      description: Represents an amount on which tax has been levied.
    Tender:
      type: object
      required:
        - amount
        - tenderType
      properties:
        accountType:
          type: string
          description: The type of account
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - STORED_VALUE
        amount:
          $ref: '#/components/schemas/LedgerAmount'
        cardNumber:
          type: string
          description: >-
            A PCI compliant masked card number, with at least the first 6 digits
            in the clear. Only applicable to card based transactions
          pattern: '[0-9]{6}[0-9*]{0,13}'
        reference:
          type: string
          description: A free text reference
        tenderType:
          type: string
          description: The type of tender used
          enum:
            - CASH
            - CHEQUE
            - CREDIT_CARD
            - DEBIT_CARD
            - WALLET
            - ROUNDING
            - GIFT_CARD
            - LOYALTY_CARD
            - OTHER
            - REWARD
      description: Details of the Tender used by a customer towards a payment
    ThirdPartyIdentifier:
      type: object
      required:
        - institutionId
        - transactionIdentifier
      properties:
        institutionId:
          type: string
          description: The entity's institution ID.
        transactionIdentifier:
          type: string
          description: >-
            The identifier assigned to this transaction by the institution
            represented in institutionId. This value should be unique within the
            institution's system.
      description: >-
        An identifier assigned by an entity which process the message.
        Identifiers are keyed by institution ID thereby enabling any institution
        to recall a transaction within the entity's own system using the
        entity's own identifier. Entities must not alter the identifier set by
        another entity. Once an identifier has been set by an entity, all other
        entities must send that identifier in subsequent messages.
    ThreeDSecureData:
      type: object
      required:
        - version
      discriminator:
        propertyName: version
      properties:
        authenticationValue:
          type: string
          description: >-
            A 20-byte value that has been Base64 encoded. This value is provided
            by the Access Control Server as a proof of authentication.
        cardHolderAuthVerificationResult:
          type: string
          description: Authentication outcome set by the Access Control Server or Issuer.
          enum:
            - CAVV_VALIDATION_PASSED
            - CAVV_VALIDATION_FAILED_ISSUER_SYSTEM_ERROR
            - CAVV_VALIDATION_FAILED_ISSUER_ATTEMPT_INCOMPLETE
            - CAVV_NOT_VALIDATED
            - CAVV_NOT_VALIDATED_INVALID_DATA
            - CAVV_VALIDATION_FAILED
        version:
          type: string
          description: >-
            The version of the 3-D Secure protocol that was used for cardholder
            authentication. Note that the version determines the format of the
            transaction identifier
          enum:
            - V1
            - V2
        eci:
          type: string
          description: >-
            Electronic Commerce Indicator. This is Payment System-specific value
            provided by the Access Control Server to indicate the results of the
            attempt to authenticate the Cardholder.
          enum:
            - AUTHENTICATION_NOT_ATTEMPTED_OR_UNSUCCESSFUL_00
            - AUTHENTICATION_NOT_ENABLED_01
            - AUTHENTICATION_SUCCESSFUL_02
            - AUTHENTICATION_SUCCESSFUL_05
            - AUTHENTICATION_NOT_ENABLED_06
            - AUTHENTICATION_NOT_ATTEMPTED_OR_UNSUCCESSFUL_07
        transactionStatus:
          type: string
          description: >-
            Indicates whether a transaction qualifies as an authenticated
            transaction or account verification. The values and their meanings
            are as follows: 

            Y = Authentication Verification Successful.
             N = Not Authenticated /Account Not Verified; Transaction denied.
             U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem.
             A = Attempts Processing Performed; Not Authenticated/ Verified, but a proof of attempted authentication/verification is provided.
             C = Challenge Required; Additional authentication is required using the CReq/CRes 
             D = Challenge Required; Decoupled Authentication confirmed. 
             R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.
             I = Informational Only; 3DS Requestor challenge preference acknowledged.
             S = Challenge using SPC 
             
          enum:
            - 'Y'
            - 'N'
            - U
            - A
            - C
            - D
            - R
            - I
            - S
      description: >-
        Data used to facilitate and communicate the result of 3-D Secure
        cardholder authentication.
    ThreeDSecureDataV1:
      allOf:
        - $ref: '#/components/schemas/ThreeDSecureData'
        - type: object
          properties:
            transactionId:
              type: string
              description: >-
                A 20-byte base 64 encoded string assigned by the 3DS Server to
                identify a single transaction. This ID can be used to prevent
                transaction replay.
          description: >-
            3-D Secure data in which the transaction identifier takes the format
            of a byte string.
    ThreeDSecureDataV2:
      allOf:
        - $ref: '#/components/schemas/ThreeDSecureData'
        - type: object
          properties:
            transactionId:
              type: string
              format: uuid
              description: >-
                A UUID assigned by the 3DS Server to identify a single
                transaction. This ID can be used to prevent transaction replay.
                This is based on version 2 the EMVCo 3-D Secure specification.
          description: >-
            3-D Secure data in which the transaction identifier takes the format
            of a UUID.
    Token:
      type: object
      required:
        - amount
        - token
        - tokenType
        - units
      properties:
        tokenType:
          type: string
          description: >-
            Type of token, namely standard (STD), basic service support tariff
            (BSST), refund (REFUND), key change (KC).
          enum:
            - STD
            - BSST
            - REFUND
            - KC
            - PWRLMT
        units:
          type: number
          description: Number of units redeemable by this token.
        amount:
          $ref: '#/components/schemas/TaxableAmount'
        receiptNum:
          type: string
          description: Receipt number issued for the transaction.
        token:
          type: string
          description: >-
            Numeric sequence to be entered into the meter to redeem the token's
            value.
        tariffCalc:
          type: array
          description: >-
            List of tariff blocks determining how the overall tariff is
            calculated.
          items:
            $ref: '#/components/schemas/TariffBlock'
      description: Represents a prepaid utility token.
    TokenReprintRequest:
      type: object
      required:
        - client
        - id
        - meter
        - originator
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        meter:
          $ref: '#/components/schemas/Meter'
        originalRef:
          type: string
          description: >-
            Reference or receipt number for the original token in the case that
            a specific token is requested. If this field is not present, then
            the last-issued token will be requested from the provider.
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
      description: Represents a request for a token reprint.
    TransactionLabel:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: >-
            Label name that indicates the type and intended use of the
            transaction label. The meaning of label names must be agreed upon by
            the parties involved in transaction processing.
          pattern: ^[a-zA-Z0-9_]{1,100}$
        value:
          type: string
          description: The value assigned to the transaction label.
          pattern: ^[a-zA-Z.-9 _-]{1,100}$
      description: >-
        A label assigned to a transaction by the entity processing the
        transaction. Labels are used for grouping or discovering transactions
        after transaction processing. Note that no transaction processing
        decision is made based on transaction labels.
    Utility:
      type: object
      properties:
        name:
          type: string
          description: Name of the utility.
        address:
          type: string
          description: Physical address of the utility.
        vatRegNum:
          type: string
          description: VAT registration number of the utility.
        clientId:
          type: string
          description: >-
            Identifier assigned by the utility to the client connecting to the
            utility's token issuing service.
        message:
          type: string
          description: Message send by the utility to be displayed on the customer receipt.
      description: Represents a utility with whom a meter is registered.
    WalletPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - walletId
          properties:
            walletId:
              type: string
              description: The unique identifier of the wallet account making the payment.
              readOnly: true
            walletPocket:
              $ref: '#/components/schemas/WalletPocket'
          description: Model for mobile wallet payments
    WalletPocket:
      type: object
      required:
        - pocketName
      properties:
        pocketName:
          type: string
          description: The name given to this wallet pocket.
        pocketId:
          type: string
          description: >-
            A programmatic ID that can be used to identify this pocket when the
            name is not enough
