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.13.0"
  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:
  /events/tokenPurchases:
    post:
      summary: "Notifies that a successful token purchase has taken place."
      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"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "purchaseId"
        in: "query"
        description: "The id of the original purchase request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A token purchase response"
        required: true
        schema:
          $ref: "#/definitions/PurchaseResponse"
      responses:
        202:
          description: "Accepted"
        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"
      security:
      - httpBasic: []
  /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: []
  /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: []
  /keyChangeTokenRequests/{requestId}/confirmations/{confirmationId}:
    post:
      summary: "Confirms that key change tokens have been provided to the customer."
      description: "Confirms that key change tokens have been provided successfully"
      operationId: "confirmKeyChange"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "requestId"
        in: "path"
        description: "The randomly generated UUID of the original 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 key change confirmation"
        required: true
        schema:
          $ref: "#/definitions/KeyChangeConfirmation"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/BasicAdvice"
        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"
      security:
      - httpBasic: []
  /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: []
  /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"
      security:
      - httpBasic: []
  /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"
      security:
      - httpBasic: []
  /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"
      security:
      - httpBasic: []
  /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"
      security:
      - httpBasic: []
  /tokenPurchases/{trialId}/trial:
    post:
      summary: "Requests a trial token purchase for a specified meter."
      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"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "trialId"
        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:
        200:
          description: "OK"
          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"
      security:
      - httpBasic: []
  /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"
      security:
      - httpBasic: []
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:
  AccountPayment:
    allOf:
    - $ref: "#/definitions/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"
  Amounts:
    type: "object"
    properties:
      requestAmount:
        description: "The transaction amount requested by the customer to be authorised\
          \ or approved. This is the total amount the customer wishes to pay for a\
          \ service or virtual product."
        $ref: "#/definitions/LedgerAmount"
      approvedAmount:
        description: "The transaction amount which was approved by the upstream entity."
        $ref: "#/definitions/LedgerAmount"
      feeAmount:
        description: "Fees charged by the upstream entity for processing the transaction."
        $ref: "#/definitions/LedgerAmount"
      balanceAmount:
        description: "The remaining balance on the customer's account."
        $ref: "#/definitions/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: "#/definitions/LedgerAmount"
    description: "Amounts which make up the transaction. Absent amounts have zero\
      \ value."
  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."
  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: "#/definitions/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:
        description: "Communicates the final amount for a transaction in the approvedAmount\
          \ field. If absent from a reversal then a full reversal is implied (i.e.\
          \ a final amount of zero). If absent from a confirmation then a full confirmation\
          \ is implied (i.e. the final amount is the same as the approvedAmount of\
          \ the  authorisation response). The approvedAmount in an advice message\
          \ should be less than or equal to the approvedAmount of the authorisation\
          \ response as stand-in transactions are not currently supported."
        $ref: "#/definitions/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: "#/definitions/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:
        description: "Communicates the final amount for a transaction in the approvedAmount\
          \ field. If absent from a reversal then a full reversal is implied (i.e.\
          \ a final amount of zero). If absent from a confirmation then a full confirmation\
          \ is implied (i.e. the final amount is the same as the approvedAmount of\
          \ the  authorisation response). The approvedAmount in an advice message\
          \ should be less than or equal to the approvedAmount of the authorisation\
          \ response as stand-in transactions are not currently supported."
        $ref: "#/definitions/Amounts"
    description: "Basic advice response information."
  CardPayment:
    allOf:
    - $ref: "#/definitions/PaymentMethod"
    - type: "object"
      required:
      - "pan"
      properties:
        posInfo:
          $ref: "#/definitions/PosInfo"
        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}"
        encryptedPin:
          description: "The encrypted pin number associated with the card in HEX format."
          $ref: "#/definitions/EncryptedPin"
        pin:
          description: "The PIN associated with this card as either a clear PIN or\
            \ an encrypted PIN in HEX format."
          $ref: "#/definitions/Pin"
      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: "#/definitions/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:
        description: "Communicates the final amount for a transaction in the approvedAmount\
          \ field. If absent from a reversal then a full reversal is implied (i.e.\
          \ a final amount of zero). If absent from a confirmation then a full confirmation\
          \ is implied (i.e. the final amount is the same as the approvedAmount of\
          \ the  authorisation response). The approvedAmount in an advice message\
          \ should be less than or equal to the approvedAmount of the authorisation\
          \ response as stand-in transactions are not currently supported."
        $ref: "#/definitions/Amounts"
      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
      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"
        format: "email"
        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)."
    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"
  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}"
      encryptionParameters:
        description: "Parameters pertaining to the generation of the pinBlock. Required\
          \ if the service is to perform any operations on the encrypted PIN, such\
          \ as PIN translation."
        $ref: "#/definitions/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"
      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"
        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"
        - "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: "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"
      faultDescription:
        type: "string"
        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"
        - "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:
      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"
        - "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."
        minLength: 0
        maxLength: 20
    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"
        minLength: 0
        maxLength: 40
    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: "#/definitions/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:
        description: "Communicates the final amount for a transaction in the approvedAmount\
          \ field. If absent from a reversal then a full reversal is implied (i.e.\
          \ a final amount of zero). If absent from a confirmation then a full confirmation\
          \ is implied (i.e. the final amount is the same as the approvedAmount of\
          \ the  authorisation response). The approvedAmount in an advice message\
          \ should be less than or equal to the approvedAmount of the authorisation\
          \ response as stand-in transactions are not currently supported."
        $ref: "#/definitions/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:
      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"
        - "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:
      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"
        - "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: "#/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"
        - "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:
      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"
      arrearsAmount:
        description: "Returned arrears amount from provider. Encapsulates the total\
          \ debt outstanding."
        $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"
        - "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:
        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"
      operatorId:
        type: "string"
        description: "The ID that uniquely identifies the person operating the terminal\
          \ specified by the terminalId field."
        minLength: 0
        maxLength: 30
    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"
        - "CARD"
        - "ACCOUNT"
        - "REWARD"
      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"
  Pin:
    type: "object"
    required:
    - "type"
    discriminator: "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: "#/definitions/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: "#/definitions/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}"
        encryptionParameters:
          description: "Parameters pertaining to the generation of the pinBlock. Required\
            \ if the service is to perform any operations on the encrypted PIN, such\
            \ as PIN translation."
          $ref: "#/definitions/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: "#/definitions/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:
          description: "Parameters that describe the hashing algorithm used to hash\
            \ the PIN."
          $ref: "#/definitions/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:
        description: "Describes the manner in which the POS captured card and PIN\
          \ data."
        $ref: "#/definitions/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:
      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"
        - "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: "#/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"
      amounts:
        description: "An optional amounts field for any additional amounts which may\
          \ need to be added to the response payload."
        $ref: "#/definitions/Amounts"
      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"
        - "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"
  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"
      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:
        description: "Communicates the final amount for a transaction in the approvedAmount\
          \ field. If absent from a reversal then a full reversal is implied (i.e.\
          \ a final amount of zero). If absent from a confirmation then a full confirmation\
          \ is implied (i.e. the final amount is the same as the approvedAmount of\
          \ the  authorisation response). The approvedAmount in an advice message\
          \ should be less than or equal to the approvedAmount of the authorisation\
          \ response as stand-in transactions are not currently supported."
        $ref: "#/definitions/Amounts"
      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."
  RewardPayment:
    allOf:
    - $ref: "#/definitions/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:
        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 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. 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"
        - "PWRLMT"
      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"
        - "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"
  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"