Angaza Nexus
Premium open-source technology for the PAYG industry.
PAYG Manufacturers
Are you building a new PAYG product or want to add PAYG functionality to your product?
Integration Overview
Here is the process to develop a PAYG product:
- Specification
- Manufacturer reviews PAYG Requirements below.
- Manufacturer reviews Tamper Mitigation Strategies below.
- Manufacturer confirms the product will be designed to meet all requirements.
- Manufacturers who are new to product development or the PAYG industry, check out additional recommendations based on our 10+ years of industry experience.
- Development
- Manufacturer completes product design, development and validation. Angaza Embedded Solutions
- Manufacturer sets up factory process to provision PAYG units.
- QA
- Manufacturer or trusted third-party completes QA test procedure to validate product meets core PAYG requirements.
- QA Sign-Off
- Angaza signs off on final QA test results. This is required for any product to be sold directly on the Angaza platform.
- Note: The QA process is required in order to ensure your product is compatible with the Angaza platform and provides the best user experience for our customers. The QA Signoff documents can be found at the below link:
Nexus Keycode QA Signoff Template
The first sheet, “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. If a Nexus Keycode product successfully passes these tests, the device is able to be sold on Angaza.
PAYG Requirements
This table displays the 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). By integrating our Nexus Keycode solution, all of the Protocol Requirements will automatically be met!
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 Angaza generated unit number. | The unit number is the primary identifier used on Angaza platform by distributors and by end clients to make payments. It is also the identifier used by manufacturers on the Nexus 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 Angaza 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 Angaza IDs through Angaza’s Nexus API | Angaza maintains control over unit number generation to ensure uniqueness across manufacturers and products. This unit number is interoperable with other PAYG platforms. | R | |
| M3 | Manufacturer must use Angaza-generated secret key & provisioning data for Nexus and OpenPAYGO Keycode devices | This is to reduce error and issues of mismatch between physical device and provisioning data on Angaza 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 on Angaza 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 considers 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 | Points if strategy is used |
|---|---|---|
| Enclosure | PAYG enforcement electronics are inside enclosure | 2 |
| Enclosure | Enclosure is sealed shut or uses non-standard screws | 2 |
| Enclosure | Screws are hidden / not easily seen by end user | 1 |
| Electrical | Power source (battery / panel) is not directly compatible with outputs. I.e Battery with 6V nominal voltage and 5V and 12V output ports | 20 |
| 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. | 10 |
| Electrical | Device does not have function available to end user that disables PAYG enforcement for maintenence testing longer than 5 mintes | 5 |
| Detection | Device has ability to detect if enclosure was opened. (i.e sticker covering screw boss or electrical / photodiode switch) | 1 |
| Detection | Device has ability to detect if tamper has occured via usage data (i.e monitoring for usage while PAYG - disabled or other metric). | 1 |
| Detection | Device can alert remotely when tampering has occured (i.e IOT data communication back to server). | 1 |
| Detection | Device can further make payg enforcement more difficult to bypass upon tamper detection | 1 |
Each strategy has a number of points associated with it based on the strategy’s relative effectiveness in reducing the tampering payoff-effort ratio. Your product will be scored based on which strategies you’ve implemented and sorted into one of the following tiers. Gold, Silver and High Risk.
| Tier | Points |
|---|---|
| Gold | 25+ |
| Silver | 15 |
| High Risk | < 15 |
Your product’s risk level will be shared openly with distributors so please make necessary changes to improve your product’s tamper security.
Angaza Embedded Solutions
- Check out Nexus Keycode for our keycode protocol product.
- Check out Nexus Channel if you are selling bundles of products and are interested in managing and communication between products