openapi: 3.0.0
info:
  description: |-
    The Electrum Airtime Service describes an interface for airtime
                      transactions.
  version: 5.28.0
  title: Airtime Service Interface
  contact:
    name: Electrum Support
    url: https://electrum.co.za/contact
    email: support@electrum.co.za
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
  /msisdn:
    get:
      summary: lookupMsisdn
      description: >-
        Looks up information associated with the given Msisdn. This includes
        such information as available products and promotions, operator
        information etc.
      operationId: lookupMsisdn
      parameters:
        - name: msisdn
          in: query
          description: >-
            The Msisdn. This must conform to the ITU E.164 numbering plan
            (https://www.itu.int/rec/T-REC-E.164/en).
          required: true
          schema:
            type: string
        - name: senderMsisdn
          in: query
          description: >-
            The sender Msisdn. The MSISDN from which the request originated.
            This must conform to the ITU E.164 numbering plan
            (https://www.itu.int/rec/T-REC-E.164/en).
          required: false
          schema:
            type: string
        - name: operator
          in: query
          description: The provider who processed the original purchase attempt.
          required: false
          schema:
            type: string
        - name: productType
          in: query
          description: >-
            Used to filter the products to lookup for a given msisdn. This
            should be a value appropriate for the `Product.type` field.
          required: false
          schema:
            type: string
        - name: channelName
          in: query
          description: Used to filter the products to lookup for a given channel.
          required: false
          schema:
            type: string
        - name: productCategory
          in: query
          description: >-
            Used to filter the products to lookup within a specific category.
            The `productType` field should be used preferentially if applicable.
            An example of a relevant `productCategory` would be the name of a
            promotion if only products within a specific promotion should be
            retrieved.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsisdnInfoResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /products:
    get:
      summary: listProducts
      description: >-
        If a list of products that are available for sale is maintained, this
        API call returns the list of products. If such a list is not maintained,
        then a 501 Not Implemented status code will be returned.
      operationId: listProducts
      parameters:
        - name: channelName
          in: query
          description: >-
            The name of the channel to retrieve products for. If set only
            products matching this channel name will be returned. If not set,
            all products will be returned.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '501':
          description: Not implemented
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /purchases:
    post:
      summary: purchase
      description: Requests an airtime product from the service provider.
      operationId: purchase
      requestBody:
        $ref: '#/components/requestBodies/PurchaseRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /purchases/confirmations:
    post:
      summary: purchaseConfirmation
      description: >-
        Once a consumer has paid for an airtime product the merchant must notify
        the vendor that the transactioncompleted successfully at the POS. This
        operation must be repeated until a final HTTP status code isreceived
        (i.e. not 500 or 504). The operation is idempotent and so may be called
        repeatedly without negative effect.
      operationId: purchaseConfirmation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseConfirmation'
        description: A purchase confirmation.
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseConfirmation'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /purchases/reversals:
    post:
      summary: purchaseReversal
      description: >-
        If a purchase operation fails with a 500 or 504 HTTP status code, or no
        response was received within the timeout period, and the provider
        supports the reversal operation, it must be reversed to ensure the
        provider knows the airtime purchase did not complete successfully. This
        operation must be repeated until a final HTTP status code is received
        (i.e. not 500 or 504). The operation is idempotent and so may be called
        repeatedly on the same airtime purchase resource without negative
        effect. If the airtime provider does not support the reversal operation,
        refer to the purchaseStatus operation.
      operationId: purchaseReversal
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseReversal'
        description: An airtime purchase reversal.
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseReversal'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /purchases/status:
    get:
      summary: purchaseStatus
      description: >-
        If the airtime provider does not support the reversal operation then the
        purchaseStatus operation should be used to determine the outcome of a
        prior purchase. This operation will, as far as possbile, return the same
        PurchaseResponse or ErrorDetail as would have been returned had the
        original purchase completed normally.
      operationId: purchaseStatus
      parameters:
        - name: provider
          in: query
          description: >-
            The provider who processed the original purchase attempt.
            Conditionally required if purchaseRef is supplied.
          required: false
          schema:
            type: string
        - name: purchaseReference
          in: query
          description: >-
            The reference returned in the original purchase attempt.
            Conditionally required if the originalMsgId is not supplied.
          required: false
          schema:
            type: string
        - name: originalMsgId
          in: query
          description: >-
            The message ID of the original PurchaseRequest which failed.
            Conditionally required if the purchaseRef is not supplied.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /purchases/trials:
    post:
      summary: purchaseTrial
      description: >-
        This operation is identical to the purchase operation except that no
        voucher is returned (for voucher based products) or no product will be
        applied to the MSISDN (for direct top-ups). This operation carries no
        financial impact. The purpose of the operation is to determine whether
        it is worth proceeding to a tender step, i.e. is a subsequent purchase
        likely to to be successful (in which case the downstream should move to
        the tender step) or fail (in which case the downstream should not take
        tender).
      operationId: purchaseTrial
      requestBody:
        $ref: '#/components/requestBodies/PurchaseRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
  /vouchers/{requestId}:
    post:
      summary: provisionVoucher
      description: Requests a voucher from the voucher vendor.
      operationId: provisionVoucher
      parameters:
        - name: requestId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoucherRequest'
        description: A voucher request.
        required: true
      responses:
        '201':
          description: Created
          headers:
            Location:
              description: The location of the created voucher resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoucherResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
      deprecated: true
  /vouchers/{requestId}/confirmations/{confirmationId}:
    post:
      summary: confirmVoucher
      description: >-
        Once a consumer has paid for a voucher and received the voucher from the
        merchant the merchant must notify the vendor that the voucher may be
        redeemed at some point in the future as per the voucher vendor's
        instructions. This operation must be repeated until a final HTTP status
        code is received (i.e. not 500 or 504). The operation is idempotent, so
        may be called repeatedly on the same voucher resource without negative
        effect.
      operationId: confirmVoucher
      parameters:
        - name: requestId
          in: path
          description: The UUID generated for the original voucher provision request.
          required: true
          schema:
            type: string
        - name: confirmationId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoucherConfirmation'
        description: A voucher provision confirmation.
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicAdvice'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
      deprecated: true
  /vouchers/{requestId}/reversals/{reversalId}:
    post:
      summary: reverseVoucher
      description: >-
        If a voucherProvision request fails with a 500 or 504 HTTP status code,
        or no response was received within the timeout period, it must be
        reversed to ensure the vendor knows to never expect further messages
        pertaining to the voucher. This operation must be repeated until a final
        HTTP status code is received (i.e. not 500 or 504). The operation is
        idempotent, so may be called repeatedly on the same voucher resource
        without negative effect.
      operationId: reverseVoucher
      parameters:
        - name: requestId
          in: path
          description: The UUID generated for the original voucher provision request.
          required: true
          schema:
            type: string
        - name: reversalId
          in: path
          description: The randomly generated UUID of this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BasicReversal'
        description: A voucher provision reversal.
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicAdvice'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      security:
        - httpBasic: []
        - oauth2: []
      deprecated: true
servers:
  - url: https://[placeholder].dev/airtime/v5
components:
  requestBodies:
    PurchaseRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PurchaseRequest'
      description: An airtime request.
      required: true
  securitySchemes:
    httpBasic:
      description: >-
        HTTP basic authentication. If you are doing a client side integration,
        Electrum will provide the username and password to the client. If you
        are doing a server side implementation, you will be expected to provide
        these credentials.
      type: http
      scheme: basic
    oauth2:
      description: >-
        OAuth2 password authentication, where the token URL, client ID, client
        secret, username, and password will be provided by Electrum if you
        implementing a client side integration. If you are doing a server side
        implementation, you will be expected to provide these credentials.
      type: oauth2
      flows:
        password:
          tokenUrl: >-
            https://auth.electrum.dev/auth/realms/Example-Realm/protocol/openid-connect/token
          scopes: {}
  schemas:
    AccountPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            srcAccountId:
              type: string
              description: Source AccountId from which this payment will be made.
            srcCustomerId:
              type: string
              description: Source CustomerId from which this payment will be made.
            destAccountId:
              type: string
              description: Destination AccountId to which this payment will be made.
            destCustomerId:
              type: string
              description: Destination CustomerId to which this payment will be made.
          description: Model for an account-to-account payment method
    Amounts:
      type: object
      properties:
        requestAmount:
          $ref: '#/components/schemas/LedgerAmount'
        approvedAmount:
          $ref: '#/components/schemas/LedgerAmount'
        feeAmount:
          $ref: '#/components/schemas/LedgerAmount'
        balanceAmount:
          $ref: '#/components/schemas/LedgerAmount'
        additionalAmounts:
          type: object
          description: >-
            Any additional amounts that are involved in a transaction which
            don't appropriately fit into the other amount fields.
          additionalProperties:
            $ref: '#/components/schemas/LedgerAmount'
      description: Amounts which make up the transaction. Absent amounts have zero value.
    An32TokenPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - token
          properties:
            token:
              type: string
              description: 32 character alphanumeric code which identifies a token
              pattern: '[a-zA-Z0-9]{32}'
          description: Model for token-based payments
    Barcode:
      type: object
      required:
        - data
        - encoding
      properties:
        data:
          type: string
          description: Data to be encoded in the barcode
        encoding:
          type: string
          description: Specifies the encoding used in the barcode
      description: Used to indicate barcode information for a slip line.
    BasicAdvice:
      type: object
      required:
        - id
        - requestId
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
      description: The data required in all advice messages
    BasicReversal:
      type: object
      required:
        - id
        - requestId
        - reversalReason
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        reversalReason:
          type: string
          description: The reason for the reversal
          enum:
            - TIMEOUT
            - CANCELLED
            - RESPONSE_NOT_FINAL
      description: >-
        An advice that notifies of the negative completion of a transaction.
        This can be either due to customer cancellation, or as a result of
        receiving a non-final response (or no response) to a request
    CardPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - pan
          properties:
            posInfo:
              $ref: '#/components/schemas/PosInfo'
            pin:
              $ref: '#/components/schemas/Pin'
            pan:
              type: string
              description: Primary account number that uniquely identifies this card.
              pattern: '[0-9]{1,19}'
            expiryDate:
              type: string
              description: The card expiry date, in YYMM format.
              pattern: '[0-9]{4}'
            threeDSecureData:
              $ref: '#/components/schemas/ThreeDSecureData'
            encryptedPin:
              $ref: '#/components/schemas/EncryptedPin'
          description: Model for card-based payments
    ChannelProductListing:
      type: object
      required:
        - channelName
      properties:
        channelName:
          type: string
          description: The name of the channel.
          minLength: 0
          maxLength: 50
        productDisplayName:
          type: string
          description: The name of the product for display purposes.
          minLength: 0
          maxLength: 50
        productDisplayCategory:
          type: string
          description: A category that is meaningful for display purposes.
          minLength: 0
          maxLength: 50
        productDisplaySortOrder:
          type: number
          format: double
          description: A menu sort order that is meaningful for display purposes.
        channelProductIdentifier:
          type: string
          description: A product identifier which is meaningful for the channel.
      description: Product data is it relates to a channel.
    Description:
      type: object
      properties:
        additionalDescriptions:
          type: object
          additionalProperties:
            type: string
        primaryDescription:
          type: string
          description: The primary description of a product.
        shortDescription:
          type: string
          description: >-
            A short description for a product which can be displayed alongside
            the name of the product to provide additional context.
      description: >-
        A description for a product which contains relevant different types of
        descriptions.
    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:
          $ref: '#/components/schemas/EncryptionParameters'
      description: >-
        A PIN required to authorise a transaction. EncryptionParameters should
        be provided where the service will be performing operations on the
        encrypted PIN, such as PIN translation. Only the PIN block need be
        provided where the service is expected to forward it to a third party,
        where the calling client and said third party have agreed upon
        encryption parameters beforehand.
    EncryptionParameters:
      type: object
      required:
        - accountNumber
      properties:
        pinBlockFormat:
          type: string
          description: >-
            PIN block format that was used when encrypting the PIN. Defaults to
            ISO_9564_FORMAT_0.
          default: ISO_9564_FORMAT_0
          enum:
            - ISO_9564_FORMAT_0
            - ISO_9564_FORMAT_1
            - ISO_9564_FORMAT_3
        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:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this errorDetail, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
          minLength: 0
          maxLength: 20
        originalId:
          type: string
          description: >-
            The UUID of the original request message in the case of an error
            occurring for an advice message
        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
            - INVALID_PRODUCT
            - ACCOUNT_ALREADY_SETTLED
            - INVALID_MERCHANT
            - OUT_OF_STOCK
            - INVALID_AN32_TOKEN
            - DO_NOT_HONOR
            - DECLINED_BY_MNO
            - INVALID_MSISDN
            - INVALID_LOYALTY_CARD
            - INSUFFICIENT_FUNDS
            - INVALID_CARD_NUMBER
            - CARD_EXPIRED
            - INCORRECT_PIN
            - PIN_ATTEMPTS_EXCEEDED
            - OUTCOME_UNKNOWN
            - SYSTEM_MALFUNCTION
            - LIMIT_EXCEEDED
        errorMessage:
          type: string
          description: A short description of the error
          minLength: 0
          maxLength: 20
        requestType:
          type: string
          description: The type of request that preceeded the error
          enum:
            - VOUCHER_REQUEST
            - VOUCHER_REVERSAL
            - VOUCHER_CONFIRMATION
            - VOUCHER_VOID
            - MSISDN_INFO_REQUEST
            - PURCHASE_REQUEST
            - PURCHASE_CONFIRMATION
            - PURCHASE_STATUS_REQUEST
            - PURCHASE_REVERSAL
            - TRIAL_PURCHASE_REQUEST
            - LIST_PRODUCTS_REQUEST
        detailMessage:
          type: object
          description: >-
            A free form detailed description of a particular failure condition
            may optionally be supplied
        providerErrorCode:
          type: string
          description: >-
            The error code returned by the service provider. Note that this
            should be used for informational purposes only. Messages displayed
            on the POS should make use of errorType and errorMessage to ensure a
            consistent set of responses.
        providerErrorMsg:
          type: string
          description: >-
            The error message returned by the service provider. Note that this
            should be used for informational purposes only. Messages displayed
            on the POS should make use of errorType and errorMessage to ensure a
            consistent set of responses.
        providerRef:
          type: string
          description: The reference returned by the service provider.
      description: Represents the outcome of a completed transaction
    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
    LedgerAmount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: integer
          format: int64
          description: Amount in minor denomination, e.g. R799.95 is encoded as 79995
        currency:
          type: string
          description: >-
            Three digit currency number from ISO 4217, e.g. South African Rand
            is encoded as 710
          pattern: '[0-9]{3}'
        ledgerIndicator:
          type: string
          description: >-
            Indicates whether this amount is a debit or a credit. Only required
            when the amount can be either a debit or a credit
          enum:
            - DEBIT
            - CREDIT
      description: >-
        An amount object only containing value and currency, and optionally an
        indicator of DEBIT/CREDIT
    LoyaltyCardPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - cardNumber
          properties:
            cardNumber:
              type: string
              description: >-
                Primary account number of the loyalty programme card used to
                make a payment
              pattern: '[0-9]{16}'
          description: Model for payments made using loyalty programme cards
    Merchant:
      type: object
      required:
        - merchantId
        - merchantName
        - merchantType
      properties:
        merchantType:
          type: string
          description: The assigned four digit merchant category code
          pattern: '[0-9]{4}'
        merchantId:
          type: string
          description: The assigned merchant identifier. Also known as card acceptor id
          minLength: 15
          maxLength: 15
        merchantName:
          $ref: '#/components/schemas/MerchantName'
      description: Merchant related data. Must be included if available
    MerchantName:
      type: object
      required:
        - city
        - country
        - name
        - region
      properties:
        name:
          type: string
          description: The merchant or trading as name associated with the merchant
          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
    Msisdn:
      type: object
      required:
        - msisdn
      properties:
        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{1,14}
        country:
          type: string
          description: >-
            The country of the Msisdn expressed as an ISO 3166-1 Alpha-2 country
            code.
          minLength: 2
          maxLength: 2
        operator:
          $ref: '#/components/schemas/Institution'
      description: Msisdn related data.
    MsisdnInfoResponse:
      type: object
      properties:
        msisdn:
          $ref: '#/components/schemas/Msisdn'
        senderMsisdn:
          $ref: '#/components/schemas/Msisdn'
        amounts:
          $ref: '#/components/schemas/Amounts'
        promotion:
          $ref: '#/components/schemas/Promotion'
        availableProducts:
          type: array
          description: >-
            Products which may be available to the customer identified by the
            Msisdn.
          items:
            $ref: '#/components/schemas/Product'
      description: Information about the Msisdn.
    Originator:
      type: object
      required:
        - institution
        - merchant
        - terminalId
      properties:
        institution:
          $ref: '#/components/schemas/Institution'
        terminalId:
          type: string
          description: >-
            The ID that uniquely identifies each device or system in an
            originator's institution capable of sending requests. Required for
            transactions initiated from physical card entry or point-of-sale
            devices
          minLength: 8
          maxLength: 8
        merchant:
          $ref: '#/components/schemas/Merchant'
        operatorId:
          type: string
          description: >-
            The ID that uniquely identifies the person operating the terminal
            specified by the terminalId field.
          minLength: 0
          maxLength: 30
        channelId:
          type: string
          description: >-
            The ID that uniquely identifies the originator's channel that this
            transaction was received through.
          minLength: 0
          maxLength: 50
      description: >-
        The Originator object encapsulates data relating to the originator of
        the transaction
    PaymentMethod:
      type: object
      required:
        - type
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          description: The general method of payment used
          enum:
            - AN_32_TOKEN
            - LOYALTY_CARD
            - CARD
            - ACCOUNT
            - REWARD
            - WALLET
            - QR
        name:
          type: string
          description: The specific method of payment used
        amount:
          $ref: '#/components/schemas/LedgerAmount'
        issuer:
          $ref: '#/components/schemas/Institution'
        pin:
          $ref: '#/components/schemas/Pin'
        proxy:
          type: string
          description: >-
            An alternative identifier for the customer's source of funds. Acts
            as a stand in for the customer identifier. E.g. a customer's MSISDN
            or email address.
          minLength: 0
          maxLength: 40
        proxyType:
          type: string
          description: An enumerated value describing the type of value used as the proxy.
          enum:
            - MSISDN
            - EMAIL
            - UNKNOWN
      description: Base model for all payment types
    Pin:
      type: object
      required:
        - type
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          description: Whether the PIN is communicated in the clear or encrypted.
          enum:
            - CLEAR_PIN
            - ENCRYPTED_PIN
            - HASHED_PIN
      description: Base model for capturing either a clear PIN or encrypted PIN
    PinClear:
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          required:
            - pin
          properties:
            pin:
              type: string
              description: A clear PIN
              pattern: .{0,20}
          description: A clear PIN required to authorise a transaction.
    PinEncrypted:
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          required:
            - pinBlock
          properties:
            pinBlock:
              type: string
              description: Hexadecimal string representing the encrypted PIN to be used.
              pattern: '[a-fA-F0-9]{16}'
            encryptionParameters:
              $ref: '#/components/schemas/EncryptionParameters'
          description: >-
            A PIN required to authorise a transaction. EncryptionParameters
            should be provided where the service will be performing operations
            on the encrypted PIN, such as PIN translation. Only the PIN block
            need be provided where the service is expected to forward it to a
            third party, where the calling client and said third party have
            agreed upon encryption parameters beforehand.
    PinHashed:
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          required:
            - hash
          properties:
            hash:
              type: string
              description: A hashed PIN expressed as an ASCII string of hexadecimal values.
              pattern: '[0-9,A-F]{1,512}'
            hashedPinParameters:
              $ref: '#/components/schemas/HashedPinParameters'
          description: >-
            A PIN, required to authorise a transaction, which has been hashed
            according to some hashing algorithm.
    PosEntryMode:
      type: object
      required:
        - panEntryMode
        - pinEntryCapability
      properties:
        panEntryMode:
          type: string
          description: Describes the method by which the PAN was captured.
          enum:
            - UNKNOWN
            - MANUAL
            - MAGSTRIPE_NO_CVV
            - BARCODE
            - OCR
            - ICC_CVV
            - CONTACTLESS_ICC
            - MAGSTRIPE_CVV
            - CONTACTLESS_MAGSTRIPE
            - ICC_NO_CVV
            - ORIG_MODE
            - FALLBACK
        pinEntryCapability:
          type: string
          description: Describes whether the PIN can be entered.
          enum:
            - UNKNOWN
            - CAN_ACCEPT
            - CANNOT_ACCEPT
      description: Describes how the PAN and PIN were captured by the POS.
    PosInfo:
      type: object
      properties:
        entryMode:
          $ref: '#/components/schemas/PosEntryMode'
        posConditionCode:
          type: string
          description: Describes the circumstances of the transaciton at the POS.
          enum:
            - NORMAL_PRESENTMENT
            - CUSTOMER_NOT_PRESENT
            - CUSTOMER_PRESENT_AND_CARD_NOT_PRESENT
            - CUSTOMER_IDENTITY_VERIFIED
            - PUBLIC_UTILITY_TERMINAL
            - CUSTOMER_TERMINAL
            - MANUAL_REVERSAL
            - UNATTENDED_TERMINAL_AND_CARD_CAN_BE_RETAINED
            - UNATTENDED_TERMINAL_AND_CARD_CANNOT_BE_RETAINED
      description: POS related data.
    Product:
      type: object
      required:
        - productId
      properties:
        isDirectTopup:
          type: boolean
          description: >-
            Describes whether or not the product directly recharges the
            recipients account (true), or a voucher number is required (false)
            to redeem the product.
          default: false
        productId:
          type: string
          description: >-
            A vendor determined code identifying the product the voucher should
            pertain to.
          pattern: ^[a-zA-Z0-9!#%&':;()*+\-./<=>?@\\^_`|~]{1,20}$
        barcode:
          type: string
          description: >-
            A barcode code identifying the product. This is an alternative
            identifier for the product but does not supersede the productId.
          pattern: '[0-9A-Za-z]{1,13}'
        name:
          type: string
          description: The name of the product.
          minLength: 1
          maxLength: 120
        description:
          $ref: '#/components/schemas/Description'
        type:
          type: string
          description: An indication of the type of the product.
          enum:
            - AIRTIME_FIXED
            - AIRTIME_VARIABLE
            - SMS_BUNDLE
            - DATA
            - APP_RELATED
            - COMBO
            - DATA_FIXED
            - DATA_VARIABLE
            - VOICE_BUNDLE
        wholesalePrice:
          $ref: '#/components/schemas/LedgerAmount'
        recipientAmount:
          $ref: '#/components/schemas/LedgerAmount'
        productValues:
          type: array
          description: >-
            The value of the product. Multiple values may be returned in varying
            currencies in the case of products available internationally.
          items:
            $ref: '#/components/schemas/LedgerAmount'
        validityPeriod:
          $ref: '#/components/schemas/ValidityPeriod'
        productContents:
          type: array
          description: A list defining the contents of the airtime product.
          items:
            $ref: '#/components/schemas/ProductContent'
        operator:
          $ref: '#/components/schemas/Institution'
        channels:
          type: array
          description: A list of channels the product is available at.
          items:
            $ref: '#/components/schemas/ChannelProductListing'
      description: Product related data.
    ProductContent:
      type: object
      required:
        - amount
        - unit
      properties:
        amount:
          type: integer
          format: int64
          description: >-
            The size of the product in KB, MB or GB for data; Unit for SMSs;
            Minutes for airtime.
          minimum: 0
        unit:
          type: string
          description: >-
            The unit of product. Can be KB, MB or GB for data; Unit for SMSs;
            Minutes for airtime.
          enum:
            - KB
            - MB
            - GB
            - UNIT
            - MINUTES
      description: Specifically describes the content of the airtime product.
    Promotion:
      type: object
      required:
        - promotion
      properties:
        promotion:
          type: string
          description: A description of the promotion available to the subscriber.
        startDate:
          type: string
          format: date-time
          description: The start date of the promotion.
        endDate:
          type: string
          format: date-time
          description: The end date of the promotion.
      description: Promotion related data.
    PurchaseConfirmation:
      type: object
      required:
        - id
        - requestId
        - tenders
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        tenders:
          type: array
          description: An array of tenders used to pay for the transaction
          items:
            $ref: '#/components/schemas/Tender'
      description: >-
        Confirm that a previous {@link PurchaseRequest} has completed
        successfully at the POS.
    PurchaseRequest:
      type: object
      required:
        - client
        - id
        - originator
        - product
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        product:
          $ref: '#/components/schemas/Product'
        tenders:
          type: array
          description: >-
            An array of tenders used to pay for the transaction. This is used if
            payment is tendered at the point of sale. A Tender differs from a
            PaymentMethod in that the former represents a payment that has
            already been collected at the point of sale, whereas the latter
            represents a payment that still needs to be collected from a third
            party.
          items:
            $ref: '#/components/schemas/Tender'
        paymentMethods:
          type: array
          description: >-
            An array of payment methods to be used as payment for the
            transaction. This is used if payment is not tendered at the point of
            sale, but is effected through one or more calls to third party
            payment providers as part of the request. A PaymentMethod differs
            from a Tender in that the former represents payment that still needs
            to be collected from a third party, whereas the latter represents
            payment that has already been collected at the point of sale.
          items:
            $ref: '#/components/schemas/PaymentMethod'
        recipientMsisdn:
          $ref: '#/components/schemas/Msisdn'
        senderMsisdn:
          $ref: '#/components/schemas/Msisdn'
      description: >-
        A request for an airtime product. This may be for airtime, data or SMS
        products or a combination. Airtime requests may be for PIN based or
        PIN-less products.
    PurchaseResponse:
      type: object
      required:
        - client
        - id
        - originator
        - product
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        product:
          $ref: '#/components/schemas/Product'
        msisdn:
          $ref: '#/components/schemas/Msisdn'
        voucher:
          $ref: '#/components/schemas/Voucher'
      description: A response to a successful request for an airtime product.
    PurchaseReversal:
      type: object
      required:
        - id
        - requestId
        - reversalReason
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        reversalReason:
          type: string
          description: The reason for the reversal
          enum:
            - TIMEOUT
            - CANCELLED
            - RESPONSE_NOT_FINAL
      description: >-
        Reverse a previous {@link PurchaseRequest}. This may be due to a
        cancellation at the POS or because the original {@link PurchaseRequest}
        is in an unknown state.
    QrPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - tranId
          properties:
            tranId:
              type: string
              description: >-
                The unique transaction identifier related to this transaction.
                In QRs styled on the EMVCo specification, the tranId is embedded
                in sub-Tag 00 of the Electrum MAIT.
            partnerPaymentToken:
              type: string
              description: A payment token received from the Partner.
          description: >-
            Model for QR-based payments. This payment method should be used when
            a QR code is presented for payment.
    RewardPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - rewardCode
          properties:
            rewardCode:
              type: string
              description: A code used to recognise the reward programme
              minLength: 0
              maxLength: 40
          description: >-
            Model for reward-based payments. This payment method should be used
            when the payment is offset using a reward programme
    SlipData:
      type: object
      properties:
        messageLines:
          type: array
          description: >-
            An array of text lines and optional formatting to be printed on the
            customer slip.
          items:
            $ref: '#/components/schemas/SlipLine'
        slipWidth:
          type: integer
          format: int32
          description: The width of the slip in normal (unformatted) characters.
        issuerReference:
          type: string
          description: >-
            An identifier that is printed on the customer slip and uniquely
            identifies the payment on the service provider's system. This value
            is used by the customer to request a refund when the service
            supports this function, and it is thus important that this number is
            unique.
          pattern: '[A-Z0-9]{1,40}'
      description: Data that may be printed on the customer slip for information purposes
    SlipLine:
      type: object
      required:
        - text
      properties:
        barcode:
          $ref: '#/components/schemas/Barcode'
        text:
          type: string
          description: Text contained on the line
        fontWidthScaleFactor:
          type: number
          format: double
          description: >-
            Scale factor for font width. Assume 1.0 (i.e. normal size) if not
            present.
        fontHeightScaleFactor:
          type: number
          format: double
          description: >-
            Scale factor for font height. Assume 1.0 (i.e. normal size) if not
            present.
        line:
          type: boolean
          description: Denotes a solid line on the slip. Assume false if not present.
          default: false
        cut:
          type: boolean
          description: >-
            Indicates the slip should be cut at this line. Assume false if not
            present.
          default: false
      description: A line of text to be printed on the till slip
    Tender:
      type: object
      required:
        - amount
        - tenderType
      properties:
        accountType:
          type: string
          description: The type of account
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - STORED_VALUE
        amount:
          $ref: '#/components/schemas/LedgerAmount'
        cardNumber:
          type: string
          description: >-
            A PCI compliant masked card number, with at least the first 6 digits
            in the clear. Only applicable to card based transactions
          pattern: '[0-9]{6}[0-9*]{0,13}'
        reference:
          type: string
          description: A free text reference
          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
            - REWARD
      description: Details of the Tender used by a customer towards a payment
    ThirdPartyIdentifier:
      type: object
      required:
        - institutionId
        - transactionIdentifier
      properties:
        institutionId:
          type: string
          description: The entity's institution ID.
        transactionIdentifier:
          type: string
          description: >-
            The identifier assigned to this transaction by the institution
            represented in institutionId. This value should be unique within the
            institution's system.
      description: >-
        An identifier assigned by an entity which process the message.
        Identifiers are keyed by institution ID thereby enabling any institution
        to recall a transaction within the entity's own system using the
        entity's own identifier. Entities must not alter the identifier set by
        another entity. Once an identifier has been set by an entity, all other
        entities must send that identifier in subsequent messages.
    ThreeDSecureData:
      type: object
      required:
        - version
      discriminator:
        propertyName: version
      properties:
        authenticationValue:
          type: string
          description: >-
            A 20-byte value that has been Base64 encoded. This value is provided
            by the Access Control Server as a proof of authentication.
        cardHolderAuthVerificationResult:
          type: string
          description: Authentication outcome set by the Access Control Server or Issuer.
          enum:
            - CAVV_VALIDATION_PASSED
            - CAVV_VALIDATION_FAILED_ISSUER_SYSTEM_ERROR
            - CAVV_VALIDATION_FAILED_ISSUER_ATTEMPT_INCOMPLETE
            - CAVV_NOT_VALIDATED
            - CAVV_NOT_VALIDATED_INVALID_DATA
            - CAVV_VALIDATION_FAILED
        version:
          type: string
          description: >-
            The version of the 3-D Secure protocol that was used for cardholder
            authentication. Note that the version determines the format of the
            transaction identifier
          enum:
            - V1
            - V2
        eci:
          type: string
          description: >-
            Electronic Commerce Indicator. This is Payment System-specific value
            provided by the Access Control Server to indicate the results of the
            attempt to authenticate the Cardholder.
          enum:
            - AUTHENTICATION_NOT_ATTEMPTED_OR_UNSUCCESSFUL_00
            - AUTHENTICATION_NOT_ENABLED_01
            - AUTHENTICATION_SUCCESSFUL_02
            - AUTHENTICATION_SUCCESSFUL_05
            - AUTHENTICATION_NOT_ENABLED_06
            - AUTHENTICATION_NOT_ATTEMPTED_OR_UNSUCCESSFUL_07
        transactionStatus:
          type: string
          description: >-
            Indicates whether a transaction qualifies as an authenticated
            transaction or account verification. The values and their meanings
            are as follows: 

            Y = Authentication Verification Successful.
             N = Not Authenticated /Account Not Verified; Transaction denied.
             U = Authentication/ Account Verification Could Not Be Performed; Technical or other problem.
             A = Attempts Processing Performed; Not Authenticated/ Verified, but a proof of attempted authentication/verification is provided.
             C = Challenge Required; Additional authentication is required using the CReq/CRes 
             D = Challenge Required; Decoupled Authentication confirmed. 
             R = Authentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.
             I = Informational Only; 3DS Requestor challenge preference acknowledged.
             S = Challenge using SPC 
             
          enum:
            - 'Y'
            - 'N'
            - U
            - A
            - C
            - D
            - R
            - I
            - S
      description: >-
        Data used to facilitate and communicate the result of 3-D Secure
        cardholder authentication.
    ThreeDSecureDataV1:
      allOf:
        - $ref: '#/components/schemas/ThreeDSecureData'
        - type: object
          properties:
            transactionId:
              type: string
              description: >-
                A 20-byte base 64 encoded string assigned by the 3DS Server to
                identify a single transaction. This ID can be used to prevent
                transaction replay.
          description: >-
            3-D Secure data in which the transaction identifier takes the format
            of a byte string.
    ThreeDSecureDataV2:
      allOf:
        - $ref: '#/components/schemas/ThreeDSecureData'
        - type: object
          properties:
            transactionId:
              type: string
              format: uuid
              description: >-
                A UUID assigned by the 3DS Server to identify a single
                transaction. This ID can be used to prevent transaction replay.
                This is based on version 2 the EMVCo 3-D Secure specification.
          description: >-
            3-D Secure data in which the transaction identifier takes the format
            of a UUID.
    TransactionLabel:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: >-
            Label name that indicates the type and intended use of the
            transaction label. The meaning of label names must be agreed upon by
            the parties involved in transaction processing.
          pattern: ^[a-zA-Z0-9_]{1,100}$
        value:
          type: string
          description: The value assigned to the transaction label.
          pattern: ^[a-zA-Z0-9 _-]{1,100}$
      description: >-
        A label assigned to a transaction by the entity processing the
        transaction. Labels are used for grouping or discovering transactions
        after transaction processing. Note that no transaction processing
        decision is made based on transaction labels.
    ValidityPeriod:
      type: object
      required:
        - duration
        - durationUnit
      properties:
        duration:
          type: integer
          format: int64
          description: >-
            A long value describing the number of durationUnits for the validity
            period.
          minimum: 0
        durationUnit:
          type: string
          description: >-
            A value describing the unit of measurement to be applied to the
            validity period.
          enum:
            - NANOS
            - MICROS
            - MILLIS
            - SECONDS
            - MINUTES
            - HOURS
            - HALF_DAYS
            - DAYS
            - WEEKS
            - MONTHS
            - YEARS
            - DECADES
            - CENTURIES
            - MILLENNIA
            - ERAS
            - FOREVER
      description: >-
        Specifically describes the length of time for which a product is valid.
        Any unused portion of a product (e.g. unused data) will be forfeit at
        the end of the validity period.
    Voucher:
      type: object
      required:
        - serialNumber
      properties:
        pin:
          type: string
          description: >-
            The voucher's PIN used by the customer to redeem the voucher. This
            must be present in `VoucherResponse` messages. It is recommended
            this field not be populated in other instances as it may be
            considered sensitive data.
          pattern: '[0-9]{1,20}'
        expiryDate:
          type: string
          format: date-time
          description: >-
            The date and time at which the voucher expires in UTC. The format
            shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
        serialNumber:
          type: string
          description: >-
            The voucher's serial number. This can be used to identify the
            voucher in the vendor's system but cannot be used to redeem the
            voucher.
          pattern: '[0-9a-zA-Z]{1,20}'
        batchNumber:
          type: string
          description: >-
            The voucher's batch number. This can be used to help identify the
            voucher in the vendor's system but cannot be used to redeem the
            voucher.
          pattern: '[0-9a-zA-Z]{1,20}'
        redeemInstructions:
          type: array
          description: >-
            An array of free text lines which provide the customer with
            information on how to redeem the voucher. These are intended to be
            printed on a customer's receipt slip.
          items:
            type: string
      description: Specifically describes the voucher provisioned by the vendor.
    VoucherConfirmation:
      type: object
      required:
        - id
        - requestId
        - tenders
        - thirdPartyIdentifiers
        - time
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this advice, as defined for
            a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)
        requestId:
          type: string
          description: The UUID identifying the request that this advice relates to
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        thirdPartyIdentifiers:
          type: array
          description: >-
            The unaltered thirdPartyIdentifiers array as supplied in the related
            BasicResponse message. Required if thirdPartyIdentifiers field was
            present in the BasicResponse. If no thirdPartyIdentifiers was
            received in the BasicResponse or no BasicResponse was received then
            this should be set to the thirdPartyIdentifiers sent in the original
            request.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        tenders:
          type: array
          description: An array of tenders used to pay for the transaction
          items:
            $ref: '#/components/schemas/Tender'
        voucher:
          $ref: '#/components/schemas/Voucher'
      description: >-
        Information about the voucher provision being confirmed. This object
        refers to a specific voucher which was previously successfully
        provisioned.
    VoucherRequest:
      type: object
      required:
        - client
        - id
        - originator
        - product
        - thirdPartyIdentifiers
        - time
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        product:
          $ref: '#/components/schemas/Product'
        tenders:
          type: array
          description: >-
            An array of tenders used to pay for the transaction. This is used if
            payment is tendered at the point of sale. A Tender differs from a
            PaymentMethod in that the former represents a payment that has
            already been collected at the point of sale, whereas the latter
            represents a payment that still needs to be collected from a third
            party.
          items:
            $ref: '#/components/schemas/Tender'
        paymentMethods:
          type: array
          description: >-
            An array of payment methods to be used as payment for the
            transaction. This is used if payment is not tendered at the point of
            sale, but is effected through one or more calls to third party
            payment providers as part of the request. A PaymentMethod differs
            from a Tender in that the former represents payment that still needs
            to be collected from a third party, whereas the latter represents
            payment that has already been collected at the point of sale.
          items:
            $ref: '#/components/schemas/PaymentMethod'
      description: Information about the voucher provision request.
    VoucherResponse:
      type: object
      required:
        - client
        - id
        - originator
        - thirdPartyIdentifiers
        - time
        - voucher
      properties:
        transactionLabels:
          type: array
          description: >-
            A list containing labels that can be used to discover this
            transaction or group it with other transactions sharing labels with
            the same label name and value. Transaction labels should never be
            used to make transaction processing decisions.
          items:
            $ref: '#/components/schemas/TransactionLabel'
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this transaction, as defined
            for a variant 4 UUID in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          format: date-time
          description: >-
            The date and time of the message as recorded by the sender. The
            format shall be as defined for date-time in [RFC 3339 section
            5.6](https://tools.ietf.org/html/rfc3339#section-5.6). It is
            recommended that the optional time-secfrac be included up to
            millisecond precision
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which each identify the transaction within
            each entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
          description: >-
            Used to group multiple transactions which would otherwise be
            considered independent.
        tranType:
          type: string
          description: >-
            Data relating to the type of transaction taking place (i.e. cash
            withdrawal, goods and services etc.).
          enum:
            - GOODS_AND_SERVICES
            - CASH_WITHDRAWAL
            - DEBIT_ADJUSTMENT
            - GOODS_AND_SERVICES_WITH_CASH_BACK
            - NON_CASH
            - RETURNS
            - DEPOSIT
            - CREDIT_ADJUSTMENT
            - GENERAL_CREDIT
            - AVAILABLE_FUNDS_INQUIRY
            - BALANCE_INQUIRY
            - GENERAL_INQUIRY
            - CARD_VERIFICATION_INQUIRY
            - CARDHOLDER_ACCOUNTS_TRANSFER
            - GENERAL_TRANSFER
            - PAYMENT_FROM_ACCOUNT
            - GENERAL_PAYMENT
            - PAYMENT_TO_ACCOUNT
            - PAYMENT_FROM_ACCOUNT_TO_ACCOUNT
            - PLACE_HOLD_ON_CARD
            - GENERAL_ADMIN
            - CHANGE_PIN
            - CARD_HOLDER_INQUIRY
            - POINTS_INQUIRY
        srcAccType:
          type: string
          description: >-
            This specifies the type of source account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          description: >-
            This specifies the type of destination account being used in the
            transaction (i.e. cheque, savings).
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
        rrn:
          type: string
          description: This is a reference set by the original source of the transaction.
        amounts:
          $ref: '#/components/schemas/Amounts'
        responseProduct:
          $ref: '#/components/schemas/Product'
        voucher:
          $ref: '#/components/schemas/Voucher'
      description: Information about the voucher provisioned.
    WalletPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          required:
            - walletId
          properties:
            walletId:
              type: string
              description: The unique identifier of the wallet account making the payment.
              readOnly: true
            walletPocket:
              $ref: '#/components/schemas/WalletPocket'
          description: Model for mobile wallet payments
    WalletPocket:
      type: object
      required:
        - pocketName
      properties:
        pocketName:
          type: string
          description: The name given to this wallet pocket.
        pocketId:
          type: string
          description: >-
            A programmatic ID that can be used to identify this pocket when the
            name is not enough
