Definitions

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

BasicReversal

An advice that notifies of the negative completion of a transaction. This can be either due to customer cancellation, or as a result of receiving a non-final response (or no response) to a request

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.
reversalReason string required [TIMEOUT, CANCELLED, RESPONSE_NOT_FINAL] The reason for the reversal

CardPayment

Model for card-based payments

Name Type Required Default Restrictions Description
type string required [AN_32_TOKEN, LOYALTY_CARD, CARD] 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 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 optional The encrypted pin number associated with the card in HEX format.
pin Pin optional The PIN associated with this card as either a clear PIN or an encrypted PIN in HEX format.

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
id string required maxLength:20
The randomly generated UUID identifying this errorDetail, as defined for a variant 4 UUID in RFC 4122
originalId string optional The UUID of the original request message in the case of an error occurring for an advice message
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, INVALID_PRODUCT, ACCOUNT_ALREADY_SETTLED, INVALID_MERCHANT, OUT_OF_STOCK, INVALID_AN32_TOKEN, DO_NOT_HONOR, DECLINED_BY_MNO, INVALID_MSISDN, INVALID_LOYALTY_CARD, INSUFFICIENT_FUNDS, INVALID_CARD_NUMBER, CARD_EXPIRED, INCORRECT_PIN, PIN_ATTEMPTS_EXCEEDED] The type of error that occurred
errorMessage string required maxLength:20
A short description of the error
requestType string required [VOUCHER_REQUEST, VOUCHER_REVERSAL, VOUCHER_CONFIRMATION, VOUCHER_VOID, MSISDN_INFO_REQUEST, PURCHASE_REQUEST, PURCHASE_CONFIRMATION, PURCHASE_STATUS_REQUEST, PURCHASE_REVERSAL] The type of request that preceeded the error
detailMessage object optional A free form detailed description of a particular failure condition may optionally be supplied
providerErrorCode string optional The error code returned by the service provider. Note that this should be used for informational purposes only. Messages displayed on the POS should make use of errorType and errorMessage to ensure a consistent set of responses.
providerErrorMsg string optional The error message returned by the service provider. Note that this should be used for informational purposes only. Messages displayed on the POS should make use of errorType and errorMessage to ensure a consistent set of responses.
providerRef string optional The reference returned by the service provider.

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

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] 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

Msisdn

Msisdn related data.

Name Type Required Default Restrictions Description
msisdn string required pattern:^+?[1-9]\d{1,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.
country string optional maxLength:2
minLength:2
The country of the Msisdn expressed as an ISO 3166-1 Alpha-2 country code.
operator Institution optional The Mobile Network Operator (MNO) to whom the Msisdn belongs.

MsisdnInfoResponse

Information about the Msisdn.

Name Type Required Default Restrictions Description
msisdn Msisdn optional The MSISDN which was looked up updated with relevant information returned.
amounts Amounts optional Additional amounts which may pertain to transactions against the Msisdn.
promotion Promotion optional Promotional information for the customer identified by the MISDN.
availableProducts array[Product] optional Products which may be available to the customer identified by the Msisdn.

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, CARD] 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] 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] 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] 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 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.

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.

Product

Product related data.

Name Type Required Default Restrictions Description
productId string required pattern:[0-9A-Za-z]{1,20}
A vendor determined code identifying the product the voucher should pertain to.
barcode string optional pattern:[0-9A-Za-z]{1,13}
A barcode code identifying the product. This is an alternative identifier for the product but does not supersede the productId.
name string optional maxLength:40
minLength:1
The name of the product.
type string optional [AIRTIME_FIXED, AIRTIME_VARIABLE, SMS_BUNDLE, DATA, APP_RELATED, COMBO] An indication of the type of the product.
wholesalePrice LedgerAmount optional The wholesale price of the product. The currency is in the currency of the merchant’s account with the provider.
recipientAmount LedgerAmount optional The amount received by the recipient. The currency is in the currency of the destination country.
productValues array[LedgerAmount] optional The value of the product. Multiple values may be returned in varying currencies in the case of products available internationally.

Promotion

Promotion related data.

Name Type Required Default Restrictions Description
promotion string required A description of the promotion available to the subscriber.
startDate string optional format:date-time
The start date of the promotion.
endDate string optional format:date-time
The end date of the promotion.

PurchaseConfirmation

Confirm that a previous {@link PurchaseRequest} has completed successfully at the POS.

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.
tenders array[Tender] required An array of tenders used to pay for the transaction

PurchaseRequest

A request for an airtime product. This may be for airtime, data or SMS products or a combination. Airtime requests may be for PIN based or PIN-less products.

Name Type Required Default Restrictions Description
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.
amounts Amounts optional If the product identified by the product field is not a fixed price product then the amounts field indicates the value of the product referred to.
product Product required A description of the product requested.
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.
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.
recipientMsisdn Msisdn optional The Msisdn of the customer who will receive or make use of the product requested.
senderMsisdn Msisdn optional The Msisdn of the customer who purchasing product requested. This field may be mandatory for certain providers especially in the case of international purchases.

PurchaseResponse

A response to a successful request for an airtime product.

Name Type Required Default Restrictions Description
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 Data to be printed on the slip in addition to the voucher instructions.
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.
amounts Amounts optional If the product identified by the product field is not a fixed price product then the amounts field indicates the value of the product referred to.
product Product required A description of the product requested.
msisdn Msisdn optional The Msisdn of the customer who will use the product requested.
voucher Voucher optional In the case of a PIN based product, this details the voucher to be redeemed for the requested product.

PurchaseReversal

Reverse a previous {@link PurchaseRequest}. This may be due to a cancellation at the POS or because the original {@link PurchaseRequest} is in an unknown state.

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.
reversalReason string required [TIMEOUT, CANCELLED, RESPONSE_NOT_FINAL] The reason for the reversal

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.

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.

Voucher

Specifically describes the voucher provisioned by the vendor.

Name Type Required Default Restrictions Description
pin string optional pattern:[0-9]{1,20}
The voucher’s PIN used by the customer to redeem the voucher. This must be present in VoucherResponse messages. It is recommended this field not be populated in other instances as it may be considered sensitive data.
expiryDate string optional format:date-time
The date and time at which the voucher expires in UTC. The format shall be as defined for date-time in RFC 3339 section 5.6.
serialNumber string required pattern:[0-9a-zA-Z]{1,20}
The voucher’s serial number. This can be used to identify the voucher in the vendor’s system but cannot be used to redeem the voucher.
batchNumber string optional pattern:[0-9a-zA-Z]{1,20}
The voucher’s batch number. This can be used to help identify the voucher in the vendor’s system but cannot be used to redeem the voucher.
redeemInstructions array[string] optional An array of free text lines which provide the customer with information on how to redeem the voucher. This are intended to be printed on a customer’s receipt slip.

VoucherConfirmation

Information about the voucher provision being confirmed. This object refers to a specific voucher which was previously successfully provisioned.

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.
tenders array[Tender] required An array of tenders used to pay for the transaction
voucher Voucher optional Information about the specific voucher being confirmed. This should at a minimum be the voucher serial number returned in the VoucherResponse so that the vendor can look up the voucher to be confirmed within the vendor’s system.

VoucherRequest

Information about the voucher provision request.

Name Type Required Default Restrictions Description
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.
amounts Amounts optional If the product identified by the product field is not a fixed price product then the amounts field indicates the value of the product referred to.
product Product required The product for which the voucher should be provisioned.
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.
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.

VoucherResponse

Information about the voucher provisioned.

Name Type Required Default Restrictions Description
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 the VoucherRequest.
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 Data to be printed on the slip in addition to the voucher instructions.
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.
amounts Amounts optional If the product identified by the product field is not a fixed price product then the amounts field indicates the value of the product in the response.
responseProduct Product optional The product for which the voucher was provisioned. This is assumed to be the product requested if this is absent.
voucher Voucher required The voucher provisioned if the vendor processed the request successfully.