Definitions

AccountPayment

Model for an account-to-account payment method

Name Type Required Default Restrictions Description
type string required [AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD] The general method of payment used
name string optional The specific method of payment used
amount LedgerAmount required Ledger amount of the payment
srcAccountId string optional Source AccountId from which this payment will be made.
srcCustomerId string optional Source CustomerId from which this payment will be made.
destAccountId string optional Destination AccountId to which this payment will be made.
destCustomerId string optional Destination CustomerId to which this payment will be made.

Amounts

Amounts which make up the transaction. Absent amounts have zero value.

Name Type Required Default Restrictions Description
requestAmount LedgerAmount optional 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.
approvedAmount LedgerAmount optional The transaction amount which was approved by the upstream entity.
feeAmount LedgerAmount optional Fees charged by the upstream entity for processing the transaction.
balanceAmount LedgerAmount optional The remaining balance on the customer’s account.
additionalAmounts object optional Any additional amounts that are involved in a transaction which don’t appropriately fit into the other amount fields.

An32TokenPayment

Model for token-based payments

Name Type Required Default Restrictions Description
type string required [AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD] 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

BasicAdvice

The data required in all advice messages

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.
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.
amounts Amounts optional 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.

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.
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.
amounts Amounts optional 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.

CardPayment

Model for card-based payments

Name Type Required Default Restrictions Description
type string required [AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD] The general method of payment used
name string optional The specific method of payment used
amount LedgerAmount required Ledger amount of the payment
posInfo [PosInfo](#posinfo) optional
pan string required pattern:[0-9]{1,19}
Primary account number that uniquely identifies this card.
expiryDate string optional pattern:[0-9]{4}
The card expiry date, in YYMM format.
encryptedPin [EncryptedPin](#encryptedpin) optional The encrypted pin number associated with the card in HEX format.
pin [Pin](#pin) optional The PIN associated with this card as either a clear PIN or an encrypted PIN in HEX format.

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.
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.
amounts Amounts optional 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.
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
dateOfBirth string optional format:date-time
The customer’s date of birth
status string optional The status of this customer on the Giftcard system. For example: active, inactive
msisdn string optional pattern:^+?[1-9]\d{0,14}
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.
emailAddress string optional format:email
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).

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.

EncryptedPin

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.

Name Type Required Default Restrictions Description
pinBlock string required pattern:[a-fA-F0-9]{16}
Hexadecimal string representing the encrypted PIN to be used.
encryptionParameters EncryptionParameters optional 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.

EncryptionParameters

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.

Name Type Required Default Restrictions Description
pinBlockFormat string optional [ISO_9564_FORMAT_0, ISO_9564_FORMAT_1, ISO_9564_FORMAT_3] PIN block format that was used when encrypting the PIN. Defaults to ISO_9564_FORMAT_0.
accountNumber string required pattern:[0-9]{12}
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.
keyIndex integer optional format:int32
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.

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, 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] 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, NOTIFY_TOKEN_PURCHASE, TOKEN_PURCHASE_TRIAL_REQUEST] 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
faultDescription string optional maxLength:160
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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.

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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.

HashedPinParameters

A collection of parameters required to reliably reproduce the hashed value (excluding the actual PIN value).

Name Type Required Default Restrictions Description
name string required maxLength:20
The name of the hashing algorithm.

Institution

Originating, acquiring, processing, or receiving institution details

Name Type Required Default Restrictions Description
id string required The institution’s ID. API implementations should take care to set this field as appropriate for the implementation.
name string required maxLength:40
The institutions’s name

KeyChangeConfirmation

Represents an advice message confirming successful change of a key.

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.
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.
amounts Amounts optional 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.

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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.

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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.

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, CARD, ACCOUNT, REWARD] 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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.

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.
arrearsAmount LedgerAmount optional Returned arrears amount from provider. Encapsulates the total debt outstanding.
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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.

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
operatorId string optional maxLength:30
The ID that uniquely identifies the person operating the terminal specified by the terminalId field.

PaymentMethod

Base model for all payment types

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

Pin

Base model for capturing either a clear PIN or encrypted PIN

Name Type Required Default Restrictions Description
type string required [CLEAR_PIN, ENCRYPTED_PIN, HASHED_PIN] Whether the PIN is communicated in the clear or encrypted.

PinClear

A clear PIN required to authorise a transaction.

Name Type Required Default Restrictions Description
type string required [CLEAR_PIN, ENCRYPTED_PIN, HASHED_PIN] Whether the PIN is communicated in the clear or encrypted.
pin string required pattern:.{0,20}
A clear PIN

PinEncrypted

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.

Name Type Required Default Restrictions Description
type string required [CLEAR_PIN, ENCRYPTED_PIN, HASHED_PIN] Whether the PIN is communicated in the clear or encrypted.
pinBlock string required pattern:[a-fA-F0-9]{16}
Hexadecimal string representing the encrypted PIN to be used.
encryptionParameters [EncryptionParameters](#encryptionparameters) optional 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.

PinHashed

A PIN, required to authorise a transaction, which has been hashed according to some hashing algorithm.

Name Type Required Default Restrictions Description
type string required [CLEAR_PIN, ENCRYPTED_PIN, HASHED_PIN] Whether the PIN is communicated in the clear or encrypted.
hash string required pattern:[0-9,A-F]{1,512}
A hashed PIN expressed as an ASCII string of hexadecimal values.
hashedPinParameters [HashedPinParameters](#hashedpinparameters) optional Parameters that describe the hashing algorithm used to hash the PIN.

PosEntryMode

Describes how the PAN and PIN were captured by the POS.

Name Type Required Default Restrictions Description
panEntryMode string required [UNKNOWN, MANUAL, MAGSTRIPE_NO_CVV, BARCODE, OCR, ICC_CVV, CONTACTLESS_ICC, MAGSTRIPE_CVV, CONTACTLESS_MAGSTRIPE, ICC_NO_CVV, ORIG_MODE, FALLBACK] Describes the method by which the PAN was captured.
pinEntryCapability string required [UNKNOWN, CAN_ACCEPT, CANNOT_ACCEPT] Describes whether the PIN can be entered.

PosInfo

POS related data.

Name Type Required Default Restrictions Description
entryMode PosEntryMode optional Describes the manner in which the POS captured card and PIN data.
posConditionCode string optional [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] Describes the circumstances of the transaciton at the POS.

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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.
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.
amounts Amounts optional An optional amounts field for any additional amounts which may need to be added to the response payload.
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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.

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.
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.
amounts Amounts optional 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.
reversalReason string required [TIMEOUT, CANCELLED, RESPONSE_NOT_FINAL] The reason for the reversal

RewardPayment

Model for reward-based payments. This payment method should be used when the payment is offset using a reward programme

Name Type Required Default Restrictions Description
type string required [AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD] The general method of payment used
name string optional The specific method of payment used
amount LedgerAmount required Ledger amount of the payment
rewardCode string required maxLength:40
A code used to recognise the reward programme

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 The entity’s institution ID.
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, PWRLMT] 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, CARD_HOLDER_INQUIRY, POINTS_INQUIRY] 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).
stan string optional The System Trace Audit Number can be used to locate transactions across different systems.
rrn string optional This is a reference set by the original source of the transaction.

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.