QR+ Master Specification (1.0.0)

Release Candidate 1.0.0-rc-6 approved for publication

Design objectives:

• Possess recognizable attributes to distinguish it from URI codes generated for other standards or applications.
• Enable extended lifetime Paylinks for sensitive Paylinks and indefinite lifetime links for non sensitive links.
• Allows deep linking on mobile devices, but cannot be used for direct web access (e.g. web based guest experiences).
• No human reproducibility requirement.
• No guest experience. Resist browser use.

The encoding consists of the following elements:

• uri scheme: The URI scheme for QR+ paylinks are qr-plus
• anchorDomain: The naming authority of the URI. One value for all Paylinks and used as authority for registration of mobile deep-linking apps. The anchor domain is the domain where the QR+ Registry for this network is hosted.
• flowTypeIndicator: Indicator to the flow type. Unreserved URI character string defined by the Registry Service.
• spIndicator: Indicator to the registered Paylink Provider who can resolve this Paylink. This encoding-specific indicator is issued by SARB as part of the Service Provider registration process and published by the Registry Service.
  • The mapping of spIndicator to the relevant Service Provider API host is managed by the Paylink Registry.
  • spIndicator 'xmpl': Reserved for example links. Never in active use.
• paylinkValue: A random string of at least 20 characters (RFC3986 'unreserved' characters; RegEx '^[A-Za-z0-9-._~]*$')

Further requirements:

1. The Paylink Provider MUST enforce Flow Type specific lifespan and quarantine/reuse requirements on the Paylink as prescribed by the Registry Service. (e.g. lifespan of less than 30 minutes for flow type prp-connected).
2. The generated paylinkValue MUST comply to the PLV Random Number Generation requirements
3. The encoding MUST only use URI Scheme, naming Authority and Path components as presented above (e.g. no Query or Fragment components).
4. The URI naming Authority MUST have a host component only (e.g. no Port or User Information)
5. The URI Path hierarchy MUST be exactly four

Design objectives:

• Enable high accuracy human reproducibility over voice and consumer keypad in use cases where actioning the Paylink involves manual consumer code verification, typing or copying.
• Targeted at Payee Presentment use cases where the Payer application is connected.
• Focussed on short Paylink lifespan use cases utilizing a small PLV number space.
• No guest experience.

The encoding consists of the following elements:

• First digit: (value 1 through 9) representing the flowTypeIndicator (e.g. 2).
  • Value '0': Reserved
  • Values published by the Paylink Registry Service
• Second and third digits: (value 00 through 99) the spIndicator identifying the registered Paylink Provider, within the Flow Type context, who can resolve this Paylink (e.g. 48).
  • Values 00 through 99: Mapping of spIndicator to Paylink Provider API host/url resolved by SARB NPU Paylink Registry.
  • Indicator 48: Reserved for example links. Never in active use
• Sequence of 9 digits: Representing the random paymentLinkValue (e.g., 439574307).
  • Values xxxx74xxx: Reserved for example links. Never in active use
• Last digit: The luhnDigit (https://en.wikipedia.org/wiki/Luhn_algorithm), calculated over preceding digits (e.g., 7).

Further requirements:

1. The Paylink Provider MUST enforce Flow Type specific lifespan and quarantine/reuse requirements on the Paylink as prescribed by the Registry Service.
2. The 9 digit paylinkValue MUST be generated in compliance of the PLV Random Number Generation requirements
3. Paylink entry applications MUST perform Luhn checks to detect entry but NOT remove the digit from the Paylink structure.
4. A separation character (e.g., '-') MUST be used in presentation formats to aid recognition and improve human reproduction accuracy, but implementations MUST NOT require users to enter the separation character.

Design objectives:

• Possess recognizable attributes to distinguish it from codes generated through other standards or applications.
• Allow for high accuracy reading with standard barcode scanning equipment (Code128 format) without the need for additional error correction.
• Targeted at Payer Presentment use cases where the Payer application is connected (e.g. PrP-1).
• Maximize PLV namespace for medium lifespan Paylinks.
• No guest experience.
• No human reproducibility requirement.

The encoding consists of the following elements:

• Encoding identifier: The first three characters 'ZA-' defining South African Paylink Encoding
• Character 4 - [digit]: (value '1' through '9') representing the flowTypeIndicator (e.g. '2').
  • Value '0': Reserved
  • Values published by the Paylink Registry Service
• Character 5 through 8 - [digits]: (value '0000' through '9999') the spIndicator identifying the registered Paylink Provider who can resolve this Paylink (e.g. '3713').
  • Reference data for mapping of spIndicator to the relevant Service Provider API host is managed by the Paylink Registry.
  • Paylink Provider '3713': Reserved for example links. Never in active use.
• Sequence of 19 characters [digits]: Random paylinkValue (e.g., '9436387216843892349').
  • Values 94xxxxxxxxxxxxxxxxxx: Reserved for example links. Never in active use

Further requirements:

1. The Paylink Provider MUST enforce Flow Type specific lifespan and quarantine/reuse requirements on the Paylink as prescribed by the Registry Service.
2. The generated paylinkValue MUST comply to the PLV Random Number Generation requirements

Design objectives:

• Enable cryptographic attestation of a Paylink value to improve the security posture in use cases where Paylink integrity is critical e.g. Payer not connected PrP use cases.
• Avoid shared-secret based mechanisms requiring secure secret distribution processes.
• No guest experience.
• No human reproducibility objective.
• Size constrained to allow for QR presentment on a consumer smartphone. (320px wide screen)

Below the Concise Data Definition Language (CDDL) specification of the Paylink in Concise Binary Object Representation (CBOR) format

paylink = [
  bstr .cbor payload, 
  signature 
]

payload = (
  kid:bstr .size 16,
  plv:bstr .size 12,
  p:uint .size 2, 
  ts:time,  ; 32bit uint seconds since 1970 - range to 2038
)

signature = bstr .size 64 

The encoding consists of the following elements:

• kid: The key Id of the cryptographic key used to sign the Paylink. The Paylink Provider must be able to correlate this value to the ECC pubic key and its owner for signature validation.
• plv: The Paylink Value of the Paylink (12 byte binary value).
• p: The Paylink Provider identifier UINT containing:
  • spIndicator: Lowest 12 bits (spIndicator = p mod 4096). Values published by the Paylink Registry.
  • flowTypeIndicator: Highest 4 bits (flowTypeIndicator = p div 4096). Values published by the Paylink Registry.
• ts: The unix timestamp in seconds since 1970-01-01T00:00:00.000Z when the Paylink was created.
• signature: The signature over the CBOR encoded payload block using ECDSA with P-256 curve (ES256)

Further requirements:

1. The Paylink Provider MUST enforce Flow Type specific lifespan and quarantine/reuse requirements on the Paylink and PLV as prescribed by the Registry Service. (e.g. lifespan of less than 5 minutes for prp-disconnected flow type).
2. The Paylink MUST be single use and terminated after first resolution even if the payment fails.
3. The Paylink Provider MUST resolve the Paylink only if the signature is successfully validated.
4. Paylink lifespan SHOULD be enforced using the generation timestamp.

PeP-1: Merchant Single Use in Physical Proximity

Description

This experience targets a Merchant (Payee) doing an on-screen presentment of a Paylink at a cash register. Once the Consumer (Payer) indicates their intent to pay using QR+, the cashier presents a single use Paylink linked to the current checkout session. The Consumer scans the Paylink with a mobile app. The Paylink may be presented, and link resolved, before the transaction details are available (check-in) or afterwards (immediate payment). When the transaction details are available, the PrSP does a Payment request and the PrSP prompts the Payer to approve the payment. After the payment is executed, both the Merchant (cashier) and the Consumer are notified of the successful payment.

Key Attributes

• Payee Presented: The Paylink is presented by the Merchant (Payee) to the Consumer (Payer).
• Single Use: The Paylink is linked to one checkout session and expires once payment is received or the session is abandoned.
• Allocated: The Paylink can be used by any Payer wanting to make payment for the current checkout session.
• Short-Lived: The Paylink has a short lifespan, covering only the duration of the checkout process. The Paylink can be generated speculatively in anticipation of a QR+ payment but must expire if not used.
• Payee Connected: The Payee application is connected and able to generate a dynamic Paylink to present at the POI.
• Payer Connected: The Payer application is connected and able to submit the Paylink, augment the transaction information, and approve the payment.

Use Case Diagram

Variants

1. Presentment at Payment Authorization: The Paylink is presented after basket totalization, before payment authorization once all transaction details are known.
2. Presentment at Item Scanning: The Paylink is presented during item scanning allowing the Consumer to 'check-in' for the session. Identity or loyalty actions can complete prior to the transaction amount being shared via a Payment Request at payment authorization.

Supported Paylink Formats

PeP-2: Merchant Multi Use

Description

This experience targets a Merchant (Payee) presenting a multi-use Paylink for payment in either physical proximity or online scenarios. One Paylink is used for multiple payments from different customers. The Merchant generates the Paylink and publishes it in either printed or static uri format. The Paylink metadata could include reusable transaction details, such as the amount at creation. At check-out, the Merchant presents the Paylink to the Consumer for payment. The Consumer actions the Paylink with a mobile app and may be prompted to augment transaction information (e.g., amount, payment reference) before approving the payment. After payment, the Payer is notified of the successful payment. An attempt must be made to notify the Payee of the payment but the Payee's availability to receive the notification is not essential.

Key Attributes

• Payee Presented: The Paylink is presented by the Merchant (Payee) to the Consumer (Payer).
• Multi Use: The Payee uses one Paylink to process multiple payments.
• Unallocated: The Paylink is generated prior to the payment interaction and the Merchant cannot perform payment allocation based on the Paylink metadata. Allocation must occur through payment reference information provided by the Payer.
• Long-Lived: The Paylink can have a long lifespan.
• Payee Connected or Not Connected: There is no requirement for the Payee application to be connected. The Payee can choose to not be connected while accepting payments, but will then not receive payment confirmations and will then need to accept the risks around claims of payment by the Payer.
• Payer Connected: The Payer application is connected and able to submit the Paylink, augment the transaction information, and approve the payment.

Use Case Diagram

Variants

1. Physical proximity: The Payer is in physical proximity and scans a printed QR with a mobile phone.
2. Remote: The Payer is presented with the Paylink through a static web page through QR and/or Web Click presentment.

Supported Paylink Formats

PeP-3: Merchant Single Context, Long Lifespan

Description

This experience targets a Merchant (Payee) presenting a single context Paylink for payment by a Consumer. The single context can be linked to one transaction or to one customer. The proximity can vary: it may be nearby, such as in the case of a restaurant bill, or distant, such as with mail invoicing. When generating the invoice or bill, the Merchant creates a Paylink with metadata referencing payment allocation information. The Paylink is shared with the intended Payer in physical (printed) or electronic (url or pdf) format. Upon receipt of the Paylink, the Consumer actions the paylink and augments and approves the payment.

Key attributes

• Payee Presented: The Paylink is presented by the Merchant (Payee) to the Consumer (Payer).
• Single or Multi Use: The Paylink may be intended for one or more payments by a known or unknown customer (e.g. printed on bill for restaurant payment => unknown Payers. Printed on utility statement => one or more payments for a known payer).
• Allocated: The Paylink is linked to a single context. Either to one payment(or bill) or one customer account.
• Medium or Long Lived: The lifetime of the Paylink may be fairly short, as in the case of restaurant payments, or long, as in the case of mailed invoices.
• Payee Not Connected: The Payee application must be connected during Paylink generation but is not required to be connected during payment.
• Payer Connected: The Payer application is connected and able to submit the Paylink, augment the transaction information, and approve the payment.

Use case diagram

Variants

1. Short lifespan: Near proximity which may allow for short Paylink lifespan.
2. Long lifespan: The Payer and Payee are not in proximity and requires a long lifespan Paylink.

Supported Paylink Formats

PeP-4: Online Merchant Single Use

Description

This experience targets an Online Merchant generating a single use Paylink for presentment on a website or mobile application for payment at checkout. The PeSP generates a single use Paylink with specific transaction metadata. The Consumer actions the Paylink by either using his camera on a QR code displayed on the PC screen or a button click. The Payer is presented with the transaction for confirmation and approves on the PrSP app.

Variants

1. PC Experience: When a Payment experience is pursued through a PC browser, a QR presentment format MUST be used. The Payer scans the QR with her mobile and chooses to action it through a PrSP app. A string presentment format MAY be used where the Payer will copy the Paylink to a PrSP App.
2. Mobile Experience: When a Payment experience is pursued on a Mobile browser or App, a web click presentment format MUST be used. A QR presentment format MAY be used in addition to the web click. The Payer clicks the link on the mobile and chooses to action the Paylink through a PrSP app. A string presentment format MAY be used where the Payer will copy the Paylink to a PrSP App.

Key Attributes

• Payee Presented: The Paylink is presented by the Online Merchant (Payee) to the Consumer (Payer) on a website or in a mobile app.
• Single Use: The Paylink is linked to one checkout session and expires once payment is received or the session is abandoned.
• Allocated: The Paylink can be used by any Payer wanting to make payment for the current checkout session.
• Short-Lived: The Paylink has a short lifespan, limited to the duration of the checkout process.
• Payee Connected: The Payee application must be connected during payment to get the Paylink from the PeSP.
• Payer Connected: The Payer application is connected and able to submit the Paylink and approves the payment.

Use Case Diagrams

Supported Paylink Formats

PeP-6: Person-to-Person Payment

Description

This experience targets a person-to-person payment scenario where the Payer (Consumer) and the Payee (Consumer) use their respective mobile applications to facilitate a payment transaction via a Paylink. The process involves generating, scanning, and processing a Paylink to complete the payment.

Key Attributes

• Payee Presented: The Paylink is presented by the Payee (Consumer) to the Payer (Consumer).
• Single or Multi Use: The Paylink MAY be single use or multi use.
• Allocated or Not Allocated: The Paylink may be linked to a specific context (allocation) or have an open context (no allocation)
• Short or Long Lived: The Paylink may have an open context and long lifespan or the Payee might prefer to limit the Paylink lifespan for a specific context
• Payee Connected for Paylink Generation: The Payee application may be not connected during the Paylink actioning and payment, but has to be connected during Paylink generation. The Payee must accept relevant risks if she chooses to be offline during payment.
• Payer Connected: The Payer application is connected and able to submit the Paylink, augment the transaction information, and approve the payment.

Use Case Diagram

Variants

1. Single-context Limited Lifespan Paylink: The Payee generates a Paylink to get a friend to pay her the coffee they just had. Both transaction details and allocation information provided.
2. Multi-use Paylink: The Payee generates a Paylink with long lifespan which anybody can use to send her money at any time. Payer provides allocation information.

Supported Paylink Formats

PrP-1: Merchant Single Use Connected

Description

This experience targets a Consumer (Payer) presenting a Paylink during checkout at a cash register. The Consumer presents the Paylink on their personal mobile device which has a live connection with their PrSP (is connected). The Paylink is actioned by the POS attendant during item scanning. After the Paylink is actioned, the Consumer is prompted on their mobile device to approve the payment. After approval is given, both the Merchant (cashier) and the Consumer are notified of the session outcome.

Key Attributes

• Payer Presented: The Paylink is presented by the Consumer (Payer) to the Merchant (Payee).
• Single Use: The Paylink is linked to one checkout session and expires once payment is received or the session is abandoned.
• Allocated: The Paylink is used by one Payer to make payment for the current checkout session.
• Short-Lived: The Paylink has a short lifespan covering only the duration of the payment process. The Paylink, and corresponding PLV, is generated only when the Customer intends to use it at a POI.
• Payee Connected: The Payee application is connected and able to submit the Paylink for resolution and provide the transaction details.
• Payer Connected: The Payer application is connected and able to communicate with the PrSP to generate the Paylink and approve the payment.

Use Case Diagram

Variants

1. Presentment at Payment Authorization: The Paylink is presented after basket totalization, before payment authorization once all transaction details are known.
2. Presentment at Item Scanning: The Paylink is presented during item scanning allowing the Consumer to 'check-in' for the session. Identity or loyalty requests can be processed prior to payment.

Supported Paylink Formats

PrP-2: Merchant Single Use Not Connected

Description

This experience targets a Consumer (Payer) presenting a Paylink during checkout at a cash register. The Consumer presents the Paylink on their personal mobile device which does NOT have a live connection with their PrSP at that time. The Consumer presents the Paylink as payment approval after till point total calculation and payment selection. The Paylink is actioned by the POS attendant at payment authorization only (not as check-in). The Consumer is NOT prompted on their mobile device, for transaction approval after the Paylink is actioned. The Merchant submits the Paylink and transaction details to the PeSP for processing. Both Consumer and Merchant is notified of flow outcome although the Consumer might only receive the notice once their connection has be reestablished.

Key Attributes

• Payer Presented: The Paylink is presented by the Consumer (Payer) to the Merchant (Payee).
• Single Use: The Paylink is generated on the Consumer device and includes a generation timestamp in addition to an offline PLV. Each PLV is only used once and the Paylink expires if not used within a reasonable time.
• Allocated: The Paylink is used by one Payer wanting to make payment for the current checkout session.
• Short-Lived: The Paylink has a short lifespan covering only the duration of the payment process. The Paylink is generated on the mobile device only when the Customer intends to use it at a POI.
• Payee Connected: The Payee application is connected and able to submit the Paylink and transaction details.
• Payer Not Connected: The Payer application is not connected but able to generate the Paylink on the mobile device using a PLV that has been acquired from the PrSP earlier. The Payer is therefor unable to give real time payment approval to the PrSP.

Use Case Diagram

Variants

1. None

Supported Paylink Formats