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 Prepaid Utility Service describes an interface for facilitating\
\ the purchase
of prepaid tokens for
utilities\
\ such as electricity and water. One or more tokens for a requested value
\
\ are issued by an
upstream provider (typically\
\ a payments aggregator) against a specified meter number.
\
\ The tokens (each
being a sequence of usually 20 digits) are\
\ printed on the customer receipt and are
input manually on
\
\ the meter's keypad for the value to be redeemed."
version: "3.13.0"
title: "Prepaid Utility Service Interface"
contact:
name: "Electrum API"
url: "http://io.electrum"
email: "api@electrum.co.za"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "sandbox.electrum.io"
basePath: "/prepaidutility/v3"
schemes:
- "https"
paths:
/events/tokenPurchases:
post:
summary: "Notifies that a successful token purchase has taken place."
description: "An event notification to signal that a successful token purchase\
\ was performed. This operation is for informational purposes only. Implementations\
\ that do not need to subscribe to this event may simply return an HTTP status\
\ code 501."
operationId: "notifyTokenPurchase"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "purchaseId"
in: "query"
description: "The id of the original purchase request."
required: true
type: "string"
- in: "body"
name: "body"
description: "A token purchase response"
required: true
schema:
$ref: "#/definitions/PurchaseResponse"
responses:
202:
description: "Accepted"
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"
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: []
/faultReports/{requestId}:
post:
summary: "Report a fault on a meter"
description: "Reports a technical fault on a specified meter. This resource\
\ is used when a customer wishes to report a technical fault to the utility\
\ with whom the meter is reqistered."
operationId: "createFaultReport"
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 fault report"
required: true
schema:
$ref: "#/definitions/FaultReportRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/FaultReportResponse"
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: []
/keyChangeTokenRequests/{requestId}:
post:
summary: "Request a key change token"
description: "Requests a key change token for a specified meter. This resource\
\ is used when the utility has updated a meter's encryption key and the customer\
\ required a token to input the new key to the meter. Key change tokens are\
\ typically supplied as part of a normal purchase, so this operation is rarely\
\ used."
operationId: "createKeyChangeTokenRequest"
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 key change token request"
required: true
schema:
$ref: "#/definitions/KeyChangeTokenRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/KeyChangeTokenResponse"
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: []
/keyChangeTokenRequests/{requestId}/confirmations/{confirmationId}:
post:
summary: "Confirms that key change tokens have been provided to the customer."
description: "Confirms that key change tokens have been provided successfully"
operationId: "confirmKeyChange"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "requestId"
in: "path"
description: "The randomly generated UUID of the original request."
required: true
type: "string"
- name: "confirmationId"
in: "path"
description: "The randomly generated UUID of this confirmation."
required: true
type: "string"
- in: "body"
name: "body"
description: "A key change confirmation"
required: true
schema:
$ref: "#/definitions/KeyChangeConfirmation"
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"
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: []
/meterLookups/{lookupId}:
post:
summary: "Request information about a specified meter"
description: "Request information about a specified meter, including customer\
\ and utility details. This resource is used to verify that a meter number\
\ is valid and registered with the correct details. It also confirms whether\
\ the meter is recognised by a provider and that tokens can be issued against\
\ it."
operationId: "createMeterLookup"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "lookupId"
in: "path"
description: "The randomly generated UUID of this request."
required: true
type: "string"
- in: "body"
name: "body"
description: "A meter information lookup request."
required: true
schema:
$ref: "#/definitions/MeterLookupRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/MeterLookupResponse"
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: []
/tokenPurchases/{purchaseId}:
post:
summary: "Requests a token purchase for a specified meter."
description: "Requests that the provider issue a token against the meter for\
\ a given monetary value. In the case that the meter and/or utility supports\
\ the issue of free tokens under a basic service support tariff scheme, then\
\ any free tokens due will also be returned. If the requested amount is 0\
\ and a free token is due to the meter, then only this free token will be\
\ returned. A portion of the request amount may be used by the provider to\
\ offset outstanding debt or service charges owed by the customer, in which\
\ case the value of the token returned may be less than the request amount\
\ (see interface documentation for further details)."
operationId: "createTokenPurchaseRequest"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "purchaseId"
in: "path"
description: "The randomly generated UUID of this request."
required: true
type: "string"
- in: "body"
name: "body"
description: "A token purchase 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"
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: []
/tokenPurchases/{purchaseId}/confirmations/{confirmationId}:
post:
summary: "Confirms that a purchase has been completed successfully."
description: "Confirms that a purchase has been completed successfully (i.e.\
\ the tokens have been issued to the customer and payment has been received\
\ by the merchant). It is typical that token providers do not support confirmations\
\ (aka advices), but certain point-of-sale integrations may require support\
\ for these. A confirmation request must be sent repeatedly until an HTTP\
\ response code indicating a final state has been received (i.e. either 202\
\ or 400)."
operationId: "confirmTokenPurchase"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "purchaseId"
in: "path"
description: "The randomly generated UUID of the original purchase request."
required: true
type: "string"
- name: "confirmationId"
in: "path"
description: "The randomly generated UUID of this confirmation."
required: true
type: "string"
- in: "body"
name: "body"
description: "A token purchase confirmation"
required: true
schema:
$ref: "#/definitions/ConfirmationAdvice"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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"
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: []
/tokenPurchases/{purchaseId}/retry:
post:
summary: "Retry a previously submitted purchase request."
description: "If no response was received to a purchase request due to a timeout\
\ or temporary communications failure, PoS may retry the same purchase request\
\ by calling this resource. The original purchase request will be resubmitted\
\ to the provider. If the provider had received the original request, it will\
\ respond by returning any tokens that were already issued. If not, then either\
\ new tokens may be issued as per a normal purchase or the retry will be declined."
operationId: "retryPurchaseRequest"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "purchaseId"
in: "path"
description: "The randomly generated UUID of the original purchase request."
required: true
type: "string"
- in: "body"
name: "body"
description: "The original token purchase request."
required: true
schema:
$ref: "#/definitions/PurchaseRequest"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/PurchaseResponse"
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"
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: []
/tokenPurchases/{purchaseId}/reversals/{reversalId}:
post:
summary: "Notifies the provider that a purchase was not completed successfully."
description: "Notifies that a purchase was not completed successfully. This\
\ can occur if the original request timed out or if payment was unsuccessful.\
\ Many providers, however, do not support reversals and once a token has been\
\ issued the merchant becomes liable for the cost irrespective of payment\
\ failure or timeout. The token may still be retrieved by a reprint request,\
\ which merchants may use to help accommodate this scenario. A reversal request\
\ must be sent repeatedly until an HTTP response code indicating a final state\
\ has been received (i.e. either 202 or 400)."
operationId: "reverseTokenPurchase"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "purchaseId"
in: "path"
description: "The randomly generated UUID of the original purchase request."
required: true
type: "string"
- name: "reversalId"
in: "path"
description: "The randomly generated UUID of this reversal."
required: true
type: "string"
- in: "body"
name: "body"
description: "A token purchase reversal."
required: true
schema:
$ref: "#/definitions/ReversalAdvice"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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"
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: []
/tokenPurchases/{trialId}/trial:
post:
summary: "Requests a trial token purchase for a specified meter."
description: "This operation is identical to the 'createTokenPurchaseRequest'\
\ operation except that no tokens are returned and this operation carries\
\ no financial impact. This operation allows the customer to make an informed\
\ choice about the transaction outcome before committing to purchase electricity.\
\ This operation serves to inform a customer exactly what the outcome of their\
\ purchase is: the service charges which will be levied, the debt recovery\
\ charges, the number of units which will be provided etc. If a customer is\
\ dissatisfied with the details in the response, the customer may abort the\
\ transaction without any consequences."
operationId: "trialTokenPurchaseRequest"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "trialId"
in: "path"
description: "The randomly generated UUID of this request."
required: true
type: "string"
- in: "body"
name: "body"
description: "A token purchase request."
required: true
schema:
$ref: "#/definitions/PurchaseRequest"
responses:
200:
description: "OK"
schema:
$ref: "#/definitions/PurchaseResponse"
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: []
/tokenReprints/{reprintId}:
post:
summary: "Requests a reprint of a token"
description: "Requests a reprint of a token that was previously issued for a\
\ specified meter. The request can be for either the last token issued for\
\ that meter, or for a specific transaction reference, depending on what the\
\ provider supports."
operationId: "requestTokenReprint"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "reprintId"
in: "path"
description: "The randomly generated UUID of this request."
required: true
type: "string"
- in: "body"
name: "body"
description: "A token reprint request."
required: true
schema:
$ref: "#/definitions/TokenReprintRequest"
responses:
200:
description: "Success"
schema:
$ref: "#/definitions/PurchaseResponse"
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, where user name\
\ equals the value used in
MessageId.institutionId and\
\ password has been agreed with Electrum."
type: "basic"
definitions:
AccountPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
properties:
srcAccountId:
type: "string"
description: "Source AccountId from which this payment will be made."
srcCustomerId:
type: "string"
description: "Source CustomerId from which this payment will be made."
destAccountId:
type: "string"
description: "Destination AccountId to which this payment will be made."
destCustomerId:
type: "string"
description: "Destination CustomerId to which this payment will be made."
description: "Model for an account-to-account payment method"
Amounts:
type: "object"
properties:
requestAmount:
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."
amounts:
description: "Communicates the final amount for a transaction in the approvedAmount\
\ field. If absent from a reversal then a full reversal is implied (i.e.\
\ a final amount of zero). If absent from a confirmation then a full confirmation\
\ is implied (i.e. the final amount is the same as the approvedAmount of\
\ the authorisation response). The approvedAmount in an advice message\
\ should be less than or equal to the approvedAmount of the authorisation\
\ response as stand-in transactions are not currently supported."
$ref: "#/definitions/Amounts"
description: "The data required in all advice messages"
BasicAdviceResponse:
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."
amounts:
description: "Communicates the final amount for a transaction in the approvedAmount\
\ field. If absent from a reversal then a full reversal is implied (i.e.\
\ a final amount of zero). If absent from a confirmation then a full confirmation\
\ is implied (i.e. the final amount is the same as the approvedAmount of\
\ the authorisation response). The approvedAmount in an advice message\
\ should be less than or equal to the approvedAmount of the authorisation\
\ response as stand-in transactions are not currently supported."
$ref: "#/definitions/Amounts"
description: "Basic advice response information."
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"
ConfirmationAdvice:
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."
amounts:
description: "Communicates the final amount for a transaction in the approvedAmount\
\ field. If absent from a reversal then a full reversal is implied (i.e.\
\ a final amount of zero). If absent from a confirmation then a full confirmation\
\ is implied (i.e. the final amount is the same as the approvedAmount of\
\ the authorisation response). The approvedAmount in an advice message\
\ should be less than or equal to the approvedAmount of the authorisation\
\ response as stand-in transactions are not currently supported."
$ref: "#/definitions/Amounts"
tenders:
type: "array"
description: "An array of tenders used to pay for the transaction"
items:
$ref: "#/definitions/Tender"
description: "Represents an advice message confirming successful completion of\
\ a transaction."
Customer:
type: "object"
properties:
firstName:
type: "string"
description: "The customer's first name(s)"
minLength: 0
maxLength: 40
lastName:
type: "string"
description: "The customer's last name"
minLength: 0
maxLength: 40
address:
type: "string"
description: "The customer's address"
minLength: 0
maxLength: 80
dateOfBirth:
type: "string"
format: "date-time"
description: "The customer's date of birth"
status:
type: "string"
description: "The status of this customer on the Giftcard system. For example:\
\ active, inactive"
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{0,14}"
emailAddress:
type: "string"
format: "email"
description: "The customer's email address. This address must conform to RFC\
\ 5322 3.4.1 addr-spec (https://tools.ietf.org/html/rfc5322#section-3.4.1)."
description: "A customer who ultimately requests a transaction be performed."
DebtRecoveryCharge:
type: "object"
required:
- "amount"
- "balance"
- "description"
properties:
amount:
description: "Amount charged and tax levied for debt recovery, in minor denomination."
$ref: "#/definitions/TaxableAmount"
description:
type: "string"
description: "Description of this debt recovery charge (e.g. municipal rates\
\ arrears)."
minLength: 0
maxLength: 40
balance:
description: "Remaining balance on this account."
$ref: "#/definitions/LedgerAmount"
receiptNum:
type: "string"
description: "Receipt number for this charge."
minLength: 0
maxLength: 30
description: "Represents a charge deducted from the purchase to recover outstanding\
\ debt"
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."
default: "ISO_9564_FORMAT_0"
enum:
- "ISO_9564_FORMAT_0"
- "ISO_9564_FORMAT_1"
- "ISO_9564_FORMAT_3"
accountNumber:
type: "string"
description: "12 digit account number used when encrypting the PIN. When account\
\ number is a card number (PAN), this is the rightmost 12 digits excluding\
\ the check digit."
pattern: "[0-9]{12}"
keyIndex:
type: "integer"
format: "int32"
description: "Index of the key under which the PIN block is encrypted. Where\
\ keys are exchanged in TR-31 KeyBlock format, this should be set to the\
\ key version number field of the key used for encryption. If this field\
\ is not populated, the most recently exchanged key will be used. Note that\
\ omitting this field may require a higher level of synchronization during\
\ automated key exchange in some environments."
description: "Parameters pertaining to the generation of the PIN block. Required\
\ if the service is to perform any operations on the encrypted PIN, such as\
\ translation."
ErrorDetail:
type: "object"
required:
- "errorMessage"
- "errorType"
- "id"
- "requestType"
properties:
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"
- "UNKNOWN_METER_ID"
- "TRANSACTION_DECLINED"
- "INVALID_MERCHANT"
- "INVALID_AN32_TOKEN"
- "DO_NOT_HONOR"
- "INVALID_MSISDN"
- "INVALID_LOYALTY_CARD"
- "UTILITY_INVALID"
- "SYSTEM_MALFUNCTION"
- "METER_KEY_INVALID"
- "AMOUNT_TOO_LOW"
- "AMOUNT_TOO_HIGH"
- "NO_FREE_UNITS_DUE"
- "INSUFFICIENT_FUNDS"
- "LIMIT_EXCEEDED"
- "METER_ID_BLOCKED"
- "OUTCOME_UNKNOWN"
errorMessage:
type: "string"
description: "A short description of the error"
minLength: 0
maxLength: 20
requestType:
type: "string"
description: "The type of request being processed when the error occurred."
enum:
- "METER_LOOKUP_REQUEST"
- "TOKEN_PURCHASE_REQUEST"
- "TOKEN_PURCHASE_RETRY_REQUEST"
- "TOKEN_REPRINT_REQUEST"
- "FAULT_REPORT_REQUEST"
- "KEY_CHANGE_TOKEN_REQUEST"
- "CONFIRMATION_ADVICE"
- "REVERSAL_ADVICE"
- "NOTIFY_TOKEN_PURCHASE"
- "TOKEN_PURCHASE_TRIAL_REQUEST"
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"
FaultReportRequest:
type: "object"
required:
- "client"
- "contactNumber"
- "faultType"
- "id"
- "meter"
- "originator"
- "thirdPartyIdentifiers"
- "time"
properties:
meter:
description: "Details of the meter for which fault is logged. The object must\
\ include at least a value for meterId."
$ref: "#/definitions/Meter"
customer:
description: "Details of the person or organization to whom the meter belongs."
$ref: "#/definitions/Customer"
contactNumber:
type: "string"
description: "Contact telephone number of the person reporting the fault"
minLength: 0
maxLength: 20
faultType:
type: "string"
description: "Type of fault that is being reported"
enum:
- "SERIOUS_BOX_DAMAGE"
- "FIRE_WATER_DAMAGE"
- "METER_DEAD"
- "KEEPS_TRIPPING"
- "NO_TRIP"
- "DISPLAY_LIGHTS_BUTTONS"
- "NETWORK_FAULT_REPORT"
- "INCORRECT_SGC"
- "INCORRECT_TI"
- "CONVERTED_FRM_CONVENTIONAL"
- "METER_CHANGED_OUT"
- "NEW_INSTALLATION"
faultDescription:
type: "string"
minLength: 0
maxLength: 160
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."
description: "Data required to report a fault related to a specific meter"
FaultReportResponse:
type: "object"
required:
- "client"
- "description"
- "id"
- "originator"
- "reference"
- "thirdPartyIdentifiers"
- "time"
properties:
reference:
type: "string"
description: "Reference number for the fault report"
description:
type: "string"
description: "Description of the fault"
minLength: 0
maxLength: 160
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."
description: "Represents a response to a fault report"
HashedPinParameters:
type: "object"
required:
- "name"
properties:
name:
type: "string"
description: "The name of the hashing algorithm."
minLength: 0
maxLength: 20
description: "A collection of parameters required to reliably reproduce the hashed\
\ value (excluding the actual PIN value)."
Institution:
type: "object"
required:
- "id"
- "name"
properties:
id:
type: "string"
description: "The institution's ID. API implementations should take care to\
\ set this field as appropriate for the implementation."
name:
type: "string"
description: "The institutions's name"
minLength: 0
maxLength: 40
description: "Originating, acquiring, processing, or receiving institution details"
KeyChangeConfirmation:
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."
amounts:
description: "Communicates the final amount for a transaction in the approvedAmount\
\ field. If absent from a reversal then a full reversal is implied (i.e.\
\ a final amount of zero). If absent from a confirmation then a full confirmation\
\ is implied (i.e. the final amount is the same as the approvedAmount of\
\ the authorisation response). The approvedAmount in an advice message\
\ should be less than or equal to the approvedAmount of the authorisation\
\ response as stand-in transactions are not currently supported."
$ref: "#/definitions/Amounts"
description: "Represents an advice message confirming successful change of a key."
KeyChangeData:
type: "object"
properties:
newSupplyGroupCode:
type: "string"
description: "New supply group code. Only relevant if this has been changed\
\ by the utility and a key change token has been issued."
pattern: "[0-9]{6}"
newKeyRevisionNumber:
type: "string"
description: "New key revision number. Only relevant if this has been changed\
\ by the utility and a key change token has been issued."
pattern: "[0-9]{1}"
newTariffIndex:
type: "string"
description: "New tariff index. Only relevant if this has been changed by\
\ the utility and a key change token has been issued."
pattern: "[0-9]{2}"
description: "Represents updated meter encryption key data"
KeyChangeTokenRequest:
type: "object"
required:
- "client"
- "id"
- "meter"
- "originator"
- "thirdPartyIdentifiers"
- "time"
properties:
meter:
description: "Details of the meter."
$ref: "#/definitions/Meter"
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."
description: "Represents a request for a key change token"
KeyChangeTokenResponse:
type: "object"
required:
- "client"
- "id"
- "meter"
- "originator"
- "thirdPartyIdentifiers"
- "time"
properties:
meter:
description: "Details of the meter."
$ref: "#/definitions/Meter"
tokens:
type: "array"
description: "List of tokens issued for the key change."
items:
$ref: "#/definitions/Token"
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: "A ready-to-print till slip. This is supplied by some providers\
\ either in addition to or in place of individual message elements. Where\
\ present, it must be used by POS to print the slip."
$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."
description: "Represents a response to a key change token request"
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"
Meter:
type: "object"
required:
- "meterId"
properties:
meterId:
type: "string"
description: "Unique identifier for the meter (e.g. serial number)."
pattern: "[a-zA-Z0-9]{0,20}"
track2Data:
type: "string"
description: "Track 2 data stored on the magnetic stripe of a card that is\
\ supplied with certain meters. This data contains all meter details. It\
\ can be used as an alternative means of input at PoS and may be required\
\ by some providers."
pattern: "[a-zA-Z0-9=]{34}"
serviceType:
type: "string"
description: "Type of service dispensed by this meter (e.g. electricity, water\
\ or gas)."
pattern: "[a-zA-Z0-9]{0,12}"
supplyGroupCode:
type: "string"
description: "Code used to identify a group of suppliers."
pattern: "[0-9]{6}"
keyRevisionNum:
type: "string"
description: "Key revision number of the meter."
pattern: "[0-9]{1}"
tariffIndex:
type: "string"
description: "Code representing the tariff associated with this meter."
pattern: "[0-9]{2}"
tokenTechCode:
type: "string"
description: "The means by which tokens are supplied for this meter (typically\
\ either numeric token or magnetic track)."
pattern: "[0-9]{2}"
algorithmCode:
type: "string"
description: "Code used to identify token encryption algorithm used by the\
\ meter."
pattern: "[0-9]{2}"
keyChangeData:
description: "Represents new meter data in the case that these these have\
\ been updated."
$ref: "#/definitions/KeyChangeData"
description: "Data associated with a prepaid utility meter"
MeterLookupRequest:
type: "object"
required:
- "client"
- "id"
- "meter"
- "originator"
- "thirdPartyIdentifiers"
- "time"
properties:
meter:
description: "Details of the meter for which information is requested. The\
\ object must include at least a value for meterId."
$ref: "#/definitions/Meter"
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."
description: "Represents a request for information about a meter"
MeterLookupResponse:
type: "object"
required:
- "client"
- "customer"
- "id"
- "meter"
- "originator"
- "thirdPartyIdentifiers"
- "time"
- "utility"
properties:
meter:
description: "Details of the meter."
$ref: "#/definitions/Meter"
customer:
description: "Details of the person or organization to whom the meter belongs."
$ref: "#/definitions/Customer"
utility:
description: "Details of the utility which manages this meter's account."
$ref: "#/definitions/Utility"
minAmount:
description: "Minimum purchase amount that can be requested by the customer."
$ref: "#/definitions/LedgerAmount"
maxAmount:
description: "Maximum purchase amount that can be requested by the customer."
$ref: "#/definitions/LedgerAmount"
arrearsAmount:
description: "Returned arrears amount from provider. Encapsulates the total\
\ debt outstanding."
$ref: "#/definitions/LedgerAmount"
bsstDue:
type: "boolean"
description: "Boolean flag indicating whether a free basic service support\
\ token is owing on this meter. Not all meters support this and typically\
\ only one free token is issued per calendar month. If the value of this\
\ field is true, then a purchase request with an amount of 0 can be sent\
\ and the response will contain the free token."
default: false
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."
description: "Represents a response to a meter lookup request"
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"
operatorId:
type: "string"
description: "The ID that uniquely identifies the person operating the terminal\
\ specified by the terminalId field."
minLength: 0
maxLength: 30
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"
- "ACCOUNT"
- "REWARD"
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"
- "HASHED_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."
PinHashed:
allOf:
- $ref: "#/definitions/Pin"
- type: "object"
required:
- "hash"
properties:
hash:
type: "string"
description: "A hashed PIN expressed as an ASCII string of hexadecimal values."
pattern: "[0-9,A-F]{1,512}"
hashedPinParameters:
description: "Parameters that describe the hashing algorithm used to hash\
\ the PIN."
$ref: "#/definitions/HashedPinParameters"
description: "A PIN, required to authorise a transaction, which has been hashed\
\ according to some hashing algorithm."
PosEntryMode:
type: "object"
required:
- "panEntryMode"
- "pinEntryCapability"
properties:
panEntryMode:
type: "string"
description: "Describes the method by which the PAN was captured."
enum:
- "UNKNOWN"
- "MANUAL"
- "MAGSTRIPE_NO_CVV"
- "BARCODE"
- "OCR"
- "ICC_CVV"
- "CONTACTLESS_ICC"
- "MAGSTRIPE_CVV"
- "CONTACTLESS_MAGSTRIPE"
- "ICC_NO_CVV"
- "ORIG_MODE"
- "FALLBACK"
pinEntryCapability:
type: "string"
description: "Describes whether the PIN can be entered."
enum:
- "UNKNOWN"
- "CAN_ACCEPT"
- "CANNOT_ACCEPT"
description: "Describes how the PAN and PIN were captured by the POS."
PosInfo:
type: "object"
properties:
entryMode:
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."
PurchaseRequest:
type: "object"
required:
- "client"
- "id"
- "meter"
- "originator"
- "purchaseAmount"
- "thirdPartyIdentifiers"
- "time"
properties:
meter:
description: "Details of the meter for which a purchase is requested. The\
\ object must include at least a value for meterId."
$ref: "#/definitions/Meter"
purchaseAmount:
description: "Monetary amount, in minor denomination, of the requested token\
\ purchase."
$ref: "#/definitions/LedgerAmount"
utilityType:
type: "string"
description: "Type of utility purchase being requested (e.g. electricity,\
\ water, gas)."
msisdn:
type: "string"
description: "Mobile phone number of the customer to which the outcome of\
\ a transaction can be communicated. This should conform to the ITU E.164\
\ numbering plan (https://www.itu.int/rec/T-REC-E.164/en), but a 10-digit\
\ number beginning with zero is also acceptable."
pattern: "(^\+?[1-9]\d{1,14})|(^[0][0-9]{9})"
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"
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."
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: "Represents a token purchase request"
PurchaseResponse:
type: "object"
required:
- "client"
- "customer"
- "id"
- "meter"
- "originator"
- "thirdPartyIdentifiers"
- "time"
- "utility"
properties:
purchaseTotal:
description: "The total amount charged for tokens on this purchase. This amount\
\ is exclusive of tax and also excludes any debt recoveries or service charges\
\ deducted from the purchase amount."
$ref: "#/definitions/LedgerAmount"
taxTotal:
description: "The total tax charged for this purchase. This amount may include\
\ taxes levied on the tokens purchased, as well as any taxes on debt recovery\
\ or service charges."
$ref: "#/definitions/LedgerAmount"
amounts:
description: "An optional amounts field for any additional amounts which may\
\ need to be added to the response payload."
$ref: "#/definitions/Amounts"
meter:
description: "Details of the meter."
$ref: "#/definitions/Meter"
customer:
description: "Details of the person or organization to whom the meter belongs."
$ref: "#/definitions/Customer"
utility:
description: "Details of the utility which manages this meter's account."
$ref: "#/definitions/Utility"
utilityType:
type: "string"
description: "Type of utility purchase being requested (e.g. electricity,\
\ water, gas)."
tokens:
type: "array"
description: "List of tokens issued for the purchase."
items:
$ref: "#/definitions/Token"
debtRecoveryCharges:
type: "array"
description: "List of charges that have been levied in order to reclaim outstanding\
\ debts associated with the meter."
items:
$ref: "#/definitions/DebtRecoveryCharge"
serviceCharges:
type: "array"
description: "List of service charges levied against this meter."
items:
$ref: "#/definitions/ServiceCharge"
vatInvoiceNumber:
type: "string"
description: "The VAT invoice number corresponding to this specific transaction."
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."
description: "Represents the response to a token purchase request"
ReversalAdvice:
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."
amounts:
description: "Communicates the final amount for a transaction in the approvedAmount\
\ field. If absent from a reversal then a full reversal is implied (i.e.\
\ a final amount of zero). If absent from a confirmation then a full confirmation\
\ is implied (i.e. the final amount is the same as the approvedAmount of\
\ the authorisation response). The approvedAmount in an advice message\
\ should be less than or equal to the approvedAmount of the authorisation\
\ response as stand-in transactions are not currently supported."
$ref: "#/definitions/Amounts"
reversalReason:
type: "string"
description: "The reason for the reversal"
enum:
- "TIMEOUT"
- "CANCELLED"
- "RESPONSE_NOT_FINAL"
description: "Represents a request to reverse a previous transaction transaction."
RewardPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
required:
- "rewardCode"
properties:
rewardCode:
type: "string"
description: "A code used to recognise the reward programme"
minLength: 0
maxLength: 40
description: "Model for reward-based payments. This payment method should be\
\ used when the payment is offset using a reward programme"
ServiceCharge:
type: "object"
required:
- "amount"
- "description"
properties:
amount:
description: "Amount charged and tax levied for the service."
$ref: "#/definitions/TaxableAmount"
description:
type: "string"
description: "Description of this service charge (e.g. connection fee)."
minLength: 0
maxLength: 40
description: "Represents a service charge deducted from the purchase amount"
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"
TariffBlock:
type: "object"
required:
- "rate"
- "units"
properties:
units:
type: "number"
description: "Number of units in this tariff block."
rate:
type: "number"
description: "Tariff rate for this block in minor denomination."
description: "Represents a block of units charged at a specific tariff"
TaxableAmount:
type: "object"
required:
- "amount"
- "currency"
properties:
tax:
type: "integer"
format: "int64"
description: "Tax amount. Only present and non-zero if the amount field is\
\ exclusive of tax."
taxType:
type: "string"
description: "Description of the type of tax (e.g. VAT)."
minLength: 0
maxLength: 10
taxRate:
type: "number"
description: "Rate at which tax is levied, expressed as a percentage."
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: "Represents an amount on which tax has been levied"
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."
Token:
type: "object"
required:
- "amount"
- "token"
- "tokenType"
- "units"
properties:
tokenType:
type: "string"
description: "Type of token, namely standard (STD), basic service support\
\ tariff (BSST), refund (REFUND), key change (KC)."
enum:
- "STD"
- "BSST"
- "REFUND"
- "KC"
- "PWRLMT"
units:
type: "number"
description: "Number of units redeemable by this token."
amount:
description: "Monetary value of the token"
$ref: "#/definitions/TaxableAmount"
receiptNum:
type: "string"
description: "Receipt number issued for the transaction."
token:
type: "string"
description: "Numeric sequence to be entered into the meter to redeem the\
\ token's value."
tariffCalc:
type: "array"
description: "List of tariff blocks determining how the overall tariff is\
\ calculated."
items:
$ref: "#/definitions/TariffBlock"
description: "Represents a prepaid utility token"
TokenReprintRequest:
type: "object"
required:
- "client"
- "id"
- "meter"
- "originator"
- "thirdPartyIdentifiers"
- "time"
properties:
meter:
description: "Details of the meter for which a token reprint is requested.\
\ The object must include at least a value for meterId."
$ref: "#/definitions/Meter"
originalRef:
type: "string"
description: "Reference or receipt number for the original token in the case\
\ that a specific token is requested. If this field is not present, then\
\ the last-issued token will be requested from the provider."
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."
description: "Represents a request for a token reprint"
Utility:
type: "object"
properties:
name:
type: "string"
description: "Name of the utility."
minLength: 0
maxLength: 40
address:
type: "string"
description: "Physical address of the utility."
minLength: 0
maxLength: 80
vatRegNum:
type: "string"
description: "VAT registration number of the utility."
minLength: 0
maxLength: 10
clientId:
type: "string"
description: "Identifier assigned by the utility to the client connecting\
\ to the utility's token issuing service."
minLength: 0
maxLength: 20
message:
type: "string"
description: "Message send by the utility to be displayed on the customer\
\ receipt."
minLength: 0
maxLength: 80
description: "Represents a utility with whom a meter is registered"