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.
Recommended Integration Checkpoints
- Specification
- Review PAYG Requirements below.
- Review Tamper Mitigation Strategies below.
- Check out additional product recommendations based on our experience.
- Development
- Complete product design, development and validation.
- Set up factory process to provision PAYG units, including unique ID stickers.
- 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 |
x |
| 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.
- Enclosure: PAYG enforcement is difficult to access.
- Electrical Architecture: makes it difficult to bypass PAYG enforcement
- 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 |