Angaza Nexus


Open-source technology for the PAYG industry.

PAYG Integration Recommendations

Are you building a new PAYG product or want to add PAYG functionality to your product?

Angaza does not directly support new PAYG product development, and completing this process does not mean that Angaza can integrate your product with the Angaza PAYG software platform. However, here are some recommendations for how you might successfully integrate PAYG functionality.

  1. Specification
  2. Development
    • Complete product design, development and validation.
    • Set up factory process to provision PAYG units, including unique ID stickers.
  3. QA
    • Complete a thorough QA procedure to validate product meets every core PAYG requirement.
    • Consider adapting this Nexus Keycode QA Template that we’ve made available.

The first sheet in that QA template, “Definitions”, defines terms used throughout the tests, such as the difference between “PAYG Enabled” and “PAYG Unlocked”, or the difference between “ADD_CREDIT” and “SET_CREDIT” tokens.

The second sheet, “Requirements Traceability”, outlines specific requirements which are being tested, and by which tests.

The remaining sheets test different aspects of the product integration.

PAYG Requirements

This table displays typical core requirements for PAYG products. “R” is must-have. (These will be tested during QA process). “N” is nice to have. (These are strongly recommended). All of the Protocol Requirements are met by Nexus Keycode.

Device & Packaging

ID Requirement Reason R / N Met with Nexus Keycode
D1 Product & packaging must bear a visible label that contains human readable & machine readable platform-generated unit number. The unit number is the primary identifier used by distributors and by end clients to make payments. It is also the identifier used by manufacturers on, e.g., an Angaza API. R  
D2 Labels must be waterproof and legible after use of weak solvents e.g. 90% isopropyl alcohol and common cleaning agents. Sticker needs to be durable across the lifetime of the device. R  
D3 Device packaging meets any platform branding requirements. Co-marketing and brand recognition. N  

Manufacturing Processes

ID Requirement Reason R / N Met with Nexus Keycode
M1 Before shipment, product must be in a PAYG DISABLED state. (Locked / No Credit) Reduce stock theft; Angaza platform assumes this starting state. R  
M2 Manufacturer must generate unit IDs through platform API Platforms maintain control over unit number generation to ensure uniqueness across manufacturers and products. This unit number may be interoperable with other PAYG platforms. R  
M3 Manufacturer must typically use platform-generated secret key & provisioning data This is to reduce error and issues of mismatch between physical device and provisioning data on platform. R  
M4 Manufacturer must provision product (Assign unit number, secret key, and any other provisioning data) prior to shipment to distributor This is to reduce error and issues of mismatch between physical device and provisioning data platform. R  

User Interface

ID Requirement Reason R / N Met with Nexus Keycode
UI0a Product must have a mechanism for receiving credit updates. (i.e keypad, remote, GSM or remote communication).   R  
UI1 Product must include distinct UI element to display PAYG state (enabled / disabled). For ideal user experience to understand when payment is required. R  
UI2 If product does not have UI (i.e LCD) to show keypresses and allows user to edit digits, >10s between individual keypresses before keycode entry times out. For ideal user experience especially for users who may have trouble reading keycode while entering. R  
UI3 Product must include UI element to show
* Keycode applied (updated PAYG credit)
* Duplicate keycode
* Invalid keycode
* Keypress rejected
* Keypress accepted
* GSM Sync in progress (GSM only)
For ideal user experience and for Angaza support to assist in debugging. R  
UI4 UI display must differentiate between invalid keycode and duplicate keycodes When debugging credit issues, the first step in debugging is to re-enter previous keycodes to make sure no keycodes were missed. R  

User Interface - GSM Only

ID Requirement Reason R / N Met with Nexus Keycode
UI0b Products receiving credit updates over GSM should have a backup method (i.e keypad or remote) for network outage or coverage issues. GSM network outages or connectivity issues have been common, the user should still be able to access product. N  
UI5 If product has GSM, device must have method for user to access credit changes immediately (I.e force sync button) For best user experience to immediately apply credit after payment. R  

PAYG Keycode Protocol

ID Requirement Reason R / N Met with Nexus Keycode
TP1 Protocol must have a way to ADD CREDIT on the device. This credit must add a relative amount of credit (i.e 5 days), not convey an absolute real world date. The amount added must accumulate with existing credit. Most common usecase of Angaza platform and paygo systems R x
TP3 Device must able to recognize and apply ADD CREDIT keycodes that are older (at least 10 previous) or newer (at least 10 ahead) than the most recently applied keycode. Ease of customer experience in case a keycode was generated and skipped. User should still be able to get credit that was paid for. R x
TP2 Protocol must generate keycodes that are unit specific (other than a SHORT TEST keycode which may be universal) Prevent tampering or misuse of product R x
TP5 Protocol must have a way to SET credit on the device to a specific amount. This amount will replace the existing credit (even if unlocked) and not accumulate like the ADD credit. This method should also not allow previously generated and unentered keycodes to affect the credit state. Set Credit = 0 : Used by distributors when device requiring service are returned.

Other Set Cret : May be used if a device is in an unknown credit state to return device and platform in sync.
R - Set to 0
N - Other values
TP8 Any ADD_CREDIT or UNLOCK keycodes entered into an UNLOCKED device must not have any effect   R x
TP11 Device must have a universal keycode that can unlock device for < 5 minutes, not more than 128 times / day. Universal test keycodes are used by distributors for incoming quality checks and in field demos. The keycode must not provide too much access to product for risk of giving free usage to user. R x
TP12 ADD_CREDIT and SET_CREDIT keycodes must be capable of conveying between 0 and 180 days of PAYG credit, in increments no larger than 1 day.   R x
TP13 Device must be capable of receiving enough unique unit-specific keycodes to last device lifetime. To enable distributors to set up daily payment plans for >3 years R x
TP17 If device PAYG credit can be updated by entering a keycode as well as by another method, such as connecting to a remote server through a wireless link, to affect the same PAYG credit change as the keycode, then it shall not be possible to update the credit with one method and then receive additional credit by updating with the other method.   R x
TP18 An “UNLOCK” keycode should make any previously unapplied keycodes invalid. This is to prevent a user from accidentally entering an older keycode that was skipped and re-locking a device that should have unlimited credit. R x

PAYG Credit Tracking

ID Requirement Reason R / N Met with Nexus Keycode
PC1 Device must be able to enable and disable product functionality based on the PAYG state. For enforcement of loan. R  
CT1 Device shall keep track of PAYG credit with > 2% accuracy.   R  
CT3 Device PAYG timekeeping clock/counter shall actively run and decrement PAYG credit continually, without interruptions (24/7).   R  
CT4 Device PAYG credit shall decrement at a constant time-based rate, independent of the actual product use/discharge rate.   R  
CT5 Device PAYG timekeeping shall not track ‘negative/overdue’ credit, and shall stop decrementing credit at zero (0) credit remaining.   R  
CT6 Device PAYG timekeeping clock/counter must continue to run and decrement PAYG credit for at least 168 hours after user-facing outputs disable due to a ‘low battery’ state.   R  
CT10 Nonvolatile memory shall be persisted across power loss and reset events   R  
CT12 Clock source shall not be end-user accessible or modifiable User shall not be able to modify the PAYG credit without authorization R  

Tamper Mitigation Strategies

All PAYG security strategies can be defeated with enough effort. It is your responsibility to control this risk in your product.

Angaza recommends three layers of tamper risk mitigation: 1) Physical Enclosure 2) Electrical Architecture 3) Tamper Detection. We’ve listed strategies you can implement in your product in each layer.

  1. Enclosure: PAYG enforcement is difficult to access.
  2. Electrical Architecture: makes it difficult to bypass PAYG enforcement
  3. Detection: Product able to detect tampering or misuse of product
Layer Strategies
Enclosure PAYG enforcement electronics are inside enclosure
Enclosure Enclosure is sealed shut or uses non-standard screws
Enclosure Screws are hidden / not easily seen by end user
Electrical Power source (battery / panel) is not directly compatible with outputs. I.e Battery with 6V nominal voltage and 5V and 12V output ports
Electrical Device does not have a way for user to bypass payg enforcement via jumper cable connection. An attacker should have to solder to make a secure connection at a minimum.
Electrical Device does not have function available to end user that disables PAYG enforcement for maintenence testing longer than 5 mintes
Detection Device has ability to detect if enclosure was opened. (i.e sticker covering screw boss or electrical / photodiode switch)
Detection Device has ability to detect if tamper has occured via usage data (i.e monitoring for usage while PAYG - disabled or other metric).
Detection Device can alert remotely when tampering has occured (i.e IOT data communication back to server).
Detection Device can further make payg enforcement more difficult to bypass upon tamper detection