Definitions

An32TokenPayment

Model for token-based payments

Name Type Required Default Restrictions Description
type string required [AN_32_TOKEN, LOYALTY_CARD] The general method of payment used
name string optional The specific method of payment used
amount LedgerAmount required Ledger amount of the payment
token string required pattern:[a-zA-Z0-9]{32}
32 character alphanumeric code which identifies a token

Barcode

Used to indicate barcode information for a slip line.

Name Type Required Default Restrictions Description
data string required Data to be encoded in the barcode
encoding string required Specifies the encoding used in the barcode

BasicAdviceResponse

Basic advice response information.

Name Type Required Default Restrictions Description
id string required The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
requestId string required The UUID identifying the request that this advice relates to
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
thirdPartyIdentifiers array[ThirdPartyIdentifier] required 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.

ConfirmationAdvice

Represents an advice message confirming successful completion of a transaction.

Name Type Required Default Restrictions Description
id string required The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
requestId string required The UUID identifying the request that this advice relates to
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
thirdPartyIdentifiers array[ThirdPartyIdentifier] required 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.
tenders array[Tender] required An array of tenders used to pay for the transaction

Customer

A customer who ultimately requests a transaction be performed.

Name Type Required Default Restrictions Description
firstName string optional maxLength:40
The customer’s first name(s)
lastName string optional maxLength:40
The customer’s last name
address string optional maxLength:80
The customer’s address

DebtRecoveryCharge

Represents a charge deducted from the purchase to recover outstanding debt

Name Type Required Default Restrictions Description
amount TaxableAmount required Amount charged and tax levied for debt recovery, in minor denomination.
description string required maxLength:40
Description of this debt recovery charge (e.g. municipal rates arrears).
balance LedgerAmount required Remaining balance on this account.
receiptNum string optional maxLength:30
Receipt number for this charge.

ErrorDetail

Represents the outcome of a completed transaction

Name Type Required Default Restrictions Description
errorType string required [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] The type of error that occurred
errorMessage string required maxLength:20
A short description of the error
requestType string required [METER_LOOKUP_REQUEST, TOKEN_PURCHASE_REQUEST, TOKEN_PURCHASE_RETRY_REQUEST, TOKEN_REPRINT_REQUEST, FAULT_REPORT_REQUEST, KEY_CHANGE_TOKEN_REQUEST, CONFIRMATION_ADVICE, REVERSAL_ADVICE] The type of request being processed when the error occurred.
id string required The UUID of the message for which error occurred.
originalId string optional The UUID of the original request message in the case of an error occurring for an advice message.
detailMessage object optional A free form detailed description of a particular failure condition may optionally be supplied

FaultReportRequest

Data required to report a fault related to a specific meter

Name Type Required Default Restrictions Description
meter Meter required Details of the meter for which fault is logged. The object must include at least a value for meterId.
customer Customer optional Details of the person or organization to whom the meter belongs.
contactNumber string required maxLength:20
Contact telephone number of the person reporting the fault
faultType string required [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] Type of fault that is being reported
id string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional Text to be printed on the customer receipt.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).

FaultReportResponse

Represents a response to a fault report

Name Type Required Default Restrictions Description
reference string required Reference number for the fault report
description string required maxLength:160
Description of the fault
id string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional Text to be printed on the customer receipt.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).

Institution

Originating, acquiring, processing, or receiving institution details

Name Type Required Default Restrictions Description
id string required pattern:[0-9]{1,11}
The institution’s id as assigned by Electrum
name string required maxLength:40
The institutions’s name

KeyChangeData

Represents updated meter encryption key data

Name Type Required Default Restrictions Description
newSupplyGroupCode string optional pattern:[0-9]{6}
New supply group code. Only relevant if this has been changed by the utility and a key change token has been issued.
newKeyRevisionNumber string optional pattern:[0-9]{1}
New key revision number. Only relevant if this has been changed by the utility and a key change token has been issued.
newTariffIndex string optional pattern:[0-9]{2}
New tariff index. Only relevant if this has been changed by the utility and a key change token has been issued.

KeyChangeTokenRequest

Represents a request for a key change token

Name Type Required Default Restrictions Description
meter Meter required Details of the meter.
id string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional Text to be printed on the customer receipt.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).

KeyChangeTokenResponse

Represents a response to a key change token request

Name Type Required Default Restrictions Description
meter Meter required Details of the meter.
tokens array[Token] optional List of tokens issued for the key change.
id string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional 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.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).

LedgerAmount

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

Name Type Required Default Restrictions Description
amount integer required format:int64
Amount in minor denomination, e.g. R799.95 is encoded as 79995
currency string required pattern:[0-9]{3}
Three digit currency number from ISO 4217, e.g. South African Rand is encoded as 710
ledgerIndicator string optional [DEBIT, CREDIT] Indicates whether this amount is a debit or a credit. Only required when the amount can be either a debit or a credit

LoyaltyCardPayment

Model for payments made using loyalty programme cards

Name Type Required Default Restrictions Description
type string required [AN_32_TOKEN, LOYALTY_CARD] The general method of payment used
name string optional The specific method of payment used
amount LedgerAmount required Ledger amount of the payment
cardNumber string required pattern:[0-9]{16}
Primary account number of the loyalty programme card used to make a payment

Merchant

Merchant related data. Must be included if available

Name Type Required Default Restrictions Description
merchantType string required pattern:[0-9]{4}
The assigned four digit merchant category code
merchantId string required maxLength:15
minLength:15
The assigned merchant identifier. Also known as card acceptor id
merchantName MerchantName required The name of a merchant

MerchantName

A container object representing the Merchant Name and Location

Name Type Required Default Restrictions Description
name string required maxLength:23
The merchant or trading as name associated with the merchant
city string required maxLength:13
The city where the merchant is located
region string required maxLength:2
The state or region where the merchant is located
country string required maxLength:2
The country where the merchant is located

Meter

Data associated with a prepaid utility meter

Name Type Required Default Restrictions Description
meterId string required pattern:[a-zA-Z0-9]{0,20}
Unique identifier for the meter (e.g. serial number).
track2Data string optional pattern:[a-zA-Z0-9=]{34}
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.
serviceType string optional pattern:[a-zA-Z0-9]{0,12}
Type of service dispensed by this meter (e.g. electricity, water or gas).
supplyGroupCode string optional pattern:[0-9]{6}
Code used to identify a group of suppliers.
keyRevisionNum string optional pattern:[0-9]{1}
Key revision number of the meter.
tariffIndex string optional pattern:[0-9]{2}
Code representing the tariff associated with this meter.
tokenTechCode string optional pattern:[0-9]{2}
The means by which tokens are supplied for this meter (typically either numeric token or magnetic track).
algorithmCode string optional pattern:[0-9]{2}
Code used to identify token encryption algorithm used by the meter.
keyChangeData KeyChangeData optional Represents new meter data in the case that these these have been updated.

MeterLookupRequest

Represents a request for information about a meter

Name Type Required Default Restrictions Description
meter Meter required Details of the meter for which information is requested. The object must include at least a value for meterId.
id string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional Text to be printed on the customer receipt.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).

MeterLookupResponse

Represents a response to a meter lookup request

Name Type Required Default Restrictions Description
meter Meter required Details of the meter.
customer Customer required Details of the person or organization to whom the meter belongs.
utility Utility required Details of the utility which manages this meter’s account.
minAmount LedgerAmount optional Minimum purchase amount that can be requested by the customer.
maxAmount LedgerAmount optional Maximum purchase amount that can be requested by the customer.
bsstDue boolean optional 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.
id string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional Text to be printed on the customer receipt.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).

Originator

The Originator object encapsulates data relating to the originator of the transaction

Name Type Required Default Restrictions Description
institution Institution required The institution originating the request, as issued by Electrum
terminalId string required maxLength:8
minLength:8
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
merchant Merchant required Merchant data. Required if available

PaymentMethod

Base model for all payment types

Name Type Required Default Restrictions Description
type string required [AN_32_TOKEN, LOYALTY_CARD] The general method of payment used
name string optional The specific method of payment used
amount LedgerAmount required Ledger amount of the payment

PurchaseRequest

Represents a token purchase request

Name Type Required Default Restrictions Description
meter Meter required Details of the meter for which a purchase is requested. The object must include at least a value for meterId.
purchaseAmount LedgerAmount required Monetary amount, in minor denomination, of the requested token purchase.
utilityType string optional Type of utility purchase being requested (e.g. electricity, water, gas).
msisdn string optional pattern:(^+?[1-9]\d{1,14})|(^[0][0-9]{9})
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.
tenders array[Tender] optional 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.
id string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional Text to be printed on the customer receipt.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).
paymentMethods array[PaymentMethod] optional 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.

PurchaseResponse

Represents the response to a token purchase request

Name Type Required Default Restrictions Description
purchaseTotal LedgerAmount optional 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.
taxTotal LedgerAmount optional 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.
meter Meter required Details of the meter.
customer Customer required Details of the person or organization to whom the meter belongs.
utility Utility required Details of the utility which manages this meter’s account.
utilityType string optional Type of utility purchase being requested (e.g. electricity, water, gas).
tokens array[Token] optional List of tokens issued for the purchase.
debtRecoveryCharges array[DebtRecoveryCharge] optional List of charges that have been levied in order to reclaim outstanding debts associated with the meter.
serviceCharges array[ServiceCharge] optional List of service charges levied against this meter.
vatInvoiceNumber string optional The VAT invoice number corresponding to this specific transaction.
id string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional Text to be printed on the customer receipt.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).

ReversalAdvice

Represents a request to reverse a previous transaction transaction.

Name Type Required Default Restrictions Description
id string required The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122
requestId string required The UUID identifying the request that this advice relates to
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
thirdPartyIdentifiers array[ThirdPartyIdentifier] required 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.
reversalReason string required [TIMEOUT, CANCELLED, RESPONSE_NOT_FINAL] The reason for the reversal

ServiceCharge

Represents a service charge deducted from the purchase amount

Name Type Required Default Restrictions Description
amount TaxableAmount required Amount charged and tax levied for the service.
description string required maxLength:40
Description of this service charge (e.g. connection fee).

SlipData

Data that may be printed on the customer slip for information purposes

Name Type Required Default Restrictions Description
messageLines array[SlipLine] optional An array of text lines and optional formatting to be printed on the customer slip.
slipWidth integer optional format:int32
The width of the slip in normal (unformatted) characters.
issuerReference string optional pattern:[A-Z0-9]{1,40}
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.

SlipLine

A line of text to be printed on the till slip

Name Type Required Default Restrictions Description
barcode Barcode optional Barcode information for this line
text string required Text contained on the line
fontWidthScaleFactor number optional format:double
Scale factor for font width. Assume 1.0 (i.e. normal size) if not present.
fontHeightScaleFactor number optional format:double
Scale factor for font height. Assume 1.0 (i.e. normal size) if not present.
line boolean optional Denotes a solid line on the slip. Assume false if not present.
cut boolean optional Indicates the slip should be cut at this line. Assume false if not present.

TariffBlock

Represents a block of units charged at a specific tariff

Name Type Required Default Restrictions Description
units number required Number of units in this tariff block.
rate number required Tariff rate for this block in minor denomination.

TaxableAmount

Represents an amount on which tax has been levied

Name Type Required Default Restrictions Description
tax integer optional format:int64
Tax amount. Only present and non-zero if the amount field is exclusive of tax.
taxType string optional maxLength:10
Description of the type of tax (e.g. VAT).
taxRate number optional Rate at which tax is levied, expressed as a percentage.
amount integer required format:int64
Amount in minor denomination, e.g. R799.95 is encoded as 79995
currency string required pattern:[0-9]{3}
Three digit currency number from ISO 4217, e.g. South African Rand is encoded as 710
ledgerIndicator string optional [DEBIT, CREDIT] Indicates whether this amount is a debit or a credit. Only required when the amount can be either a debit or a credit

Tender

Details of the Tender used by a customer towards a payment

Name Type Required Default Restrictions Description
accountType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, STORED_VALUE] The type of account
amount LedgerAmount required The tendered amount
cardNumber string optional pattern:[0-9]{6}[0-9*]{0,13}
A PCI compliant masked card number, with at least the first 6 digits in the clear. Only applicable to card based transactions
reference string optional maxLength:40
A free text reference
tenderType string required [CASH, CHEQUE, CREDIT_CARD, DEBIT_CARD, WALLET, ROUNDING, GIFT_CARD, LOYALTY_CARD, OTHER] The type of tender used

ThirdPartyIdentifier

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.

Name Type Required Default Restrictions Description
institutionId string required pattern:[0-9]{1,11}
The entity’s institution’s ID as assigned by Electrum.
transactionIdentifier string required The identifier assigned to this transaction by the institution represented in institutionId. This value should be unique within the institution’s system.

Token

Represents a prepaid utility token

Name Type Required Default Restrictions Description
tokenType string required [STD, BSST, REFUND, KC] Type of token, namely standard (STD), basic service support tariff (BSST), refund (REFUND), key change (KC).
units number required Number of units redeemable by this token.
amount TaxableAmount required Monetary value of the token
receiptNum string optional Receipt number issued for the transaction.
token string required Numeric sequence to be entered into the meter to redeem the token’s value.
tariffCalc array[TariffBlock] optional List of tariff blocks determining how the overall tariff is calculated.

TokenReprintRequest

Represents a request for a token reprint

Name Type Required Default Restrictions Description
meter Meter required Details of the meter for which a token reprint is requested. The object must include at least a value for meterId.
originalRef string optional 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 string required The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122
time string required format:date-time
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. It is recommended that the optional time-secfrac be included up to millisecond precision
originator Originator required Data relating to the originator of the transaction.
client Institution required Data relating to the sender of Transaction.
settlementEntity Institution optional Data relating to the entity with whom the Merchant will settle the transaction.
receiver Institution optional Data relating to the entity which ultimately processes the request.
thirdPartyIdentifiers array[ThirdPartyIdentifier] required An array of identifiers which each identify the transaction within each entity’s system.
slipData SlipData optional Text to be printed on the customer receipt.
basketRef string optional Used to group multiple transactions which would otherwise be considered independent.
tranType string optional [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] Data relating to the type of transaction taking place (i.e. cash withdrawal, goods and services etc.).
srcAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of source account being used in the transaction (i.e. cheque, savings).
destAccType string optional [DEFAULT, SAVINGS, CHEQUE, CREDIT, UNIVERSAL, ELECTRONIC_PURSE, GIFT_CARD, STORED_VALUE] This specifies the type of destination account being used in the transaction (i.e. cheque, savings).

Utility

Represents a utility with whom a meter is registered

Name Type Required Default Restrictions Description
name string optional maxLength:40
Name of the utility.
address string optional maxLength:80
Physical address of the utility.
vatRegNum string optional maxLength:10
VAT registration number of the utility.
clientId string optional maxLength:20
Identifier assigned by the utility to the client connecting to the utility’s token issuing service.
message string optional maxLength:80
Message send by the utility to be displayed on the customer receipt.