Definitions

AccountPayment

Model for an account-to-account payment method

Name	Type	Required	Restrictions	Description
type	string	required	[AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD, WALLET, QR]	The general method of payment used
name	string	optional		The specific method of payment used
amount	LedgerAmount	optional		Ledger amount of the payment
issuer	Institution	optional		The institution which is responsible for managing this payment method (e.g. the card issuer, the wallet provider, the token provider etc.)
pin	Pin	optional		The PIN associated with this payment method. Various PIN formats are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected in a response and will not be translated.
proxy	string	optional	maxLength:40	An alternative identifier for the customer's source of funds. Acts as a stand in for the customer identifier. E.g. a customer's MSISDN or email address.
proxyType	string	optional	[MSISDN, EMAIL, UNKNOWN]	An enumerated value describing the type of value used as the proxy.
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.

Address

Details of a customer's address

Name	Type	Required	Restrictions	Description
addressLine1	string	optional	pattern:^.{1,100}	First line of street address.
addressLine2	string	optional	pattern:^.{1,100}	Second line of street address (if required).
city	string	optional	pattern:^.{1,30}	The city where the owner is located. Note: if this field ever needs to be translated to another API with shorter fields, the field will be truncated from the right.
region	string	optional	pattern:[A-Z]{2}	The state or region where the owner is located.
country	string	optional	pattern:[A-Z]{2}	The owner’s resident country expressed as an ISO 3166-1 Alpha-2 code.
postalCode	string	optional	pattern:[A-Za-z0-9 -]{1,20}	The owner’s postal code.

Amounts

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

Name	Type	Required	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	Restrictions	Description
type	string	required	[AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD, WALLET, QR]	The general method of payment used
name	string	optional		The specific method of payment used
amount	LedgerAmount	optional		Ledger amount of the payment
issuer	Institution	optional		The institution which is responsible for managing this payment method (e.g. the card issuer, the wallet provider, the token provider etc.)
pin	Pin	optional		The PIN associated with this payment method. Various PIN formats are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected in a response and will not be translated.
proxy	string	optional	maxLength:40	An alternative identifier for the customer's source of funds. Acts as a stand in for the customer identifier. E.g. a customer's MSISDN or email address.
proxyType	string	optional	[MSISDN, EMAIL, UNKNOWN]	An enumerated value describing the type of value used as the proxy.
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

CardPayment

Model for card-based payments

Name	Type	Required	Restrictions	Description
type	string	required	[AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD, WALLET, QR]	The general method of payment used
name	string	optional		The specific method of payment used
amount	LedgerAmount	optional		Ledger amount of the payment
issuer	Institution	optional		The institution which is responsible for managing this payment method (e.g. the card issuer, the wallet provider, the token provider etc.)
pin	Pin	optional		The PIN associated with this payment method. Various PIN formats are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected in a response and will not be translated.
proxy	string	optional	maxLength:40	An alternative identifier for the customer's source of funds. Acts as a stand in for the customer identifier. E.g. a customer's MSISDN or email address.
proxyType	string	optional	[MSISDN, EMAIL, UNKNOWN]	An enumerated value describing the type of value used as the proxy.
posInfo	[PosInfo](#posinfo)	optional
pin	[Pin](#pin)	optional		The PIN associated with this card as either a clear PIN or an encrypted PIN in HEX format.
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.

CreateQrCodeRequest

A request from the merchant for a QR code to be generated. The QR code returned should be suitable to be displayed to a consumer to be scanned.

Name	Type	Required	Restrictions	Description
id	string	required		The randomly generated UUID identifying this request. This may be a variant 3 or 4 as defined 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 request.
client	Institution	required		Data relating to the sender of the request.
thirdPartyIdentifiers	array[ThirdPartyIdentifier]	optional		An array of identifiers which each identify the transaction within each entity’s system.
rrn	string	optional		This is a reference set by the original source of the request.
stan	string	optional		The System Trace Audit Number can be used to locate transactions across different systems.
amounts	Amounts	optional		The amounts pertaining to the QR code to be created.
customer	Customer	optional		Information detail pertaining to the customer.
qrProperties	QrProperties	optional		A collection of attributes that describe how a QR code is intended to be used for transacting.
paymentMethods	array[PaymentMethod]	optional		A list of payment methods with which the QR owner will accept payment. The paymentMethods specify the destination to which funds may be transferred when the QR code is scanned.

CreateQrCodeResponse

The response to a CreateQrCodeRequest which contains the specific code assigned by the QR code provider as well as the full QR code in EMVCo format.

Name	Type	Required	Restrictions	Description
id	string	required		The randomly generated UUID identifying this request. This may be a variant 3 or 4 as defined 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 request.
client	Institution	required		Data relating to the sender of the request.
thirdPartyIdentifiers	array[ThirdPartyIdentifier]	optional		An array of identifiers which each identify the transaction within each entity’s system.
rrn	string	optional		This is a reference set by the original source of the request.
stan	string	optional		The System Trace Audit Number can be used to locate transactions across different systems.
amounts	Amounts	optional		The amounts pertaining to the QR code to be created.
customer	Customer	optional		Information detail pertaining to the customer.
qrProperties	QrProperties	optional		A collection of attributes that describe how a QR code is intended to be used for transacting.
paymentMethods	array[PaymentMethod]	optional		A list of payment methods with which the QR owner will accept payment. The paymentMethods specify the destination to which funds may be transferred when the QR code is scanned.
tranId	string	required		The unique transaction identifier assigned by the QR code provider to this QR code. This value is also encoded in the QR code returned in the qrCode field. The QR code provider is responsible for ensuring appropriate uniqueness of the QR code for the appropriate period of time. No specific restrictions are placed on the format of the QR code (length, characters etc.) but implementors should consider the following aspects; *Length* - Longer QR codes require more detailed resolution on display screens and scanning devices and are also harder to scan. *Manual Entry* - While manual entry of QR codes is not explicitly supported by the QR Payments Service Interface, implementors may choose to support such fallback mechanisms if a QR code cannot be scanned. Longer and more complicated codes will be more susceptible to errors when inputted manually. This value must be provided in subsequent ‘notifyScan’ and ‘pay’ operations to link payments to specific Partners.
qrCode	string	required		The full set of data to be encoded in the graphical QR code. The data is provided in a Tag-Length-Value format as described in the EMVCo specification but is not a fully EMVCo compliant string e.g. Tags which are mandatory under the EMVCo specification may be omitted. The precise set of Tags to be populated in the QR code should be discussed and agreed upon by implementation partners.

Customer

A customer who ultimately requests a transaction be performed.

Name	Type	Required	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).
addressDetails	Address	optional		The customer’s address details.
profileId	string	optional		The customer’s profile ID. Used to uniquely identify a customer.

CustomerProvidedValuePrompt

Properties of a prompt that can be displayed on a customer's scanning application to capture a user-provided text value which can be used when performing actions associated with the data embedded in this QR code.

Name	Type	Required	Default	Restrictions	Description
label	string	required		maxLength:50	Label that will be displayed as prompt for the customer-provided value. This value should also uniquely identify the prompt and its associated value once captured.

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

Describes a failed outcome of an operation.

Name	Type	Required	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, ACCOUNT_ALREADY_SETTLED, INVALID_MERCHANT, DO_NOT_HONOR, DECLINED_BY_PARTNER, DECLINED_BY_ACQUIRER, DECLINED_BY_ISSUER, INSUFFICIENT_FUNDS, INVALID_CARD_NUMBER, CARD_EXPIRED, INVALID_TRAN_ID, PARTNER_UNKNOWN, NO_SCAN_RECEIVED, INVALID_ACCOUNT]	The type of error that occurred. This value should be used for programmatic handling of errors.
errorMessage	string	required	maxLength:40	A short description of the error. This value should be suitable for display to an operator.
detailMessage	object	optional		A free form detailed description of a particular failure condition may optionally be supplied. This information is intended for informational purposes only when investigating the cause of a failure.
providerErrorCode	string	optional		The error code returned by the service provider if available. 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 if available. 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 if available.
tranId	string	optional		The unique transaction identifier related to this transaction if available. This is the value returned in the tranId field of the CreateQrCodeResponse or the ScanNotification.

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

LedgerAmount

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

Name	Type	Required	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	Restrictions	Description
type	string	required	[AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD, WALLET, QR]	The general method of payment used
name	string	optional		The specific method of payment used
amount	LedgerAmount	optional		Ledger amount of the payment
issuer	Institution	optional		The institution which is responsible for managing this payment method (e.g. the card issuer, the wallet provider, the token provider etc.)
pin	Pin	optional		The PIN associated with this payment method. Various PIN formats are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected in a response and will not be translated.
proxy	string	optional	maxLength:40	An alternative identifier for the customer's source of funds. Acts as a stand in for the customer identifier. E.g. a customer's MSISDN or email address.
proxyType	string	optional	[MSISDN, EMAIL, UNKNOWN]	An enumerated value describing the type of value used as the proxy.
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	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	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

NotificationParameters

Some integrations that make use of this interface may support notifying recipients when QR data has been used to perform some action. For example, a recipient may receive a notification if a customer successfully makes a payment by scanning a QR code. This property contains details describing notifications that may be triggered by using this QR code. Note that this data may be omitted in lookup operation responses, as this data may be considered sensitive.

Name	Type	Required	Default	Restrictions	Description
recipients	array[NotificationRecipient]	optional			A list of entities that should receive notifications based on the use of a QR code.

NotificationRecipient

An entity that should receive notifications based on the use of a QR code. This model collects details about how to contact the recipient.

Name	Type	Required	Default	Restrictions	Description
emailAddress	string	optional		format:email	An email address where a recipient should receive a notification based on use of a QR code.
msisdn	string	optional		pattern:^+?[1-9][0-9]{1,14}	An MSISDN where a recipient should receive a notification based on use of a QR code. 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.

Originator

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

Name	Type	Required	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.
channelId	string	optional	maxLength:50	The ID that uniquely identifies the originator’s channel that this transaction was received through.

PaymentConfirmation

Confirm that a previous PaymentRequest has completed successfully at the POS. Where possible all optional fields should be supplied to ensure smooth processing. If optional fields are not present then processing may require retrieval of the original transaction leading to unnecessary processing overheads.

Name	Type	Required	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.
partner	Institution	optional		An echo of the value in the original PaymentRequest.
tranId	string	optional		An echo of the value in the original PaymentRequest.

PaymentMethod

Base model for all payment types

Name	Type	Required	Restrictions	Description
type	string	required	[AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD, WALLET, QR]	The general method of payment used
name	string	optional		The specific method of payment used
amount	LedgerAmount	optional		Ledger amount of the payment
issuer	Institution	optional		The institution which is responsible for managing this payment method (e.g. the card issuer, the wallet provider, the token provider etc.)
pin	Pin	optional		The PIN associated with this payment method. Various PIN formats are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected in a response and will not be translated.
proxy	string	optional	maxLength:40	An alternative identifier for the customer’s source of funds. Acts as a stand in for the customer identifier. E.g. a customer’s MSISDN or email address.
proxyType	string	optional	[MSISDN, EMAIL, UNKNOWN]	An enumerated value describing the type of value used as the proxy.

PaymentRequest

A request to effect a payment with a linked QR code. Such requests originate from the Merchant's system and are typically directed to the Partner for processing. If the Partner for a PaymentRequest is not known, then the PaymentRequest may be directed to an intermediate system which receives ScanNotification messages from Partners. This intermediate system is then responsible for identifying the correct Partner to which a PaymentRequest should be directed.

Name	Type	Required	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.
partner	Institution	optional		Data relating to the entity who will process the payment. This identifies the entity who provided the ScanNotification for the QR code associated with this PaymentRequest. This should be populated if known to aid in routing the PaymentRequest to the entity which provided the ScanNotification.
amounts	Amounts	required		The amounts pertaining to the transaction. Note that the requestAmount herein maybe be different to that submitted when the QR code was requested. This request amount describes the actual amount to be processed in the transaction.
tranId	string	required		The unique transaction identifier related to this transaction. Retailers must set this to the same value as that returned in the tranId field of the CreateQrCodeResponse that preceded this PaymentRequest. Partners may associate this PaymentRequest with the QR code whose ScanNotification they submitted with this value.
partnerPaymentToken	string	optional		A payment token received from the Partner in the ScanNotification. A Partner may provide such a value in the ScanNotification so that it is included in the PaymentRequest to the Partner. This field should be populated if known. A Partner may expect to receive this value in the PaymentRequest if it was provided in the ScanNotification.

PaymentResponse

The response to a successful payment with a linked QR code scan.

Name	Type	Required	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.
partner	Institution	required		Data relating to the entity who processed the PaymentRequest. This identifies the entity who provided the ScanNotification for the QR code associated with this payment.
tenders	array[Tender]	optional		An array of tenders used to pay for the transaction. This may be used to describe the payment which was effected as a result of the QR code scan e.g. the card detail ultimately used for the payment.
amounts	Amounts	required		The amounts pertaining to the transaction.
tranId	string	required		This value is echoed from the PaymentRequest.
partnerPaymentToken	string	optional		This value is echoed from the PaymentRequest.

PaymentReversal

Reverse a previous PaymentRequest. This may be due to a cancellation at the POS or because the original PaymentRequest failed or is in an unknown state. Where possible all optional fields should be supplied to ensure smooth processing. If optional fields are not present then processing may require retrieval of the original transaction leading to unnecessary processing overheads.

Name	Type	Required	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
partner	Institution	optional		An echo of the value in the original PaymentRequest.
tranId	string	optional		An echo of the value in the original PaymentRequest.

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

Name	Type	Required	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	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.

QrPayment

Model for QR-based payments. This payment method should be used when a QR code is presented for payment.

Name	Type	Required	Restrictions	Description
type	string	required	[AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD, WALLET, QR]	The general method of payment used
name	string	optional		The specific method of payment used
amount	LedgerAmount	optional		Ledger amount of the payment
issuer	Institution	optional		The institution which is responsible for managing this payment method (e.g. the card issuer, the wallet provider, the token provider etc.)
pin	Pin	optional		The PIN associated with this payment method. Various PIN formats are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected in a response and will not be translated.
proxy	string	optional	maxLength:40	An alternative identifier for the customer's source of funds. Acts as a stand in for the customer identifier. E.g. a customer's MSISDN or email address.
proxyType	string	optional	[MSISDN, EMAIL, UNKNOWN]	An enumerated value describing the type of value used as the proxy.
tranId	string	required		The unique transaction identifier related to this transaction. In QRs styled on the EMVCo specification, the tranId is embedded in sub-Tag 00 of the Electrum MAIT.
partnerPaymentToken	string	optional		A payment token received from the Partner.

QrProperties

A collection of attributes that describe how a QR code is intended to be used for transacting.

Name	Type	Required	Restrictions	Description
description	string	optional	maxLength:20	The description field is intended to be displayed to the person scanning the QR code to provide them with context for the QR and why it was created.
guid	string	optional		The value which, when embedded in an EMVCo QR code, identifies the provider of the QR code.
overPaymentAllowed	boolean	optional		Indicates whether or not the transaction against the QR may use an amount greater than the value in the `amount` field.
partPaymentAllowed	boolean	optional		Indicates whether or not the transaction against the QR may use an amount less than the value in the `amount` field.
customerProvidedValuePrompts	array[CustomerProvidedValuePrompt]	optional		Details for prompts that can be displayed to the customer by a scanning application. These prompts can be used to signal that the user can input their own custom text values when scanning a QR code. These values may then be used as part of the action that is initiated by scanning the code.
requestTip	boolean	optional		When a QR code is used for facilitating payment, this option can be used to indicate that a prompt for a separate tip amount should be displayed by the customer’s scanning application. This value is not required, so when this property is not specified, this value should be treated as `false`.
expiryDate	string	optional	format:date-time	The date and time at which the QR code expires at which point it may no longer be used to facilitate transactions. 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
notificationParameters	NotificationParameters	optional		Some integrations that make use of this interface may support notifying recipients when QR data has been used to perform some action. For example, a recipient may receive a notification if a customer successfully makes a payment by scanning a QR code. This property contains details describing notifications that may be triggered by using this QR code. Note that this data may be omitted in lookup operation responses, as this data may be considered sensitive.
qrLabel	string	optional	maxLength:50	This value can be used as an alternative means of referencing a QR code. It supports a potentially human-readable way to reference a QR code that may be easily recognised by the owner or users of the code.

RewardPayment

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

Name	Type	Required	Restrictions	Description
type	string	required	[AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD, WALLET, QR]	The general method of payment used
name	string	optional		The specific method of payment used
amount	LedgerAmount	optional		Ledger amount of the payment
issuer	Institution	optional		The institution which is responsible for managing this payment method (e.g. the card issuer, the wallet provider, the token provider etc.)
pin	Pin	optional		The PIN associated with this payment method. Various PIN formats are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected in a response and will not be translated.
proxy	string	optional	maxLength:40	An alternative identifier for the customer's source of funds. Acts as a stand in for the customer identifier. E.g. a customer's MSISDN or email address.
proxyType	string	optional	[MSISDN, EMAIL, UNKNOWN]	An enumerated value describing the type of value used as the proxy.
rewardCode	string	required	maxLength:40	A code used to recognise the reward programme

ScanNotification

A notification sent by the Partner indicating that the Partner received a scan of the QR code linked to the transaction ID. Any PaymentRequest with a matching tranId value should be forwarded to the Partner for processing.

Name	Type	Required	Restrictions	Description
id	string	required		The randomly generated UUID identifying this notification. This may be a variant 3 or 4 as defined 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
partner	Institution	required		Data relating to the entity whose customer scanned a QR code. PaymentRequest messages which have a matching tranId value should be be sent to the Partner for processing.
settlementEntity	Institution	optional		Data relating to the entity with whom the Merchant will settle the transaction. A Partner may provide this information if known at the time the QR code was scanned.
receiver	Institution	optional		Data relating to the entity which ultimately processes the request. A Partner may provide this information if known at the time the QR code was scanned.
thirdPartyIdentifiers	array[ThirdPartyIdentifier]	optional		An array of identifiers which identify the transaction within each entity’s system.
amounts	Amounts	optional		The amounts pertaining to the QR code which was scanned.
tranId	string	required		The transaction identifier encoded within the QR Code which was scanned. Any PaymentRequest with a matching tranId value should be forwarded to the Partner for processing.
partnerPaymentToken	string	optional		A payment token received from the partner in the ScanNotification. If supplied by the Partner then it will be echoed in the PaymentRequest to the Partner.

SlipData

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

Name	Type	Required	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	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	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.

WalletPayment

Model for mobile wallet payments

Name	Type	Required	Restrictions	Description
type	string	required	[AN_32_TOKEN, LOYALTY_CARD, CARD, ACCOUNT, REWARD, WALLET, QR]	The general method of payment used
name	string	optional		The specific method of payment used
amount	LedgerAmount	optional		Ledger amount of the payment
issuer	Institution	optional		The institution which is responsible for managing this payment method (e.g. the card issuer, the wallet provider, the token provider etc.)
pin	Pin	optional		The PIN associated with this payment method. Various PIN formats are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected in a response and will not be translated.
proxy	string	optional	maxLength:40	An alternative identifier for the customer's source of funds. Acts as a stand in for the customer identifier. E.g. a customer's MSISDN or email address.
proxyType	string	optional	[MSISDN, EMAIL, UNKNOWN]	An enumerated value describing the type of value used as the proxy.
walletId	string	required		The unique identifier of the wallet account making the payment.
walletPocket	[WalletPocket](#walletpocket)	optional		The pocket associated with this wallet from which the payment is to be made. Used to determine where to make a payment from when a wallet is split into different sections. When not provided, payment will be directly from the wallet and not a subsection of the wallet.

WalletPocket

Name	Type	Required	Default	Restrictions	Description
pocketName	string	required			The name given to this wallet pocket.
pocketId	string	optional			A programmatic ID that can be used to identify this pocket when the name is not enough