Swagger

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

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

Swagger Definition

---
swagger: "2.0"
info:
  description: "Electrum QR Payment Retailer Interface."
  version: "1.0.0"
  title: "Electrum QR Payment Retailer 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:
  /qrCodes:
    post:
      summary: "Request a QR Code to display to allow the initiation of a payment."
      description: "Requests a QR code to be generated for display to a customer allowing a scan and payment to be effected.`
      in cases where a scan is not possible."
      operationId: "getQrCode"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "A get QR code request"
          required: true
          schema:
            $ref: "#/definitions/GetQrCodeRequest"
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/GetQrCodeResponse"
        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:
    post:
      summary: "Tender via QR code."
      description: "A request to tender via QR code has been made by a customer and subsequently a QR code was issued and displayed by the merchant. This operation
     requests a payment be authorised by the partner and linked to said QR code. This call should be made only after the QR code has been successfully displayed to the customer."
      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 their 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: []


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

definitions:
  GetQrCodeRequest:
    type: "object"
    required:
      - "id"
      - "originator"
      - "time"
      - "rrn"
    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"


  GetQrCodeResponse:
    type: "object"
    required:
      - "id"
      - "originator"
      - "time"
      - "rrn"
      - "qrCode"
      - "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"
      amounts:
        description: "The amount to be tendered."
        $ref: "#/definitions/LedgerAmount"
      qrCode:
        type: "string"
        description: "A QR code as described in the Advanced Topics section."
      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."

  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."

  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"

  ConfirmationAdvice:
    type: "object"
    required:
      - "id"
      - "requestId"
      - "time"
      - "rrn"
      - "partner"
    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."
      partner:
        description: "Data relating to the entity which processed the tender request as returned in the PaymentResponse."
        $ref: "#/definitions/Institution"
    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."
      partner:
        description: "Data relating to the entity which processed the tender request as returned in the PaymentResponse."
        $ref: "#/definitions/Institution"
    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."

  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"