Swagger

The swagger (Open API) definition of the interface specification can be found here, as well as below.

Many tools are available for processing swagger files, and using a code generation tool to create a boilerplate client or server can be an excellent starting point for development. We highly recommend looking at swagger-codegen for a generator in your preferred language when starting out.

Swagger definition

---
swagger: "2.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.5.2"
  title: "Prepaid Utility Service Interface"
  contact:
    name: "Electrum API"
    url: "http://io.electrum"
    email: "api@electrum.co.za"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "sandbox.electrum.io"
basePath: "/prepaidutility/v3"
schemes:
- "https"
paths:
  /prepaidutility/v3/faultReports/{requestId}:
    post:
      summary: "Report a fault on a meter"
      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"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "requestId"
        in: "path"
        description: "The randomly generated UUID of this request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A fault report"
        required: true
        schema:
          $ref: "#/definitions/FaultReportRequest"
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/FaultReportResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
      - httpBasic: []
  /prepaidutility/v3/keyChangeTokenRequests/{requestId}:
    post:
      summary: "Request a key change token"
      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"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "requestId"
        in: "path"
        description: "The randomly generated UUID of this request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A key change token request"
        required: true
        schema:
          $ref: "#/definitions/KeyChangeTokenRequest"
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/KeyChangeTokenResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
      - httpBasic: []
  /prepaidutility/v3/meterLookups/{lookupId}:
    post:
      summary: "Request information about a specified meter"
      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"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "lookupId"
        in: "path"
        description: "The randomly generated UUID of this request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A meter information lookup request."
        required: true
        schema:
          $ref: "#/definitions/MeterLookupRequest"
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/MeterLookupResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
      - httpBasic: []
  /prepaidutility/v3/tokenPurchases/{purchaseId}:
    post:
      summary: "Requests a token purchase for a specified meter."
      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"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "purchaseId"
        in: "path"
        description: "The randomly generated UUID of this request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A token purchase request."
        required: true
        schema:
          $ref: "#/definitions/PurchaseRequest"
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/PurchaseResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
  /prepaidutility/v3/tokenPurchases/{purchaseId}/confirmations/{confirmationId}:
    post:
      summary: "Confirms that a purchase has been completed successfully."
      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 400)."
      operationId: "confirmTokenPurchase"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "purchaseId"
        in: "path"
        description: "The randomly generated UUID of the original purchase request."
        required: true
        type: "string"
      - name: "confirmationId"
        in: "path"
        description: "The randomly generated UUID of this confirmation."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A token purchase confirmation"
        required: true
        schema:
          $ref: "#/definitions/ConfirmationAdvice"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/BasicAdviceResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not found"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
  /prepaidutility/v3/tokenPurchases/{purchaseId}/retry:
    post:
      summary: "Retry a previously submitted purchase request."
      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"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "purchaseId"
        in: "path"
        description: "The randomly generated UUID of the original purchase request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "The original token purchase request."
        required: true
        schema:
          $ref: "#/definitions/PurchaseRequest"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/PurchaseResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not found"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
  /prepaidutility/v3/tokenPurchases/{purchaseId}/reversals/{reversalId}:
    post:
      summary: "Notifies the provider that a purchase was not completed successfully."
      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 400)."
      operationId: "reverseTokenPurchase"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "purchaseId"
        in: "path"
        description: "The randomly generated UUID of the original purchase request."
        required: true
        type: "string"
      - name: "reversalId"
        in: "path"
        description: "The randomly generated UUID of this reversal."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A token purchase reversal."
        required: true
        schema:
          $ref: "#/definitions/ReversalAdvice"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/BasicAdviceResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not found"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
  /prepaidutility/v3/tokenReprints/{reprintId}:
    post:
      summary: "Requests a reprint of a token"
      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"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "reprintId"
        in: "path"
        description: "The randomly generated UUID of this request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A token reprint request."
        required: true
        schema:
          $ref: "#/definitions/TokenReprintRequest"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/PurchaseResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
securityDefinitions:
  httpBasic:
    description: "All requests require HTTP basic authentication, where user name\
      \ equals the value used in
                    MessageId.institutionId and\
      \ password has been agreed with Electrum."
    type: "basic"
definitions:
  An32TokenPayment:
    allOf:
    - $ref: "#/definitions/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."
  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: "#/definitions/ThirdPartyIdentifier"
    description: "Basic advice response information."
  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: "#/definitions/ThirdPartyIdentifier"
      tenders:
        type: "array"
        description: "An array of tenders used to pay for the transaction"
        items:
          $ref: "#/definitions/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)"
        minLength: 0
        maxLength: 40
      lastName:
        type: "string"
        description: "The customer's last name"
        minLength: 0
        maxLength: 40
      address:
        type: "string"
        description: "The customer's address"
        minLength: 0
        maxLength: 80
    description: "A customer who ultimately requests a transaction be performed."
  DebtRecoveryCharge:
    type: "object"
    required:
    - "amount"
    - "balance"
    - "description"
    properties:
      amount:
        description: "Amount charged and tax levied for debt recovery, in minor denomination."
        $ref: "#/definitions/TaxableAmount"
      description:
        type: "string"
        description: "Description of this debt recovery charge (e.g. municipal rates\
          \ arrears)."
        minLength: 0
        maxLength: 40
      balance:
        description: "Remaining balance on this account."
        $ref: "#/definitions/LedgerAmount"
      receiptNum:
        type: "string"
        description: "Receipt number for this charge."
        minLength: 0
        maxLength: 30
    description: "Represents a charge deducted from the purchase to recover outstanding\
      \ debt"
  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"
      errorMessage:
        type: "string"
        description: "A short description of the error"
        minLength: 0
        maxLength: 20
      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"
      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: "A free form detailed description of a particular failure condition\
          \ may optionally be supplied"
    description: "Represents the outcome of a completed transaction"
  FaultReportRequest:
    type: "object"
    required:
    - "client"
    - "contactNumber"
    - "faultType"
    - "id"
    - "meter"
    - "originator"
    - "thirdPartyIdentifiers"
    - "time"
    properties:
      meter:
        description: "Details of the meter for which fault is logged. The object must\
          \ include at least a value for meterId."
        $ref: "#/definitions/Meter"
      customer:
        description: "Details of the person or organization to whom the meter belongs."
        $ref: "#/definitions/Customer"
      contactNumber:
        type: "string"
        description: "Contact telephone number of the person reporting the fault"
        minLength: 0
        maxLength: 20
      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"
      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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/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"
      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"
    description: "Data required to report a fault related to a specific meter"
  FaultReportResponse:
    type: "object"
    required:
    - "client"
    - "description"
    - "id"
    - "originator"
    - "reference"
    - "thirdPartyIdentifiers"
    - "time"
    properties:
      reference:
        type: "string"
        description: "Reference number for the fault report"
      description:
        type: "string"
        description: "Description of the fault"
        minLength: 0
        maxLength: 160
      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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/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"
      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"
    description: "Represents a response to a fault report"
  Institution:
    type: "object"
    required:
    - "id"
    - "name"
    properties:
      id:
        type: "string"
        description: "The institution's id as assigned by Electrum"
        pattern: "[0-9]{1,11}"
      name:
        type: "string"
        description: "The institutions's name"
        minLength: 0
        maxLength: 40
    description: "Originating, acquiring, processing, or receiving institution details"
  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:
      meter:
        description: "Details of the meter."
        $ref: "#/definitions/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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/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"
      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"
    description: "Represents a request for a key change token"
  KeyChangeTokenResponse:
    type: "object"
    required:
    - "client"
    - "id"
    - "meter"
    - "originator"
    - "thirdPartyIdentifiers"
    - "time"
    properties:
      meter:
        description: "Details of the meter."
        $ref: "#/definitions/Meter"
      tokens:
        type: "array"
        description: "List of tokens issued for the key change."
        items:
          $ref: "#/definitions/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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "A ready-to-print till slip. This is supplied by some providers\
          \ either in addition to or in place of individual message elements. Where\
          \ present, it must be used by POS to print the slip."
        $ref: "#/definitions/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"
      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"
    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: "#/definitions/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"
        minLength: 15
        maxLength: 15
      merchantName:
        description: "The name of a merchant"
        $ref: "#/definitions/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"
        minLength: 0
        maxLength: 23
      city:
        type: "string"
        description: "The city where the merchant is located"
        minLength: 0
        maxLength: 13
      region:
        type: "string"
        description: "The state or region where the merchant is located"
        minLength: 0
        maxLength: 2
      country:
        type: "string"
        description: "The country where the merchant is located"
        minLength: 0
        maxLength: 2
    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:
        description: "Represents new meter data in the case that these these have\
          \ been updated."
        $ref: "#/definitions/KeyChangeData"
    description: "Data associated with a prepaid utility meter"
  MeterLookupRequest:
    type: "object"
    required:
    - "client"
    - "id"
    - "meter"
    - "originator"
    - "thirdPartyIdentifiers"
    - "time"
    properties:
      meter:
        description: "Details of the meter for which information is requested. The\
          \ object must include at least a value for meterId."
        $ref: "#/definitions/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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/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"
      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"
    description: "Represents a request for information about a meter"
  MeterLookupResponse:
    type: "object"
    required:
    - "client"
    - "customer"
    - "id"
    - "meter"
    - "originator"
    - "thirdPartyIdentifiers"
    - "time"
    - "utility"
    properties:
      meter:
        description: "Details of the meter."
        $ref: "#/definitions/Meter"
      customer:
        description: "Details of the person or organization to whom the meter belongs."
        $ref: "#/definitions/Customer"
      utility:
        description: "Details of the utility which manages this meter's account."
        $ref: "#/definitions/Utility"
      minAmount:
        description: "Minimum purchase amount that can be requested by the customer."
        $ref: "#/definitions/LedgerAmount"
      maxAmount:
        description: "Maximum purchase amount that can be requested by the customer."
        $ref: "#/definitions/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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/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"
      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"
    description: "Represents a response to a meter lookup request"
  Originator:
    type: "object"
    required:
    - "institution"
    - "merchant"
    - "terminalId"
    properties:
      institution:
        description: "The institution originating the request, as issued by Electrum"
        $ref: "#/definitions/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"
        minLength: 8
        maxLength: 8
      merchant:
        description: "Merchant data. Required if available"
        $ref: "#/definitions/Merchant"
    description: "The Originator object encapsulates data relating to the originator\
      \ of the transaction"
  PaymentMethod:
    type: "object"
    required:
    - "amount"
    - "type"
    discriminator: "type"
    properties:
      type:
        type: "string"
        description: "The general method of payment used"
        enum:
        - "AN_32_TOKEN"
        - "LOYALTY_CARD"
      name:
        type: "string"
        description: "The specific method of payment used"
      amount:
        description: "Ledger amount of the payment"
        $ref: "#/definitions/LedgerAmount"
    description: "Base model for all payment types"
  PurchaseRequest:
    type: "object"
    required:
    - "client"
    - "id"
    - "meter"
    - "originator"
    - "purchaseAmount"
    - "thirdPartyIdentifiers"
    - "time"
    properties:
      meter:
        description: "Details of the meter for which a purchase is requested. The\
          \ object must include at least a value for meterId."
        $ref: "#/definitions/Meter"
      purchaseAmount:
        description: "Monetary amount, in minor denomination, of the requested token\
          \ purchase."
        $ref: "#/definitions/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: "#/definitions/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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/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"
      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"
      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: "#/definitions/PaymentMethod"
    description: "Represents a token purchase request"
  PurchaseResponse:
    type: "object"
    required:
    - "client"
    - "customer"
    - "id"
    - "meter"
    - "originator"
    - "thirdPartyIdentifiers"
    - "time"
    - "utility"
    properties:
      purchaseTotal:
        description: "The total amount charged for tokens on this purchase. This amount\
          \ is exclusive of tax and also excludes any debt recoveries or service charges\
          \ deducted from the purchase amount."
        $ref: "#/definitions/LedgerAmount"
      taxTotal:
        description: "The total tax charged for this purchase. This amount may include\
          \ taxes levied on the tokens purchased, as well as any taxes on debt recovery\
          \ or service charges."
        $ref: "#/definitions/LedgerAmount"
      meter:
        description: "Details of the meter."
        $ref: "#/definitions/Meter"
      customer:
        description: "Details of the person or organization to whom the meter belongs."
        $ref: "#/definitions/Customer"
      utility:
        description: "Details of the utility which manages this meter's account."
        $ref: "#/definitions/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: "#/definitions/Token"
      debtRecoveryCharges:
        type: "array"
        description: "List of charges that have been levied in order to reclaim outstanding\
          \ debts associated with the meter."
        items:
          $ref: "#/definitions/DebtRecoveryCharge"
      serviceCharges:
        type: "array"
        description: "List of service charges levied against this meter."
        items:
          $ref: "#/definitions/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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/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"
      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"
    description: "Represents the response to a token purchase request"
  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: "#/definitions/ThirdPartyIdentifier"
      reversalReason:
        type: "string"
        description: "The reason for the reversal"
        enum:
        - "TIMEOUT"
        - "CANCELLED"
        - "RESPONSE_NOT_FINAL"
    description: "Represents a request to reverse a previous transaction transaction."
  ServiceCharge:
    type: "object"
    required:
    - "amount"
    - "description"
    properties:
      amount:
        description: "Amount charged and tax levied for the service."
        $ref: "#/definitions/TaxableAmount"
      description:
        type: "string"
        description: "Description of this service charge (e.g. connection fee)."
        minLength: 0
        maxLength: 40
    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: "#/definitions/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:
        description: "Barcode information for this line"
        $ref: "#/definitions/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)."
        minLength: 0
        maxLength: 10
      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:
        description: "The tendered amount"
        $ref: "#/definitions/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"
        minLength: 0
        maxLength: 40
      tenderType:
        type: "string"
        description: "The type of tender used"
        enum:
        - "CASH"
        - "CHEQUE"
        - "CREDIT_CARD"
        - "DEBIT_CARD"
        - "WALLET"
        - "ROUNDING"
        - "GIFT_CARD"
        - "LOYALTY_CARD"
        - "OTHER"
    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's ID as assigned by Electrum."
        pattern: "[0-9]{1,11}"
      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. Entity's\
      \ must not alter the identifier set by another entity. Once an identifier has\
      \ been set by an entity, all other entity's must send that identifier in subsequent\
      \ messages."
  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"
      units:
        type: "number"
        description: "Number of units redeemable by this token."
      amount:
        description: "Monetary value of the token"
        $ref: "#/definitions/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: "#/definitions/TariffBlock"
    description: "Represents a prepaid utility token"
  TokenReprintRequest:
    type: "object"
    required:
    - "client"
    - "id"
    - "meter"
    - "originator"
    - "thirdPartyIdentifiers"
    - "time"
    properties:
      meter:
        description: "Details of the meter for which a token reprint is requested.\
          \ The object must include at least a value for meterId."
        $ref: "#/definitions/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:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/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"
      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"
    description: "Represents a request for a token reprint"
  Utility:
    type: "object"
    properties:
      name:
        type: "string"
        description: "Name of the utility."
        minLength: 0
        maxLength: 40
      address:
        type: "string"
        description: "Physical address of the utility."
        minLength: 0
        maxLength: 80
      vatRegNum:
        type: "string"
        description: "VAT registration number of the utility."
        minLength: 0
        maxLength: 10
      clientId:
        type: "string"
        description: "Identifier assigned by the utility to the client connecting\
          \ to the utility's token issuing service."
        minLength: 0
        maxLength: 20
      message:
        type: "string"
        description: "Message send by the utility to be displayed on the customer\
          \ receipt."
        minLength: 0
        maxLength: 80
    description: "Represents a utility with whom a meter is registered"