Linking QR code scans and Payment Requests

In order to successfully process a QR code payment, it is required that the customer’s scan and a retailer’s request to tender are linked. This linking is performed by Electrum, which facilitates the aggregation of multiple QR payment partners and hence simplifies the point-of sale interface by obviating the need for knowing which partner will process the payment when initiating the transaction.

To enable linking, it is necessary for all paymentRequests and scanNotifications to contain the same transaction ID (tranId) to allow for them to be matched and the payment processed correctly. This transaction ID serves as a golden thread throughout the transaction flow and allows related transactions from Retailer and Partner to be correctly associated. It is thus imperative that the transaction ID is set correctly throughout the flow.

Below is a diagram with this transaction ID highlighted to better illustrate its use.

QR Code Structure

Organization of data

The structure of the QR code is based on a subset of the EMV QR specification as set out by EMVco.

The QR code is a string of data comprised of number data objects each containing three fields:

1. A Tag ID which indicates what sort of data it contains.
2. A length field which specifies exactly how many characters the third field is comprised of.
3. A value field in which the data is contained.

The format of the above fields is as follows:

1. The ID is a two digit numeric value ranging from ‘00’ to ‘99’
2. The length field is a two digit numeric value ranging from ‘01’ to ‘99’
3. The value field is an alpha-numeric string with a minimum length of 1 character and a maximum length of 99 characters.

Data objects themselves contain other data objects which also follow the conventions above.

Implementation

The data will always begin with a data object with ID ‘00’ this object will have a length of ‘02’ and will denote which specification version is being used. Currently the value field will contain a value of ‘01’.

Partner information will be contained in Tags with IDs ranging from ‘26’ to ‘51’ and will contain sub elements as per the below. It is possible for a QR code to contain the information for a number of partners, in which case a data object for each will be present.

• Sub Tag ‘00’ will contain a unique Partner identifier. This is a globally unique value through which a partner may be identified.
• Sub Tag ‘01’ will contain the unique transaction reference to be used for this scan.
• Sub Tag ‘02’ will contain the payment amount if provided in the getQrCode request.

Examples

Below is an example of when an Electrum QR Payment is the only payment instrument provided:

Payload: 00020126500010za.co.elec0132f82d7f64feea4f2ab24da94aaf5c2941

Breakdown:

00 02

01

26 50

00 10

za.co.elec

01 32

f82d7f64feea4f2ab24da94aaf5c2941

Below is an example of where both Electrum QR Payment and Masterpass are provided:

Payload: 00020126500010za.co.elec0132f82d7f64feea4f2ab24da94aaf5c294127260008za.co.mp01105169175130

Breakdown:

00 02

01

26 50

00 10

za.co.elec

01 32

f82d7f64feea4f2ab24da94aaf5c2941

27 26

00 08

za.co.mp

01 10

5169175130

Request ID Construction And Handling

Generation of UUIDs for payment authorisation request messages is an important step in the request process. The id field of a PaymentRequest is the single field guaranteed to always allow an entity to locate all messages pertaining to a payment request (as well as any subsequent related messages). It is therefore important that the ID value generated by a client is unique for that client. If you are developing a client implementation, please take note to generate IDs as random UUID’s, as defined for a variant 4 UUID by RFC 4122. These request identifiers must uniquely identify a request within your own client implementation. If possible, the client should check that the UUID generated for a message has not been previously generated. If the UUID has been used previously then the client should generate a new UUID. This process should be repeated as necessary until a unique UUID has been generated.

This specification acknowledges that since clients produce random UUIDs, there is a possibility that a client might repeat an ID for two independent messages of the same type if the client is unable to perform the above checks. Furthermore, independent clients may submit two distinct requests with the same UUIDs. Therefore, if you are developing a server implementation, take care to verify that a request to create a resource does not contain an ID that already exists in the system. All such requests must be declined with a status code of 400 and an ErrorType of DUPLICATE_RECORD.

Finally, if a client receives an HTTP 400 response with an ErrorType of DUPLICATE_RECORD, it is suggested that the client simply generate a new UUID for the request and resubmit the request with the new UUID.

UUID Matching

The Electrum QR Payment Partner Interface matches related messages primarily through the use of UUIDs. UUIDs are intended to uniquely identify a message across all client and server implementations of the service. Within any implementation of the Electrum QR Payment Partner Interface a given request UUID must be unique. This enables certainty that any subsequent response or advice message with the same request UUID does indeed refer to the prior request with that UUID.

Store-and-forward

To ensure that loss of transactional data is minimised, the Electrum QR Payment Partner Interface requires clients to store advice messages in persistent storage and keep them queued until a final status type is received. A final response is one of either the successful or failed status types. If the service is not responding, or responding with an unknown status type, advice messages shall be queued and the message at the head of the queue repeated regularly until a final status type is received. For high throughput systems it shall be acceptable to send several messages in parallel. Client and server systems in high throughput environments should therefore be prepared to process advice and advice response messages in any order.

The above applies to the following operations:

• Confirmation
• Reversal