openapi: 3.0.1
info:
  title: QR Payment Service Interface
  description: >-
    The Electrum QR Payment Service describes an interface for supporting
    payments via scanning of a QR code transactions.
  contact:
    name: Electrum Support
    url: https://electrum.io
    email: support@electrum.co.za
  version: 2.1.0
security:
  - httpBasic: []
paths:
  /payments/confirmations:
    post:
      summary: Confirms completion of tender initiated by a payment request.
      description: >-
        This operation confirms that a QR payment transaction has completed
        successfully between the consumer and the merchant. Such a transaction
        may be settled between the merchant and the Partner that processed the
        payment. Such a transaction cannot be reversed.
      operationId: confirmPayment
      requestBody:
        description: A QR payment confirmation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentConfirmation'
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentConfirmation'
        '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'
  /payments:
    post:
      summary: Requests a payment to be processed via a QR Partner.
      description: >-
        This request contains conventional payment information (POS information,
        transaction amount, date etc.) as well as Partner information. If a
        merchant is unable to supply the Partner information in this request,
        then the request is directed to an intermediate system which also
        receives notifications from Partners of QR scans. This intermediate
        system will match the payment request from the merchant with the scan
        notification from the Partner using the QR code information common to
        both messages. The payment request may then be forwarded to the correct
        Partner for processing.
      operationId: pay
      requestBody:
        description: A QR payment request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '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'
  /payments/reversals:
    post:
      summary: Reverses a payment request that failed or timed out
      description: >-
        This operation indicates that the sale did not complete and the payment
        should be reversed if it took place. Once a payment is reversed it
        cannot be confirmed and need not be settled between the merchant and the
        QR Partner.
      operationId: reversePayment
      requestBody:
        description: A QR payment reversal.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentReversal'
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReversal'
        '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'
  /qrCodes:
    post:
      summary: Requests a QR Code to display to a customer to be scanned.
      description: >-
        The customer may scan this code with a Partner's application and thereby
        allow the Partner to identify the QR code provider.
      operationId: createQrCode
      requestBody:
        description: >-
          Information pertaining to the QR code, which may be available at the
          time of the request. This may include details such as the entity
          requesting the QR code, the value of the transaction for which the QR
          code will be used and the specific purpose of the QR code. The request
          for a QR code should convey information about the merchant requesting
          the QR code (e.g. POS information) and not information about the
          consumer who will scan the QR code (e.g. customer or loyalty
          information).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQrCodeRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateQrCodeResponse'
        '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'
  /scans:
    post:
      summary: Notify that a QR code has been scanned.
      description: >-
        Partners are not notified by a QR code provider when a QR code is
        generated. Only when a consumer scans a QR code using a Partner's
        application is the Partner aware that the QR code is available. The
        Partner subsequently informs the provider of the QR code that their code
        has been scanned. The QR code provider shall then associate any other
        transactions pertaining to the QR code with the Partner.
      operationId: notifyScan
      requestBody:
        description: A get QR code request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanNotification'
        required: true
      responses:
        '202':
          description: Accepted
        '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'
components:
  schemas:
    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
          additionalProperties:
            $ref: '#/components/schemas/LedgerAmount'
      description: The amounts pertaining to the QR code which was scanned.
      nullable: true
    Institution:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      description: >-
        Data relating to the entity which ultimately processes the request. A
        Partner may provide this information if known at the time the QR code
        was scanned.
    LedgerAmount:
      required:
        - amount
        - currency
      type: object
      properties:
        amount:
          type: integer
          format: int64
        currency:
          pattern: '[0-9]{3}'
          type: string
        ledgerIndicator:
          type: string
          enum:
            - DEBIT
            - CREDIT
    PaymentConfirmation:
      required:
        - id
        - requestId
        - thirdPartyIdentifiers
        - time
      type: object
      properties:
        id:
          type: string
        requestId:
          type: string
        time:
          type: string
          format: date-time
        thirdPartyIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
        rrn:
          type: string
        amounts:
          $ref: '#/components/schemas/Amounts'
        partner:
          $ref: '#/components/schemas/Institution'
        tranId:
          type: string
          description: An echo of the value in the original PaymentRequest.
          nullable: true
      description: >-
        Confirm that a previous PaymentRequest has completed successfully at the
        POS. Where possible all optional fields should be supplied to ensure
        smooth processing. If optional fields are not present then processing
        may require retrieval of the original transaction leading to unnecessary
        processing overheads.
    ThirdPartyIdentifier:
      required:
        - institutionId
      type: object
      properties:
        institutionId:
          type: string
        transactionIdentifier:
          type: string
      description: >-
        An array of identifiers which identify the transaction within each
        entity's system.
    ErrorDetail:
      required:
        - errorMessage
        - errorType
        - id
      type: object
      properties:
        errorTypeFromString:
          type: string
          writeOnly: true
        id:
          maxLength: 20
          minLength: 0
          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).
        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. This value should be used for
            programmatic handling of errors.
          enum:
            - DUPLICATE_RECORD
            - FORMAT_ERROR
            - FUNCTION_NOT_SUPPORTED
            - GENERAL_ERROR
            - INVALID_AMOUNT
            - ROUTING_ERROR
            - TRANSACTION_NOT_SUPPORTED
            - UNABLE_TO_LOCATE_RECORD
            - UPSTREAM_UNAVAILABLE
            - ACCOUNT_ALREADY_SETTLED
            - INVALID_MERCHANT
            - DO_NOT_HONOR
            - DECLINED_BY_PARTNER
            - DECLINED_BY_ACQUIRER
            - DECLINED_BY_ISSUER
            - INSUFFICIENT_FUNDS
            - INVALID_CARD_NUMBER
            - CARD_EXPIRED
            - INVALID_TRAN_ID
            - PARTNER_UNKNOWN
            - NO_SCAN_RECEIVED
            - INVALID_ACCOUNT
        errorMessage:
          maxLength: 40
          minLength: 0
          type: string
          description: >-
            A short description of the error. This value should be suitable for
            display to an operator.
        detailMessage:
          type: object
          description: >-
            A free form detailed description of a particular failure condition
            may optionally be supplied. This information is intended for
            informational purposes only when investigating the cause of a
            failure.
        providerErrorCode:
          type: string
          description: >-
            The error code returned by the service provider if available. 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 if available.
            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 if available.
        tranId:
          type: string
          description: >-
            The unique transaction identifier related to this transaction if
            available. This is the value returned in the tranId field of the
            CreateQrCodeResponse or the ScanNotification.
      description: Describes a failed outcome of an operation.
    Barcode:
      required:
        - data
      type: object
      properties:
        data:
          type: string
        encoding:
          type: string
    Merchant:
      required:
        - merchantId
        - merchantName
        - merchantType
      type: object
      properties:
        merchantType:
          pattern: '[0-9]{4}'
          type: string
        merchantId:
          type: string
        merchantName:
          $ref: '#/components/schemas/MerchantName'
    MerchantName:
      required:
        - city
        - country
        - name
        - region
      type: object
      properties:
        name:
          type: string
        city:
          type: string
        region:
          type: string
        country:
          type: string
    Originator:
      required:
        - institution
        - merchant
        - terminalId
      type: object
      properties:
        institution:
          $ref: '#/components/schemas/Institution'
        terminalId:
          type: string
        merchant:
          $ref: '#/components/schemas/Merchant'
        operatorId:
          type: string
        channelId:
          type: string
      description: Data relating to the originator of the request.
    PaymentResponse:
      required:
        - amounts
        - client
        - id
        - originator
        - partner
        - thirdPartyIdentifiers
        - time
        - tranId
      type: object
      properties:
        transactionLabels:
          type: array
          items:
            $ref: '#/components/schemas/TransactionLabel'
        id:
          type: string
        time:
          type: string
          format: date-time
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
        tranType:
          type: string
          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
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
        rrn:
          type: string
        partner:
          $ref: '#/components/schemas/Institution'
        tenders:
          type: array
          description: >-
            An array of tenders used to pay for the transaction. This may be
            used to describe the payment which was effected as a result of the
            QR code scan e.g. the card detail ultimately used for the payment.
          nullable: true
          items:
            $ref: '#/components/schemas/Tender'
        amounts:
          $ref: '#/components/schemas/Amounts'
        tranId:
          type: string
          description: This value is echoed from the PaymentRequest.
        partnerPaymentToken:
          type: string
          description: This value is echoed from the PaymentRequest.
          nullable: true
      description: The response to a successful payment with a linked QR code scan.
    SlipData:
      type: object
      properties:
        messageLines:
          type: array
          items:
            $ref: '#/components/schemas/SlipLine'
        slipWidth:
          type: integer
          format: int32
        issuerReference:
          pattern: '[A-Z0-9]{1,40}'
          type: string
    SlipLine:
      required:
        - text
      type: object
      properties:
        barcode:
          $ref: '#/components/schemas/Barcode'
        text:
          type: string
        fontWidthScaleFactor:
          type: number
          format: double
        fontHeightScaleFactor:
          type: number
          format: double
        line:
          type: boolean
        cut:
          type: boolean
    Tender:
      required:
        - amount
        - tenderType
      type: object
      properties:
        accountType:
          type: string
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - STORED_VALUE
        amount:
          $ref: '#/components/schemas/LedgerAmount'
        cardNumber:
          pattern: '[0-9]{6}[0-9*]{0,13}'
          type: string
        reference:
          type: string
        tenderType:
          type: string
          enum:
            - CASH
            - CHEQUE
            - CREDIT_CARD
            - DEBIT_CARD
            - WALLET
            - ROUNDING
            - GIFT_CARD
            - LOYALTY_CARD
            - OTHER
            - REWARD
      description: >-
        An array of tenders used to pay for the transaction. This may be used to
        describe the payment which was effected as a result of the QR code scan
        e.g. the card detail ultimately used for the payment.
      nullable: true
    TransactionLabel:
      required:
        - name
        - value
      type: object
      properties:
        name:
          pattern: ^[a-zA-Z0-9_]{1,100}$
          type: string
        value:
          pattern: ^[a-zA-Z.-9 _-]{1,100}$
          type: string
    PaymentRequest:
      required:
        - amounts
        - client
        - id
        - originator
        - thirdPartyIdentifiers
        - time
        - tranId
      type: object
      properties:
        transactionLabels:
          type: array
          items:
            $ref: '#/components/schemas/TransactionLabel'
        id:
          type: string
        time:
          type: string
          format: date-time
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        slipData:
          $ref: '#/components/schemas/SlipData'
        basketRef:
          type: string
        tranType:
          type: string
          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
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        destAccType:
          type: string
          enum:
            - DEFAULT
            - SAVINGS
            - CHEQUE
            - CREDIT
            - UNIVERSAL
            - ELECTRONIC_PURSE
            - GIFT_CARD
            - STORED_VALUE
        stan:
          type: string
        rrn:
          type: string
        partner:
          $ref: '#/components/schemas/Institution'
        amounts:
          $ref: '#/components/schemas/Amounts'
        tranId:
          type: string
          description: >-
            The unique transaction identifier related to this transaction.
            Retailers must set this to the same value as that returned in the
            tranId field of the CreateQrCodeResponse that preceded this
            PaymentRequest. Partners may associate this PaymentRequest with the
            QR code whose ScanNotification they submitted with this value.
        partnerPaymentToken:
          type: string
          description: >-
            A payment token received from the Partner in the ScanNotification. A
            Partner may provide such a value in the ScanNotification so that it
            is included in the PaymentRequest to the Partner. This field should
            be populated if known. A Partner may expect to receive this value in
            the PaymentRequest if it was provided in the ScanNotification.
          nullable: true
      description: >-
        A request to effect a payment with a linked QR code. Such requests
        originate from the Merchant's system and are typically directed to the
        Partner for processing. If the Partner for a PaymentRequest is not
        known, then the PaymentRequest may be directed to an intermediate system
        which receives ScanNotification messages from Partners. This
        intermediate system is then responsible for identifying the correct
        Partner to which a PaymentRequest should be directed.
    PaymentReversal:
      required:
        - id
        - requestId
        - reversalReason
        - thirdPartyIdentifiers
        - time
      type: object
      properties:
        id:
          type: string
        requestId:
          type: string
        time:
          type: string
          format: date-time
        thirdPartyIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        stan:
          type: string
        rrn:
          type: string
        amounts:
          $ref: '#/components/schemas/Amounts'
        reversalReason:
          type: string
          enum:
            - TIMEOUT
            - CANCELLED
            - RESPONSE_NOT_FINAL
            - REFUND
            - VOID
        partner:
          $ref: '#/components/schemas/Institution'
        tranId:
          type: string
          description: An echo of the value in the original PaymentRequest.
          nullable: true
      description: >-
        Reverse a previous PaymentRequest. This may be due to a cancellation at
        the POS or because the original PaymentRequest failed or is in an
        unknown state. Where possible all optional fields should be supplied to
        ensure smooth processing. If optional fields are not present then
        processing may require retrieval of the original transaction leading to
        unnecessary processing overheads.
    AccountPayment:
      required:
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            srcAccountId:
              type: string
            srcCustomerId:
              type: string
            destAccountId:
              type: string
            destCustomerId:
              type: string
    Address:
      type: object
      properties:
        addressLine1:
          pattern: ^.{1,100}
          type: string
        addressLine2:
          pattern: ^.{1,100}
          type: string
        city:
          pattern: ^.{1,30}
          type: string
        region:
          pattern: '[A-Z]{2}'
          type: string
        country:
          pattern: '[A-Z]{2}'
          type: string
        postalCode:
          pattern: '[A-Za-z0-9 -]{1,20}'
          type: string
    An32TokenPayment:
      required:
        - token
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            token:
              pattern: '[a-zA-Z0-9]{32}'
              type: string
    CardPayment:
      required:
        - pan
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            posInfo:
              $ref: '#/components/schemas/PosInfo'
            pan:
              pattern: '[0-9]{1,19}'
              type: string
            expiryDate:
              pattern: '[0-9]{4}'
              type: string
            threeDSecureData:
              $ref: '#/components/schemas/ThreeDSecureData'
            encryptedPin:
              $ref: '#/components/schemas/EncryptedPin'
    CreateQrCodeResponse:
      required:
        - client
        - id
        - originator
        - qrCode
        - time
        - tranId
      type: object
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this request. This may be a
            variant 3 or 4 as defined in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          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
          format: date-time
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $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'
        rrn:
          type: string
          description: This is a reference set by the original source of the request.
          nullable: true
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
          nullable: true
        amounts:
          $ref: '#/components/schemas/Amounts'
        customer:
          $ref: '#/components/schemas/Customer'
        qrProperties:
          $ref: '#/components/schemas/QrProperties'
        paymentMethods:
          type: array
          description: >-
            A list of payment methods with which the QR owner will accept
            payment. The paymentMethods specify the destination to which funds
            may be transferred when the QR code is scanned.
          items:
            $ref: '#/components/schemas/PaymentMethod'
        tranId:
          type: string
          description: >-
            The unique transaction identifier assigned by the QR code provider
            to this QR code. This value is also encoded in the QR code returned
            in the qrCode field. The QR code provider is responsible for
            ensuring appropriate uniqueness of the QR code for the appropriate
            period of time. No specific restrictions are placed on the format of
            the QR code (length, characters etc.) but implementors should
            consider the following aspects; ***Length*** - Longer QR codes
            require more detailed resolution on display screens and scanning
            devices and are also harder to scan. ***Manual Entry*** - While
            manual entry of QR codes is not explicitly supported by the QR
            Payments Service Interface, implementors may choose to support such
            fallback mechanisms if a QR code cannot be scanned. Longer and more
            complicated codes will be more susceptible to errors when inputted
            manually. This value must be provided in subsequent 'notifyScan' and
            'pay' operations to link payments to specific Partners.
        qrCode:
          type: string
          description: >-
            The full set of data to be encoded in the graphical QR code. The
            data is provided in a Tag-Length-Value format as described in the
            EMVCo specification but is not a fully EMVCo compliant string e.g.
            Tags which are mandatory under the EMVCo specification may be
            omitted. The precise set of Tags to be populated in the QR code
            should be discussed and agreed upon by implementation partners.
      description: >-
        The response to a CreateQrCodeRequest which contains the specific code
        assigned by the QR code provider as well as the full QR code in EMVCo
        format.
    Customer:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        address:
          type: string
        dateOfBirth:
          type: string
          format: date-time
        status:
          type: string
        msisdn:
          pattern: ^\+?[1-9]\d{0,14}
          type: string
        emailAddress:
          type: string
        addressDetails:
          $ref: '#/components/schemas/Address'
        profileId:
          type: string
      description: Information detail pertaining to the customer.
      nullable: true
    CustomerProvidedValuePrompt:
      type: object
      properties:
        label:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Label that will be displayed as prompt for the customer-provided
            value. This value should also uniquely identify the prompt and its
            associated value once captured.
      description: >-
        Properties of a prompt that can be displayed on a customer's scanning
        application to capture a user-provided text value which can be used when
        performing actions associated with the data embedded in this QR code.
    EncryptedPin:
      required:
        - pinBlock
      type: object
      properties:
        pinBlock:
          pattern: '[a-fA-F0-9]{16}|[a-fA-F0-9]{32}'
          type: string
        encryptionParameters:
          $ref: '#/components/schemas/EncryptionParameters'
    EncryptionParameters:
      required:
        - accountNumber
      type: object
      properties:
        pinBlockFormat:
          type: string
          default: ISO_9564_FORMAT_0
          enum:
            - ISO_9564_FORMAT_0
            - ISO_9564_FORMAT_1
            - ISO_9564_FORMAT_3
            - ISO_9564_FORMAT_4
        accountNumber:
          pattern: '[0-9]{12}'
          type: string
        keyIndex:
          type: integer
          format: int32
    HashedPinParameters:
      required:
        - name
      type: object
      properties:
        name:
          type: string
    LoyaltyCardPayment:
      required:
        - cardNumber
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            cardNumber:
              pattern: '[0-9]{16}'
              type: string
    NotificationParameters:
      type: object
      properties:
        recipients:
          type: array
          description: >-
            A list of entities that should receive notifications based on the
            use of a QR code.
          items:
            $ref: '#/components/schemas/NotificationRecipient'
      description: >-
        Some integrations that make use of this interface may support notifying
        recipients when QR data has been used to perform some action. For
        example, a recipient may receive a notification if a customer
        successfully makes a payment by scanning a QR code. This property
        contains details describing notifications that may be triggered by using
        this QR code. Note that this data may be omitted in lookup operation
        responses, as this data may be considered sensitive.
    NotificationRecipient:
      type: object
      properties:
        emailAddress:
          type: string
          description: >-
            An email address where a recipient should receive a notification
            based on use of a QR code.
        msisdn:
          pattern: ^\+?[1-9][0-9]{1,14}
          type: string
          description: >-
            An MSISDN where a recipient should receive a notification based on
            use of a QR code. 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.
      description: >-
        An entity that should receive notifications based on the use of a QR
        code. This model collects details about how to contact the recipient.
    PaymentMethod:
      required:
        - type
      type: object
      properties:
        type:
          type: string
          enum:
            - AN_32_TOKEN
            - LOYALTY_CARD
            - CARD
            - ACCOUNT
            - REWARD
            - WALLET
            - QR
        name:
          type: string
        amount:
          $ref: '#/components/schemas/LedgerAmount'
        issuer:
          $ref: '#/components/schemas/Institution'
        pin:
          $ref: '#/components/schemas/Pin'
        proxy:
          maxLength: 40
          minLength: 0
          type: string
        proxyType:
          type: string
          enum:
            - MSISDN
            - EMAIL
            - UNKNOWN
      description: >-
        A list of payment methods with which the QR owner will accept payment.
        The paymentMethods specify the destination to which funds may be
        transferred when the QR code is scanned.
      discriminator:
        propertyName: type
    Pin:
      required:
        - type
      type: object
      properties:
        type:
          type: string
          enum:
            - CLEAR_PIN
            - ENCRYPTED_PIN
            - HASHED_PIN
      discriminator:
        propertyName: type
    PinClear:
      required:
        - pin
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          properties:
            pin:
              pattern: .{0,20}
              type: string
    PinEncrypted:
      required:
        - pinBlock
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          properties:
            pinBlock:
              pattern: '[a-fA-F0-9]{16}|[a-fA-F0-9]{32}'
              type: string
            encryptionParameters:
              $ref: '#/components/schemas/EncryptionParameters'
    PinHashed:
      required:
        - hash
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/Pin'
        - type: object
          properties:
            hash:
              pattern: '[0-9,A-F]{1,512}'
              type: string
            hashedPinParameters:
              $ref: '#/components/schemas/HashedPinParameters'
    PosEntryMode:
      required:
        - panEntryMode
        - pinEntryCapability
      type: object
      properties:
        panEntryMode:
          type: string
          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
          enum:
            - UNKNOWN
            - CAN_ACCEPT
            - CANNOT_ACCEPT
    PosInfo:
      type: object
      properties:
        entryMode:
          $ref: '#/components/schemas/PosEntryMode'
        posConditionCode:
          type: string
          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
    QrPayment:
      required:
        - tranId
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            tranId:
              type: string
            partnerPaymentToken:
              type: string
    QrProperties:
      type: object
      properties:
        description:
          maxLength: 20
          minLength: 0
          type: string
          description: >-
            The description field is intended to be displayed to the person
            scanning the QR code to provide them with context for the QR and why
            it was created.
        guid:
          type: string
          description: >-
            The value which, when embedded in an EMVCo QR code, identifies the
            provider of the QR code.
        overPaymentAllowed:
          type: boolean
          description: >-
            Indicates whether or not the transaction against the QR may use an
            amount greater than the value in the `amount` field.
        partPaymentAllowed:
          type: boolean
          description: >-
            Indicates whether or not the transaction against the QR may use an
            amount less than the value in the `amount` field.
        customerProvidedValuePrompts:
          type: array
          description: >-
            Details for prompts that can be displayed to the customer by a
            scanning application. These prompts can be used to signal that the
            user can input their own custom text values when scanning a QR code.
            These values may then be used as part of the action that is
            initiated by scanning the code.
          items:
            $ref: '#/components/schemas/CustomerProvidedValuePrompt'
        requestTip:
          type: boolean
          description: >-
            When a QR code is used for facilitating payment, this option can be
            used to indicate that a prompt for a separate tip amount should be
            displayed by the customer's scanning application. This value is not
            required, so when this property is not specified, this value should
            be treated as `false`.
        creationDateTime:
          type: string
          description: >-
            The date and time at which the QR code was created. 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
          format: date-time
        expiryDate:
          type: string
          description: >-
            The date and time at which the QR code expires at which point it may
            no longer be used to facilitate transactions. 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
          format: date-time
        notificationParameters:
          $ref: '#/components/schemas/NotificationParameters'
        qrLabel:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            This value can be used as an alternative means of referencing a QR
            code. It supports a potentially human-readable way to reference a QR
            code that may be easily recognised by the owner or users of the
            code.
      description: >-
        A collection of attributes that describe how a QR code is intended to be
        used for transacting.
    RewardPayment:
      required:
        - rewardCode
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            rewardCode:
              maxLength: 40
              minLength: 0
              type: string
    ThreeDSecureData:
      required:
        - version
      type: object
      properties:
        authenticationValue:
          type: string
        cardHolderAuthVerificationResult:
          type: string
          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
          enum:
            - V1
            - V2
        eci:
          type: string
          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
          enum:
            - 'Y'
            - 'N'
            - U
            - A
            - C
            - D
            - R
            - I
            - S
      discriminator:
        propertyName: version
    ThreeDSecureDataV1:
      required:
        - version
      type: object
      allOf:
        - $ref: '#/components/schemas/ThreeDSecureData'
        - type: object
          properties:
            transactionId:
              type: string
    ThreeDSecureDataV2:
      required:
        - version
      type: object
      allOf:
        - $ref: '#/components/schemas/ThreeDSecureData'
        - type: object
          properties:
            transactionId:
              type: string
              format: uuid
    WalletPayment:
      required:
        - type
        - walletId
      type: object
      allOf:
        - $ref: '#/components/schemas/PaymentMethod'
        - type: object
          properties:
            walletId:
              type: string
            walletPocket:
              $ref: '#/components/schemas/WalletPocket'
    WalletPocket:
      required:
        - pocketName
      type: object
      properties:
        pocketName:
          type: string
        pocketId:
          type: string
    CreateQrCodeRequest:
      required:
        - client
        - id
        - originator
        - time
      type: object
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this request. This may be a
            variant 3 or 4 as defined in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          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
          format: date-time
        originator:
          $ref: '#/components/schemas/Originator'
        client:
          $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'
        rrn:
          type: string
          description: This is a reference set by the original source of the request.
          nullable: true
        stan:
          type: string
          description: >-
            The System Trace Audit Number can be used to locate transactions
            across different systems.
          nullable: true
        amounts:
          $ref: '#/components/schemas/Amounts'
        customer:
          $ref: '#/components/schemas/Customer'
        qrProperties:
          $ref: '#/components/schemas/QrProperties'
        paymentMethods:
          type: array
          description: >-
            A list of payment methods with which the QR owner will accept
            payment. The paymentMethods specify the destination to which funds
            may be transferred when the QR code is scanned.
          items:
            $ref: '#/components/schemas/PaymentMethod'
      description: >-
        A request from the merchant for a QR code to be generated. The QR code
        returned should be suitable to be displayed to a consumer to be scanned.
    ScanNotification:
      required:
        - id
        - partner
        - time
        - tranId
      type: object
      properties:
        id:
          type: string
          description: >-
            The randomly generated UUID identifying this notification. This may
            be a variant 3 or 4 as defined in [RFC
            4122](https://tools.ietf.org/html/rfc4122)
        time:
          type: string
          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
          format: date-time
        partner:
          $ref: '#/components/schemas/Institution'
        settlementEntity:
          $ref: '#/components/schemas/Institution'
        receiver:
          $ref: '#/components/schemas/Institution'
        thirdPartyIdentifiers:
          type: array
          description: >-
            An array of identifiers which identify the transaction within each
            entity's system.
          items:
            $ref: '#/components/schemas/ThirdPartyIdentifier'
        amounts:
          $ref: '#/components/schemas/Amounts'
        tranId:
          type: string
          description: >-
            The transaction identifier encoded within the QR Code which was
            scanned. Any PaymentRequest with a matching tranId value should be
            forwarded to the Partner for processing.
        partnerPaymentToken:
          type: string
          description: >-
            A payment token received from the partner in the ScanNotification.
            If supplied by the Partner then it will be echoed in the
            PaymentRequest to the Partner.
          nullable: true
      description: >-
        A notification sent by the Partner indicating that the Partner received
        a scan of the QR code linked to the transaction ID. Any PaymentRequest
        with a matching tranId value should be forwarded to the Partner for
        processing.
  securitySchemes:
    httpBasic:
      type: http
      scheme: basic
