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.

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

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

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

ErrorDetail

Describes a failed outcome of an operation.

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

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

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

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

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

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

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