Swagger

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

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

Swagger definition

---
swagger: "2.0"
info:
  description: "The Electrum Airtime Service describes an interface for airtime
\
    \                  transactions."
  version: "5.12.0"
  title: "Airtime 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: "sandbox.electrum.io"
basePath: "/airtime/v5"
schemes:
- "https"
paths:
  /msisdn:
    get:
      summary: "Looks up information associated with the given Msisdn. This includes\
        \ such information as available products and promotions, operator information\
        \ etc."
      description: ""
      operationId: "lookupMsisdn"
      produces:
      - "application/json"
      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
        type: "string"
      - name: "operator"
        in: "query"
        description: "The provider who processed the original purchase attempt."
        required: false
        type: "string"
      responses:
        200:
          description: "Accepted"
          schema:
            $ref: "#/definitions/MsisdnInfoResponse"
        400:
          description: "Bad Request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not Found"
        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: []
  /purchases:
    post:
      summary: "Purchase an airtime product."
      description: "Requests an airtime product from the provider."
      operationId: "purchase"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "An airtime request."
        required: true
        schema:
          $ref: "#/definitions/PurchaseRequest"
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/PurchaseResponse"
        400:
          description: "Bad Request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
      - httpBasic: []
  /purchases/confirmations:
    post:
      summary: "Confirm that a previous purchase operation has completed successfully\
        \ at the POS."
      description: "Once a consumer has paid for an airtime product the merchant must\
        \ notify the vendor that the transactioncompleted successfully at the POS.\
        \ confirmPurchase must be repeated until a final HTTP status code isreceived\
        \ (i.e. not 500 or 504). confirmPurchase may be called repeatedly without\
        \ negative effect."
      operationId: "purchaseConfirmation"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "A purchase confirmation."
        required: true
        schema:
          $ref: "#/definitions/PurchaseConfirmation"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/PurchaseConfirmation"
        400:
          description: "Bad Request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not Found"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
      - httpBasic: []
  /purchases/reversals:
    post:
      summary: "Reverse an airtime purchase request that failed or timed out."
      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. purchaseReversal\
        \ must be repeated until a final HTTP status code is received (i.e. not 500\
        \ or 504). purchaseReversal may be called repeatedly on the same airtime purchase\
        \ resource without negative effect. If the airtime provider does not support\
        \ the reversal operation, please refer to the purchaseStatus operation."
      operationId: "purchaseReversal"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "An airtime purchase reversal."
        required: true
        schema:
          $ref: "#/definitions/PurchaseReversal"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/PurchaseReversal"
        400:
          description: "Bad Request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not Found"
        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: []
  /purchases/status:
    get:
      summary: "Looks up the status of a prior airtime purchase at the specified provider.\
        \ 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."
      description: ""
      operationId: "purchaseStatus"
      produces:
      - "application/json"
      parameters:
      - name: "provider"
        in: "query"
        description: "The provider who processed the original purchase attempt. Conditionally\
          \ required if purchaseRef is supplied."
        required: false
        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
        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
        type: "string"
      responses:
        200:
          description: "Accepted"
          schema:
            $ref: "#/definitions/PurchaseResponse"
        400:
          description: "Bad Request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not Found"
        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: []
  /vouchers/{requestId}:
    post:
      summary: "Request a voucher be provisioned."
      description: "Requests a voucher from the voucher vendor."
      operationId: "provisionVoucher"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "requestId"
        in: "path"
        description: "The randomly generated UUID of this request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A voucher request."
        required: true
        schema:
          $ref: "#/definitions/VoucherRequest"
      responses:
        201:
          description: "Created"
          schema:
            $ref: "#/definitions/VoucherResponse"
          headers:
            Location:
              type: "string"
              description: "The location of the created voucher resource"
        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: []
  /vouchers/{requestId}/confirmations/{confirmationId}:
    post:
      summary: "Confirm a voucher provision request that completed successfully."
      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.\
        \ confirmVoucher must be repeated until a final HTTP status code is received\
        \ (i.e. not 500 or 504). confirmVoucher may be called repeatedly on the same\
        \ voucher resource without negative effect."
      operationId: "confirmVoucher"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "requestId"
        in: "path"
        description: "The UUID generated for the original voucher provision request."
        required: true
        type: "string"
      - name: "confirmationId"
        in: "path"
        description: "The randomly generated UUID of this request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A voucher provision confirmation."
        required: true
        schema:
          $ref: "#/definitions/VoucherConfirmation"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/BasicAdvice"
        400:
          description: "Bad Request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not Found"
          schema:
            $ref: "#/definitions/ErrorDetail"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/ErrorDetail"
        503:
          description: "Service Unavailable"
          schema:
            $ref: "#/definitions/ErrorDetail"
        504:
          description: "Gateway Timeout"
          schema:
            $ref: "#/definitions/ErrorDetail"
      security:
      - httpBasic: []
  /vouchers/{requestId}/reversals/{reversalId}:
    post:
      summary: "Reverse a voucher provision request that failed or timed out."
      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. reverseVoucher must be repeated until a final HTTP status\
        \ code is received (i.e. not 500 or 504). reverseVoucher may be called repeatedly\
        \ on the same voucher resource without negative effect."
      operationId: "reverseVoucher"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "requestId"
        in: "path"
        description: "The UUID generated for the original voucher provision request."
        required: true
        type: "string"
      - name: "reversalId"
        in: "path"
        description: "The randomly generated UUID of this request."
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "A voucher provision reversal."
        required: true
        schema:
          $ref: "#/definitions/BasicReversal"
      responses:
        202:
          description: "Accepted"
          schema:
            $ref: "#/definitions/BasicAdvice"
        400:
          description: "Bad Request"
          schema:
            $ref: "#/definitions/ErrorDetail"
        404:
          description: "Not Found"
        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, where user name\
      \ equals
                    the value used in
                    Originator.Institution.id\
      \ and password has been agreed with Electrum."
    type: "basic"
definitions:
  Amounts:
    type: "object"
    properties:
      requestAmount:
        description: "The transaction amount requested by the customer to be authorised\
          \ or approved. This is the total amount the customer wishes to pay for a\
          \ service or virtual product."
        $ref: "#/definitions/LedgerAmount"
      approvedAmount:
        description: "The transaction amount which was approved by the upstream entity."
        $ref: "#/definitions/LedgerAmount"
      feeAmount:
        description: "Fees charged by the upstream entity for processing the transaction."
        $ref: "#/definitions/LedgerAmount"
      balanceAmount:
        description: "The remaining balance on the customer's account."
        $ref: "#/definitions/LedgerAmount"
      additionalAmounts:
        type: "object"
        description: "Any additional amounts that are involved in a transaction which\
          \ don't appropriately fit into the other amount fields."
        additionalProperties:
          $ref: "#/definitions/LedgerAmount"
    description: "Amounts which make up the transaction. Absent amounts have zero\
      \ value."
  An32TokenPayment:
    allOf:
    - $ref: "#/definitions/PaymentMethod"
    - type: "object"
      required:
      - "token"
      properties:
        token:
          type: "string"
          description: "32 character alphanumeric code which identifies a token"
          pattern: "[a-zA-Z0-9]{32}"
      description: "Model for token-based payments"
  Barcode:
    type: "object"
    required:
    - "data"
    - "encoding"
    properties:
      data:
        type: "string"
        description: "Data to be encoded in the barcode"
      encoding:
        type: "string"
        description: "Specifies the encoding used in the barcode"
    description: "Used to indicate barcode information for a slip line."
  BasicAdvice:
    type: "object"
    required:
    - "id"
    - "requestId"
    - "thirdPartyIdentifiers"
    - "time"
    properties:
      id:
        type: "string"
        description: "The randomly generated UUID identifying this advice, as defined\
          \ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
      requestId:
        type: "string"
        description: "The UUID identifying the request that this advice relates to"
      time:
        type: "string"
        format: "date-time"
        description: "The date and time of the message as recorded by the sender.\
          \ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
          \ It is recommended that the optional time-secfrac be included up to millisecond\
          \ precision"
      thirdPartyIdentifiers:
        type: "array"
        description: "The unaltered thirdPartyIdentifiers array as supplied in the\
          \ related BasicResponse message. Required if thirdPartyIdentifiers field\
          \ was present in the BasicResponse. If no thirdPartyIdentifiers was received\
          \ in the BasicResponse or no BasicResponse was received then this should\
          \ be set to the thirdPartyIdentifiers sent in the original request."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
    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: "#/definitions/ThirdPartyIdentifier"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
      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: "#/definitions/PaymentMethod"
    - type: "object"
      required:
      - "pan"
      properties:
        posInfo:
          $ref: "#/definitions/PosInfo"
        pan:
          type: "string"
          description: "Primary account number that uniquely identifies this card."
          pattern: "[0-9]{1,19}"
        expiryDate:
          type: "string"
          description: "The card expiry date, in YYMM format."
          pattern: "[0-9]{4}"
        encryptedPin:
          description: "The encrypted pin number associated with the card in HEX format."
          $ref: "#/definitions/EncryptedPin"
        pin:
          description: "The PIN associated with this card as either a clear PIN or\
            \ an encrypted PIN in HEX format."
          $ref: "#/definitions/Pin"
      description: "Model for card-based payments"
  EncryptedPin:
    type: "object"
    required:
    - "pinBlock"
    properties:
      pinBlock:
        type: "string"
        description: "Hexadecimal string representing the encrypted PIN to be used."
        pattern: "[a-fA-F0-9]{16}"
      encryptionParameters:
        description: "Parameters pertaining to the generation of the pinBlock. Required\
          \ if the service is to perform any operations on the encrypted PIN, such\
          \ as PIN translation."
        $ref: "#/definitions/EncryptionParameters"
    description: "A PIN required to authorise a transaction. EncryptionParameters\
      \ should be provided where the service will be performing operations on the\
      \ encrypted PIN, such as PIN translation. Only the PIN block need be provided\
      \ where the service is expected to forward it to a third party, where the calling\
      \ client and said third party have agreed upon encryption parameters beforehand."
  EncryptionParameters:
    type: "object"
    required:
    - "accountNumber"
    properties:
      pinBlockFormat:
        type: "string"
        description: "PIN block format that was used when encrypting the PIN. Defaults\
          \ to ISO_9564_FORMAT_0."
        enum:
        - "ISO_9564_FORMAT_0"
        - "ISO_9564_FORMAT_1"
        - "ISO_9564_FORMAT_3"
        default: "ISO_9564_FORMAT_0"
      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"
      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"
      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"
  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: "#/definitions/PaymentMethod"
    - type: "object"
      required:
      - "cardNumber"
      properties:
        cardNumber:
          type: "string"
          description: "Primary account number of the loyalty programme card used\
            \ to make a payment"
          pattern: "[0-9]{16}"
      description: "Model for payments made using loyalty programme cards"
  Merchant:
    type: "object"
    required:
    - "merchantId"
    - "merchantName"
    - "merchantType"
    properties:
      merchantType:
        type: "string"
        description: "The assigned four digit merchant category code"
        pattern: "[0-9]{4}"
      merchantId:
        type: "string"
        description: "The assigned merchant identifier. Also known as card acceptor\
          \ id"
        minLength: 15
        maxLength: 15
      merchantName:
        description: "The name of a merchant"
        $ref: "#/definitions/MerchantName"
    description: "Merchant related data. Must be included if available"
  MerchantName:
    type: "object"
    required:
    - "city"
    - "country"
    - "name"
    - "region"
    properties:
      name:
        type: "string"
        description: "The merchant or trading as name associated with the merchant"
        minLength: 0
        maxLength: 23
      city:
        type: "string"
        description: "The city where the merchant is located"
        minLength: 0
        maxLength: 13
      region:
        type: "string"
        description: "The state or region where the merchant is located"
        minLength: 0
        maxLength: 2
      country:
        type: "string"
        description: "The country where the merchant is located"
        minLength: 0
        maxLength: 2
    description: "A container object representing the Merchant Name and Location"
  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:
        description: "The Mobile Network Operator (MNO) to whom the Msisdn belongs."
        $ref: "#/definitions/Institution"
    description: "Msisdn related data."
  MsisdnInfoResponse:
    type: "object"
    properties:
      msisdn:
        description: "The MSISDN which was looked up updated with relevant information\
          \ returned."
        $ref: "#/definitions/Msisdn"
      amounts:
        description: "Additional amounts which may pertain to transactions against\
          \ the Msisdn."
        $ref: "#/definitions/Amounts"
      promotion:
        description: "Promotional information for the customer identified by the MISDN."
        $ref: "#/definitions/Promotion"
      availableProducts:
        type: "array"
        description: "Products which may be available to the customer identified by\
          \ the Msisdn."
        items:
          $ref: "#/definitions/Product"
    description: "Information about the Msisdn."
  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"
  PaymentMethod:
    type: "object"
    required:
    - "amount"
    - "type"
    discriminator: "type"
    properties:
      type:
        type: "string"
        description: "The general method of payment used"
        enum:
        - "AN_32_TOKEN"
        - "LOYALTY_CARD"
        - "CARD"
      name:
        type: "string"
        description: "The specific method of payment used"
      amount:
        description: "Ledger amount of the payment"
        $ref: "#/definitions/LedgerAmount"
    description: "Base model for all payment types"
  Pin:
    type: "object"
    required:
    - "type"
    discriminator: "type"
    properties:
      type:
        type: "string"
        description: "Whether the PIN is communicated in the clear or encrypted."
        enum:
        - "CLEAR_PIN"
        - "ENCRYPTED_PIN"
    description: "Base model for capturing either a clear PIN or encrypted PIN"
  PinClear:
    allOf:
    - $ref: "#/definitions/Pin"
    - type: "object"
      required:
      - "pin"
      properties:
        pin:
          type: "string"
          description: "A clear PIN"
          pattern: ".{0,20}"
      description: "A clear PIN required to authorise a transaction."
  PinEncrypted:
    allOf:
    - $ref: "#/definitions/Pin"
    - type: "object"
      required:
      - "pinBlock"
      properties:
        pinBlock:
          type: "string"
          description: "Hexadecimal string representing the encrypted PIN to be used."
          pattern: "[a-fA-F0-9]{16}"
        encryptionParameters:
          description: "Parameters pertaining to the generation of the pinBlock. Required\
            \ if the service is to perform any operations on the encrypted PIN, such\
            \ as PIN translation."
          $ref: "#/definitions/EncryptionParameters"
      description: "A PIN required to authorise a transaction. EncryptionParameters\
        \ should be provided where the service will be performing operations on the\
        \ encrypted PIN, such as PIN translation. Only the PIN block need be provided\
        \ where the service is expected to forward it to a third party, where the\
        \ calling client and said third party have agreed upon encryption parameters\
        \ beforehand."
  PosEntryMode:
    type: "object"
    required:
    - "panEntryMode"
    - "pinEntryCapability"
    properties:
      panEntryMode:
        type: "string"
        description: "Describes the method by which the PAN was captured."
        enum:
        - "UNKNOWN"
        - "MANUAL"
        - "MAGSTRIPE_NO_CVV"
        - "BARCODE"
        - "OCR"
        - "ICC_CVV"
        - "CONTACTLESS_ICC"
        - "MAGSTRIPE_CVV"
        - "CONTACTLESS_MAGSTRIPE"
        - "ICC_NO_CVV"
        - "ORIG_MODE"
        - "FALLBACK"
      pinEntryCapability:
        type: "string"
        description: "Describes whether the PIN can be entered."
        enum:
        - "UNKNOWN"
        - "CAN_ACCEPT"
        - "CANNOT_ACCEPT"
    description: "Describes how the PAN and PIN were captured by the POS."
  PosInfo:
    type: "object"
    properties:
      entryMode:
        description: "Describes the manner in which the POS captured card and PIN\
          \ data."
        $ref: "#/definitions/PosEntryMode"
      posConditionCode:
        type: "string"
        description: "Describes the circumstances of the transaciton at the POS."
        enum:
        - "NORMAL_PRESENTMENT"
        - "CUSTOMER_NOT_PRESENT"
        - "CUSTOMER_PRESENT_AND_CARD_NOT_PRESENT"
        - "CUSTOMER_IDENTITY_VERIFIED"
        - "PUBLIC_UTILITY_TERMINAL"
        - "CUSTOMER_TERMINAL"
        - "MANUAL_REVERSAL"
        - "UNATTENDED_TERMINAL_AND_CARD_CAN_BE_RETAINED"
        - "UNATTENDED_TERMINAL_AND_CARD_CANNOT_BE_RETAINED"
    description: "POS related data."
  Product:
    type: "object"
    required:
    - "productId"
    properties:
      productId:
        type: "string"
        description: "A vendor determined code identifying the product the voucher\
          \ should pertain to."
        pattern: "[0-9A-Za-z]{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: 40
      type:
        type: "string"
        description: "An indication of the type of the product."
        enum:
        - "AIRTIME_FIXED"
        - "AIRTIME_VARIABLE"
        - "SMS_BUNDLE"
        - "DATA"
        - "APP_RELATED"
        - "COMBO"
      wholesalePrice:
        description: "The wholesale price of the product. The currency is in the currency\
          \ of the merchant's account with the provider."
        $ref: "#/definitions/LedgerAmount"
      recipientAmount:
        description: "The amount received by the recipient. The currency is in the\
          \ currency of the destination country."
        $ref: "#/definitions/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: "#/definitions/LedgerAmount"
    description: "Product related data."
  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: "#/definitions/ThirdPartyIdentifier"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
      tenders:
        type: "array"
        description: "An array of tenders used to pay for the transaction"
        items:
          $ref: "#/definitions/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:
      id:
        type: "string"
        description: "The randomly generated UUID identifying this transaction, as\
          \ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
      time:
        type: "string"
        format: "date-time"
        description: "The date and time of the message as recorded by the sender.\
          \ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
          \ It is recommended that the optional time-secfrac be included up to millisecond\
          \ precision"
      originator:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/SlipData"
      basketRef:
        type: "string"
        description: "Used to group multiple transactions which would otherwise be\
          \ considered independent."
      tranType:
        type: "string"
        description: "Data relating to the type of transaction taking place (i.e.\
          \ cash withdrawal, goods and services etc.)."
        enum:
        - "GOODS_AND_SERVICES"
        - "CASH_WITHDRAWAL"
        - "DEBIT_ADJUSTMENT"
        - "GOODS_AND_SERVICES_WITH_CASH_BACK"
        - "NON_CASH"
        - "RETURNS"
        - "DEPOSIT"
        - "CREDIT_ADJUSTMENT"
        - "GENERAL_CREDIT"
        - "AVAILABLE_FUNDS_INQUIRY"
        - "BALANCE_INQUIRY"
        - "GENERAL_INQUIRY"
        - "CARD_VERIFICATION_INQUIRY"
        - "CARDHOLDER_ACCOUNTS_TRANSFER"
        - "GENERAL_TRANSFER"
        - "PAYMENT_FROM_ACCOUNT"
        - "GENERAL_PAYMENT"
        - "PAYMENT_TO_ACCOUNT"
        - "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
        - "PLACE_HOLD_ON_CARD"
        - "GENERAL_ADMIN"
        - "CHANGE_PIN"
        - "CARD_HOLDER_INQUIRY"
        - "POINTS_INQUIRY"
      srcAccType:
        type: "string"
        description: "This specifies the type of source account being used in the\
          \ transaction (i.e. cheque, savings)."
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "GIFT_CARD"
        - "STORED_VALUE"
      destAccType:
        type: "string"
        description: "This specifies the type of destination account being used in\
          \ the transaction (i.e. cheque, savings)."
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "GIFT_CARD"
        - "STORED_VALUE"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
      amounts:
        description: "If the product identified by the product field is not a fixed\
          \ price product then the amounts field indicates the value of the product\
          \ referred to."
        $ref: "#/definitions/Amounts"
      product:
        description: "A description of the product requested."
        $ref: "#/definitions/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: "#/definitions/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: "#/definitions/PaymentMethod"
      recipientMsisdn:
        description: "The Msisdn of the customer who will receive or make use of the\
          \ product requested."
        $ref: "#/definitions/Msisdn"
      senderMsisdn:
        description: "The Msisdn of the customer who purchasing product requested.\
          \ This field may be mandatory for certain providers especially in the case\
          \ of international purchases."
        $ref: "#/definitions/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:
      id:
        type: "string"
        description: "The randomly generated UUID identifying this transaction, as\
          \ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
      time:
        type: "string"
        format: "date-time"
        description: "The date and time of the message as recorded by the sender.\
          \ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
          \ It is recommended that the optional time-secfrac be included up to millisecond\
          \ precision"
      originator:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Data to be printed on the slip in addition to the voucher instructions."
        $ref: "#/definitions/SlipData"
      basketRef:
        type: "string"
        description: "Used to group multiple transactions which would otherwise be\
          \ considered independent."
      tranType:
        type: "string"
        description: "Data relating to the type of transaction taking place (i.e.\
          \ cash withdrawal, goods and services etc.)."
        enum:
        - "GOODS_AND_SERVICES"
        - "CASH_WITHDRAWAL"
        - "DEBIT_ADJUSTMENT"
        - "GOODS_AND_SERVICES_WITH_CASH_BACK"
        - "NON_CASH"
        - "RETURNS"
        - "DEPOSIT"
        - "CREDIT_ADJUSTMENT"
        - "GENERAL_CREDIT"
        - "AVAILABLE_FUNDS_INQUIRY"
        - "BALANCE_INQUIRY"
        - "GENERAL_INQUIRY"
        - "CARD_VERIFICATION_INQUIRY"
        - "CARDHOLDER_ACCOUNTS_TRANSFER"
        - "GENERAL_TRANSFER"
        - "PAYMENT_FROM_ACCOUNT"
        - "GENERAL_PAYMENT"
        - "PAYMENT_TO_ACCOUNT"
        - "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
        - "PLACE_HOLD_ON_CARD"
        - "GENERAL_ADMIN"
        - "CHANGE_PIN"
        - "CARD_HOLDER_INQUIRY"
        - "POINTS_INQUIRY"
      srcAccType:
        type: "string"
        description: "This specifies the type of source account being used in the\
          \ transaction (i.e. cheque, savings)."
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "GIFT_CARD"
        - "STORED_VALUE"
      destAccType:
        type: "string"
        description: "This specifies the type of destination account being used in\
          \ the transaction (i.e. cheque, savings)."
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "GIFT_CARD"
        - "STORED_VALUE"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
      amounts:
        description: "If the product identified by the product field is not a fixed\
          \ price product then the amounts field indicates the value of the product\
          \ referred to."
        $ref: "#/definitions/Amounts"
      product:
        description: "A description of the product requested."
        $ref: "#/definitions/Product"
      msisdn:
        description: "The Msisdn of the customer who will use the product requested."
        $ref: "#/definitions/Msisdn"
      voucher:
        description: "In the case of a PIN based product, this details the voucher\
          \ to be redeemed for the requested product."
        $ref: "#/definitions/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: "#/definitions/ThirdPartyIdentifier"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
      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."
  SlipData:
    type: "object"
    properties:
      messageLines:
        type: "array"
        description: "An array of text lines and optional formatting to be printed\
          \ on the customer slip."
        items:
          $ref: "#/definitions/SlipLine"
      slipWidth:
        type: "integer"
        format: "int32"
        description: "The width of the slip in normal (unformatted) characters."
      issuerReference:
        type: "string"
        description: "An identifier that is printed on the customer slip and uniquely\
          \ identifies the payment on the service provider's system. This value is\
          \ used by the customer to request a refund when the service supports this\
          \ function, and it is thus important that this number is unique."
        pattern: "[A-Z0-9]{1,40}"
    description: "Data that may be printed on the customer slip for information purposes"
  SlipLine:
    type: "object"
    required:
    - "text"
    properties:
      barcode:
        description: "Barcode information for this line"
        $ref: "#/definitions/Barcode"
      text:
        type: "string"
        description: "Text contained on the line"
      fontWidthScaleFactor:
        type: "number"
        format: "double"
        description: "Scale factor for font width. Assume 1.0 (i.e. normal size) if\
          \ not present."
      fontHeightScaleFactor:
        type: "number"
        format: "double"
        description: "Scale factor for font height. Assume 1.0 (i.e. normal size)\
          \ if not present."
      line:
        type: "boolean"
        description: "Denotes a solid line on the slip. Assume false if not present."
        default: false
      cut:
        type: "boolean"
        description: "Indicates the slip should be cut at this line. Assume false\
          \ if not present."
        default: false
    description: "A line of text to be printed on the till slip"
  Tender:
    type: "object"
    required:
    - "amount"
    - "tenderType"
    properties:
      accountType:
        type: "string"
        description: "The type of account"
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "STORED_VALUE"
      amount:
        description: "The tendered amount"
        $ref: "#/definitions/LedgerAmount"
      cardNumber:
        type: "string"
        description: "A PCI compliant masked card number, with at least the first\
          \ 6 digits in the clear. Only applicable to card based transactions"
        pattern: "[0-9]{6}[0-9*]{0,13}"
      reference:
        type: "string"
        description: "A free text reference"
        minLength: 0
        maxLength: 40
      tenderType:
        type: "string"
        description: "The type of tender used"
        enum:
        - "CASH"
        - "CHEQUE"
        - "CREDIT_CARD"
        - "DEBIT_CARD"
        - "WALLET"
        - "ROUNDING"
        - "GIFT_CARD"
        - "LOYALTY_CARD"
        - "OTHER"
    description: "Details of the Tender used by a customer towards a payment"
  ThirdPartyIdentifier:
    type: "object"
    required:
    - "institutionId"
    - "transactionIdentifier"
    properties:
      institutionId:
        type: "string"
        description: "The entity's institution ID."
      transactionIdentifier:
        type: "string"
        description: "The identifier assigned to this transaction by the institution\
          \ represented in institutionId. This value should be unique within the institution's\
          \ system."
    description: "An identifier assigned by an entity which process the message. Identifiers\
      \ are keyed by institution ID thereby enabling any institution to recall a transaction\
      \ within the entity's own system using the entity's own identifier. Entity's\
      \ must not alter the identifier set by another entity. Once an identifier has\
      \ been set by an entity, all other entity's must send that identifier in subsequent\
      \ messages."
  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. This 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: "#/definitions/ThirdPartyIdentifier"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
      tenders:
        type: "array"
        description: "An array of tenders used to pay for the transaction"
        items:
          $ref: "#/definitions/Tender"
      voucher:
        description: "Information about the specific voucher being confirmed. This\
          \ should at a minimum be the voucher serial number returned in the VoucherResponse\
          \ so that the vendor can look up the voucher to be confirmed within the\
          \ vendor's system."
        $ref: "#/definitions/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:
      id:
        type: "string"
        description: "The randomly generated UUID identifying this transaction, as\
          \ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
      time:
        type: "string"
        format: "date-time"
        description: "The date and time of the message as recorded by the sender.\
          \ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
          \ It is recommended that the optional time-secfrac be included up to millisecond\
          \ precision"
      originator:
        description: "Data relating to the originator of the transaction."
        $ref: "#/definitions/Originator"
      client:
        description: "Data relating to the sender of Transaction."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Text to be printed on the customer receipt."
        $ref: "#/definitions/SlipData"
      basketRef:
        type: "string"
        description: "Used to group multiple transactions which would otherwise be\
          \ considered independent."
      tranType:
        type: "string"
        description: "Data relating to the type of transaction taking place (i.e.\
          \ cash withdrawal, goods and services etc.)."
        enum:
        - "GOODS_AND_SERVICES"
        - "CASH_WITHDRAWAL"
        - "DEBIT_ADJUSTMENT"
        - "GOODS_AND_SERVICES_WITH_CASH_BACK"
        - "NON_CASH"
        - "RETURNS"
        - "DEPOSIT"
        - "CREDIT_ADJUSTMENT"
        - "GENERAL_CREDIT"
        - "AVAILABLE_FUNDS_INQUIRY"
        - "BALANCE_INQUIRY"
        - "GENERAL_INQUIRY"
        - "CARD_VERIFICATION_INQUIRY"
        - "CARDHOLDER_ACCOUNTS_TRANSFER"
        - "GENERAL_TRANSFER"
        - "PAYMENT_FROM_ACCOUNT"
        - "GENERAL_PAYMENT"
        - "PAYMENT_TO_ACCOUNT"
        - "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
        - "PLACE_HOLD_ON_CARD"
        - "GENERAL_ADMIN"
        - "CHANGE_PIN"
        - "CARD_HOLDER_INQUIRY"
        - "POINTS_INQUIRY"
      srcAccType:
        type: "string"
        description: "This specifies the type of source account being used in the\
          \ transaction (i.e. cheque, savings)."
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "GIFT_CARD"
        - "STORED_VALUE"
      destAccType:
        type: "string"
        description: "This specifies the type of destination account being used in\
          \ the transaction (i.e. cheque, savings)."
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "GIFT_CARD"
        - "STORED_VALUE"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
      amounts:
        description: "If the product identified by the product field is not a fixed\
          \ price product then the amounts field indicates the value of the product\
          \ referred to."
        $ref: "#/definitions/Amounts"
      product:
        description: "The product for which the voucher should be provisioned."
        $ref: "#/definitions/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: "#/definitions/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: "#/definitions/PaymentMethod"
    description: "Information about the voucher provision request."
  VoucherResponse:
    type: "object"
    required:
    - "client"
    - "id"
    - "originator"
    - "thirdPartyIdentifiers"
    - "time"
    - "voucher"
    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"
      client:
        description: "Data relating to the sender of the VoucherRequest."
        $ref: "#/definitions/Institution"
      settlementEntity:
        description: "Data relating to the entity with whom the Merchant will settle\
          \ the transaction."
        $ref: "#/definitions/Institution"
      receiver:
        description: "Data relating to the entity which ultimately processes the request."
        $ref: "#/definitions/Institution"
      thirdPartyIdentifiers:
        type: "array"
        description: "An array of identifiers which each identify the transaction\
          \ within each entity's system."
        items:
          $ref: "#/definitions/ThirdPartyIdentifier"
      slipData:
        description: "Data to be printed on the slip in addition to the voucher instructions."
        $ref: "#/definitions/SlipData"
      basketRef:
        type: "string"
        description: "Used to group multiple transactions which would otherwise be\
          \ considered independent."
      tranType:
        type: "string"
        description: "Data relating to the type of transaction taking place (i.e.\
          \ cash withdrawal, goods and services etc.)."
        enum:
        - "GOODS_AND_SERVICES"
        - "CASH_WITHDRAWAL"
        - "DEBIT_ADJUSTMENT"
        - "GOODS_AND_SERVICES_WITH_CASH_BACK"
        - "NON_CASH"
        - "RETURNS"
        - "DEPOSIT"
        - "CREDIT_ADJUSTMENT"
        - "GENERAL_CREDIT"
        - "AVAILABLE_FUNDS_INQUIRY"
        - "BALANCE_INQUIRY"
        - "GENERAL_INQUIRY"
        - "CARD_VERIFICATION_INQUIRY"
        - "CARDHOLDER_ACCOUNTS_TRANSFER"
        - "GENERAL_TRANSFER"
        - "PAYMENT_FROM_ACCOUNT"
        - "GENERAL_PAYMENT"
        - "PAYMENT_TO_ACCOUNT"
        - "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
        - "PLACE_HOLD_ON_CARD"
        - "GENERAL_ADMIN"
        - "CHANGE_PIN"
        - "CARD_HOLDER_INQUIRY"
        - "POINTS_INQUIRY"
      srcAccType:
        type: "string"
        description: "This specifies the type of source account being used in the\
          \ transaction (i.e. cheque, savings)."
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "GIFT_CARD"
        - "STORED_VALUE"
      destAccType:
        type: "string"
        description: "This specifies the type of destination account being used in\
          \ the transaction (i.e. cheque, savings)."
        enum:
        - "DEFAULT"
        - "SAVINGS"
        - "CHEQUE"
        - "CREDIT"
        - "UNIVERSAL"
        - "ELECTRONIC_PURSE"
        - "GIFT_CARD"
        - "STORED_VALUE"
      stan:
        type: "string"
        description: "The System Trace Audit Number can be used to locate transactions\
          \ across different systems."
      rrn:
        type: "string"
        description: "This is a reference set by the original source of the transaction."
      amounts:
        description: "If the product identified by the product field is not a fixed\
          \ price product then the amounts field indicates the value of the product\
          \ in the response."
        $ref: "#/definitions/Amounts"
      responseProduct:
        description: "The product for which the voucher was provisioned. This is assumed\
          \ to be the product requested if this is absent."
        $ref: "#/definitions/Product"
      voucher:
        description: "The voucher provisioned if the vendor processed the request\
          \ successfully."
        $ref: "#/definitions/Voucher"
    description: "Information about the voucher provisioned."