-----
swagger: "2.0"
info:
  description: "Electrum QR Payment Partner Service Interface."
  version: "1.0.0"
  title: "Electrum QR Payment Partner Service Interface"
  contact:
    name: "Electrum Support"
    url: "http://io.electrum"
    email: "support@electrum.co.za"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "--"
basePath: "/qr/v1"
schemes:
  - "https"
paths:
  /payments:
    post:
      summary: "Process a payment for a QR code scan."
      description: "A merchant has displayed a QR code which was subsequently scanned by your application. A notification of a successful scan has
      been successfully linked to a payment request from a Merchant and thus a request to authorise said payment is being made."
      operationId: "paymentRequest"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "A payment request"
          required: true
          schema:
            $ref: "#/definitions/PaymentRequest"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/PaymentResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
        - httpBasic: []

  /payments/{paymentId}/confirmations/{adviceId}:
    post:
      summary: "Confirm completion of tender initiated by a payment request."
      description: "Confirm that the payment previously authorised has now been completed by the merchant and the customer has left with the goods."
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: "adviceId"
          in: "path"
          description: "The randomly generated UUID of this request"
          required: true
          type: "string"
        - name: "paymentId"
          in: "path"
          description: "The UUID generated for the original paymentRequest request"
          required: true
          type: "string"
        - in: "body"
          name: "body"
          description: "A payment confirmation"
          required: true
          schema:
            $ref: "#/definitions/ConfirmationAdvice"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/AdviceResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
        - httpBasic: []

  /payments/{paymentId}/reversals/{adviceId}:
    post:
      summary: "Reverse a payment request that failed or timed out"
      description: "Reverse a previous payment previously authorised. This tender was not used by the merchant and the funds reserved should be released."
      operationId: "reversePayment"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: "adviceId"
          in: "path"
          description: "The randomly generated UUID of this request"
          required: true
          type: "string"
        - name: "paymentId"
          in: "path"
          description: "The UUID generated for the original paymentRequest request"
          required: true
          type: "string"
        - in: "body"
          name: "body"
          description: "A payment reversal"
          required: true
          schema:
            $ref: "#/definitions/ReversalAdvice"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/AdviceResponse"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
        - httpBasic: []

  /scanNotifications:
    post:
      summary: "Notification of a QR scan."
      description: "Notify the system of the scan by your application of a QR code. Information in this notification will be used to
      subsequently submit a payment to you for authorisation."
      operationId: "scanNotification"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Notification that a customer has scanned a QR code to effect tender."
          required: true
          schema:
            $ref: "#/definitions/ScanNotification"
      responses:
        201:
          description: "Success"
        400:
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        501:
          description: "Not implemented"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
        - httpBasic: []

securityDefinitions:
  httpBasic:
    description: "All requests require HTTP basic authentication."
    type: "basic"

definitions:
  PaymentRequest:
    type: "object"
    required:
      - "id"
      - "originator"
      - "time"
      - "rrn"
      - "amount"
      - "tranId"
    properties:
      id:
        type: "string"
        description: "The randomly generated UUID identifying this transaction, as\
          \ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
      time:
        type: "string"
        format: "date-time"
        description: "The date and time of the message as recorded by the sender.\
          \ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
          \ It is recommended that the optional time-secfrac be included up to millisecond\
          \ precision"
      originator:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      rrn:
        type: "string"
        description: "The retrieval reference number for this transaction set by the sender."
      amount:
        description: "The amount to be tendered."
        $ref: "#/definitions/LedgerAmount"
      tranId:
        type: "string"
        description: "The unique transaction identifier related to this transaction. This transaction identifier is encoded within the QR Code and is to be used to associate the scan and the payment request."
      partnerToken:
        type: "string"
        description: "A payment token received from the Partner in the ScanNotification."

  PaymentResponse:
    type: "object"
    required:
      - "id"
      - "originator"
      - "time"
      - "rrn"
      - "amount"
      - "tranId"
      - "partner"
    properties:
      id:
        type: "string"
        description: "The randomly generated UUID identifying this transaction, as\
          \ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
      time:
        type: "string"
        format: "date-time"
        description: "The date and time of the message as recorded by the sender.\
          \ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
          \ It is recommended that the optional time-secfrac be included up to millisecond\
          \ precision"
      originator:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      rrn:
        type: "string"
        description: "The retrieval reference number for this transaction set by the sender."
      amount:
        description: "The amount to be tendered."
        $ref: "#/definitions/LedgerAmount"
      tranId:
        type: "string"
        description: "The unique transaction identifier related to this transaction. This transaction identifier is encoded within the QR Code and is to be used to associate the scan and the payment request.."
      partner:
        description: "Data relating to the entity which processed the tender request."
        $ref: "#/definitions/Institution"
      partnerToken:
        type: "string"
        description: "A token received from the partner in the ScanNotification to be used to effect payment."

  ConfirmationAdvice:
    type: "object"
    required:
      - "id"
      - "requestId"
      - "time"
      - "rrn"
    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"
      rrn:
        type: "string"
        description: "The retrieval reference number for this transaction set by the sender in the PaymentRequest."
    description: "The data required in all advice messages"

  ReversalAdvice:
    type: "object"
    required:
      - "id"
      - "requestId"
      - "reversalReason"
      - "time"
      - "rrn"
    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"
      reversalReason:
        type: "string"
        description: "The reason for the reversal"
        enum:
          - "TIMEOUT"
          - "CANCELLED"
          - "RESPONSE_NOT_FINAL"
      rrn:
        type: "string"
        description: "The retrieval reference number for this transaction set by the sender in the payment request."
    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"

  AdviceResponse:
    type: "object"
    required:
      - "id"
      - "requestId"
      - "time"
      - "rrn"
    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"
      rrn:
        type: "string"
        description: "The retrieval reference number for this transaction set by the sender in the payment request."
    description: "Basic advice response information."

  ScanNotification:
    type: "object"
    required:
      - "id"
      - "time"
      - "partner"
      - "tranId"
    properties:
      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"
      rrn:
        type: "string"
        description: "The retrieval reference number for this transaction set by the sender."
      amount:
        description: "The amount to be tendered."
        $ref: "#/definitions/LedgerAmount"
      partner:
        description: "Data detailing to the entity which will process the tender request. This will be used to route any payment authorisations linked to this scan."
        $ref: "#/definitions/Institution"
      tranId:
        type: "string"
        description: "The unique transaction identifier related to this transaction. This is the transaction identifier taken from the QR code once scanned."
      partnerToken:
        type: "string"
        description: "A token to be submitted in any subsequent payment authorisation requests."

  ErrorDetail:
    type: "object"
    required:
      - "errorMessage"
      - "errorType"
      - "id"
      - "requestType"
    properties:
      errorType:
        type: "string"
        description: "The type of error that occurred"
        enum:
          - "GENERAL_ERROR"
      errorMessage:
        type: "string"
        description: "A short description of the error"
        minLength: 0
        maxLength: 20
      id:
        type: "string"
        description: "The UUID of the message for which error occurred."
      originalId:
        type: "string"
        description: "The UUID of the original request message in the case of an error\
          \ occurring for an advice message."
      detailMessage:
        type: "object"
        description: "A free form detailed description of a particular failure condition\
          \ may optionally be supplied"
    description: "Represents the outcome of a completed transaction"
  Institution:
    type: "object"
    required:
      - "id"
      - "name"
    properties:
      id:
        type: "string"
        description: "The institution's id as assigned by Electrum"
        pattern: "[0-9]{1,11}"
      name:
        type: "string"
        description: "The institutions's name"
        minLength: 0
        maxLength: 40
    description: "Originating, acquiring, processing, or receiving institution details"
  Merchant:
    type: "object"
    required:
      - "merchantId"
      - "merchantName"
      - "merchantType"
    properties:
      merchantType:
        type: "string"
        description: "The assigned four digit merchant category code"
        pattern: "[0-9]{4}"
      merchantId:
        type: "string"
        description: "The assigned merchant identifier. Also known as card acceptor\
          \ id"
        minLength: 15
        maxLength: 15
      merchantName:
        description: "The name of a merchant"
        $ref: "#/definitions/MerchantName"
    description: "Merchant related data. Must be included if available"
  MerchantName:
    type: "object"
    required:
      - "city"
      - "country"
      - "name"
      - "region"
    properties:
      name:
        type: "string"
        description: "The merchant or trading as name associated with the merchant"
        minLength: 0
        maxLength: 23
      city:
        type: "string"
        description: "The city where the merchant is located"
        minLength: 0
        maxLength: 13
      region:
        type: "string"
        description: "The state or region where the merchant is located"
        minLength: 0
        maxLength: 2
      country:
        type: "string"
        description: "The country where the merchant is located"
        minLength: 0
        maxLength: 2
    description: "A container object representing the Merchant Name and Location"
  Originator:
    type: "object"
    required:
      - "institution"
      - "merchant"
      - "terminalId"
    properties:
      institution:
        description: "The institution originating the request, as issued by Electrum"
        $ref: "#/definitions/Institution"
      terminalId:
        type: "string"
        description: "The ID that uniquely identifies each device or system in an\
          \ originator's institution capable of sending requests. Required for transactions\
          \ initiated from physical card entry or point-of-sale devices"
        minLength: 8
        maxLength: 8
      merchant:
        description: "Merchant data. Required if available"
        $ref: "#/definitions/Merchant"
    description: "The Originator object encapsulates data relating to the originator\
      \ of the transaction"
  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"