PayJoy Lock Documentation


Welcome to the product documentation for PayJoy’s Lock! This document provides an overview of the PayJoy’s Android app locking functionality. The PayJoy Lock allows supported Android devices to be automatically “locked” or “unlocked” based on a user’s account status. For more technical details, see our Lock API docs.

Key Concepts

These key terms will be referenced throughout the document:

Partner: A company that licenses PayJoy’s Lock to finance their customers.

Device Tag: A short sequence of letters beginning with ‘D’ that identifies a unique device. The Device Tag is used in device registration, for troubleshooting, and when specifying a device in an API call.

PayJoy-Locked Device: Devices in this state cannot access most functions other than using the PayJoy app and contacting emergency services. (See the Chapter “Restricted Functions” for details.)

PayJoy-Unlocked Device: Devices in this state are fully functional.

PayJoy-Secured Device: Devices which have the PayJoy mobile app installed and whose lock state can be controlled by PayJoy. There can only be one device admin on these phones.

Claiming a Device: Partners may claim a device using the PayJoy API to take control of a device. Once a device is claimed by a partner, that partner has the exclusive right to control the state of the device.

Fully Paid Device: Devices financed through PayJoy. Once a device is marked as fully paid, it is unlocked and the customer may request to remove the PayJoy application. Note: this does not apply to partners who do not report financing information to PayJoy.

“Rooted” Device: Rooting allows a user to modify software code on the device or install other software that the manufacturer wouldn’t normally allow. PayJoy does not allow this.

“Flashing” a Device: Refers to the process of placing the device into Download Mode and using software such as Odin to reinstall or update the device’s Android OS. This functionality is explicitly restricted by PayJoy.

“Bricked” Device: A device which has become unusable, usually because unauthorized actions incorrectly modified the device software to bring it to an unusable state. In practice, the user may not be able to recover from such a state. Note that PayJoy will not “brick” a device, but unauthorized attempts to flash the device, remove the PayJoy app, or otherwise tamper with the lock may place the device in this state.

Why PayJoy Lock

The PayJoy Lock’s key value to partners is encouraging users to pay on time, decreasing default rates and delinquency rates. The benefits of PayJoy Lock API include:

  • Patented and secure lock that can be loaded to encourage repayment
  • Blocks apps from running on a device if a certain ruleset is met, such as late payment
  • Instant unlocking available via APIs
  • Compatible with leading OEMs
  • Installed through a simple 1-2 minute process
  • Hosted on public cloud infrastructure (AWS)
  • Does not need to gather personally identifiable information (PII) in order to function.

Below is a handful of ways we’ve helped partners:

  • A partner provides financing to a customer using the customer’s device as collateral. The customer misses their monthly payment and the partner encourages repayment by locking the customer’s phone until payment is made.
  • A customer‘s device is stolen, but the device is secured by the PayJoy Lock. They contact their partner’s customer support who if they wish can lock the device to prevent device usage and data theft.
  • A customer purchases a device through a partner and the partner does not want the device being used by more than one person, so the device is locked to the SIM card contained during activation. A new SIM card is inserted and the device locks. Note: This is an optional customization feature of the PayJoy Lock.

How does the PayJoy Lock work?

When a partner chooses to lock a customer’s device, the customer’s ability to interface with their device is severely limited. A PayJoy-Locked Device restricts customers from doing the following:

  • Placing calls to numbers other than PayJoy or partner support or emergency services
  • Using or downloading apps, including “floating apps”
  • Accessing incoming calls or texts, including through WhatsApp
  • Installing “over the air” Android OS updates
  • Accessing any of the features or functionality of the device other than those listed below

A Locked Device will still allow:

  • Placing calls to emergency services
  • Placing calls to partner customer support
  • Accessing the PayJoy app to view account status and make a payment within the PayJoy app
  • Accessing any other whitelisted apps and numbers for incoming and outgoing calls (based on what the partner allows)
  • Accessing the device’s settings (except for those that might interfere with the PayJoy app)
  • Connecting to WiFi and Telcom data

The PayJoy app will never remove any documents, photos, or other data from the device, even when the device has been locked.

Types of Partners that We Work With

We support a range of partners across the world with a variety of operations:

Example: Small lending enterprises who operate with a limited or no tech team can sign up and activate locks manually via our Dashboard with no code needed within 1-2 days.

Example: A regional financing company who has a dedicated tech team can deploy our locks and integrate it seamlessly with their point-of-sale system via our Lock API.

You can see some of the partners that we work with on our website.

Requirements for a Partner to Deploy PayJoy Lock API

Partners need to have the following to deploy PayJoy Lock API:

  • Sign-up to get access to the PayJoy Lock API.
  • Developers to integrate the Lock API
  • An order management system that can activate lock on device
  • An automated backend ledger/payment system that will update lock status
  • WiFi or phone data is available where the device is activated

Current list of devices that PayJoy supports:

Open on Google Docs

PayJoy may be compatible with other devices from these OEMs — these are the ones we have tested.

Deployment of PayJoy Lock API

Technically our system allows a partner to launch as fast as their team is capable of, and a partner can get up and running within a day if they’re looking to use the Lock on a device. But integrating the Lock into a partner’s business systems at scale requires additional considerations and setup. We’re providing an end-to-end launch process to guide a partner’s technical team to integrate and launch Lock API. This may not all apply to all, but based on our experience with partners, these are the steps and estimated launch timelines to consider.

  • Day 1: Partner signs up for a free trial on our website
  • Day 1: Partner can test up to 4 devices and customize the following features of the Lock without any code needed:
    • In-app personalized company logo
    • Whitelisted numbers that users can access (such as Customer Support) when their Lock is enforced
    • Whitelisted apps that users can access when their Lock is enforced
    • Whitelisted IPs for direct server to server API calls
    • Payment Page URL which can embed the partner’s payment page so users can pay directly
  • Day 2-5: After being satisfied with the free trial, a Partner decides to purchase bundles of devices once their free trial is over
  • Day 5-10: Partner’s technical team uses the API docs to integrate and run end-to-end test to simulate the lifecycle of the app
    • Download
    • Install
    • Activate (‘claiming’ a device)
    • Remove
    • Payments received (VERY IMPORTANT: When not tested, and partners miss this step, their server does not notify us when a customer payment is received, which results in a terrible customer experience.)
  • Day 10-12: Partner sets up their Internal Tools integration. This will vary based on partners operations, but might include:
    • Steps to register customer devices
    • Setting up internal operations, roles, and permissions
    • Setting up backend ledger and payment options
    • Setting up device serviceability in case there is an issue eg; needs factory reset
  • Day 12-14: Partner tests their system’s process of activating phones and changing phone states from “Lock” to “Unlock” based on their business logic. Partner also conducts end-to-end automation testing to make sure their systems - backend ledger, payments, customer support, sales, serviceability - work seamlessly.
  • Day 14: Launch and starting using Lock as part of partner’s financing business.

Initial Setup for Your Customers

For every phone, a partner or a partner’s customer needs to follow PayJoy’s download instructions to install the PayJoy app on the device for the Lock to work properly. This installation should be done before a customer finalizes their loan process, although the exact step should be determined by the Partner and their loan process. Once the installation is complete, the PayJoy app will display this device’s unique Device Tag. The clerk will enter this Device Tag in their point-of-sale software which will complete activation of the PayJoy app.

IMPORTANT: If this activation process is not complete while installing the PayJoy app, the device is not considered Secured by PayJoy and the Lock won’t function properly.

Key User Interactions

Although users will not need to interact directly with the PayJoy lock under normal circumstances, there are some key points at which customers will interact with the PayJoy app.

  • During PayJoy app installation (during initial sale and setup process)
  • When the device has been locked by PayJoy and device functionality is restricted. In this scenario, the PayJoy app will open over any restricted apps or functionality the user attempts to access

Note: Note that in some cases, a device may not be locked by PayJoy for up to 24 hours following a change to the device’s account status. This is dependent on wifi/data connectivity, Android’s built-in task scheduling, and a variety of other factors.

  • When the device is unlocked by PayJoy and device functionality is restored
  • If the user attempts to remove the PayJoy app from the device before that device is ‘removable’. Please be aware that such action may cause the device to behave unexpectedly, and may “brick” the device. Attempts to tamper with the PayJoy lock are the most common cause of a PayJoy-Secured device becoming bricked.
  • When a customer completes their full loan payment, the PayJoy app will be updated to display a “Fully Unlocked” message to confirm that the device has been fully paid. Users will then be able to change the SIM card and/or phone number associated with the device.
  • If a user feels that their device has been locked by PayJoy in error, it is recommended to connect the device to a known working Wifi or carrier data connection and open the PayJoy app again as a first troubleshooting step. This will ensure that the device has received the customer’s most recent account status from PayJoy.
  • If the user is offline and has a payment, they can enter a code into the PayJoy app to make sure their Lock is updated with their latest expiration date.

Note: PayJoy-Secured devices will check in with PayJoy servers frequently to ensure that the device always has a user’s most up-to-date account information, and to obtain the latest security and stability enhancements directly from PayJoy. To ensure the best possible experience, customers should keep WiFi and/or carrier data enabled on their devices at all times.

Additional Information: Restricted Functionality While a Device is Secured by PayJoy

Some specific device functionality may be restricted on a PayJoy-Secured Device, even if the device is not currently locked. These restricted features will not impact most users, but a Partner or customer with specific technical requirements should read through these potential restrictions to make sure you understand our product.

These restrictions may vary depending on device OEM. Restricted functionalities include:

  • Flashing firmware to the device via Download Mode
  • “Rooting” the device or otherwise tampering with the Android OS
  • Attempting to tamper with the PayJoy lock or remove the PayJoy app prior to the user fully paying off the device. Note that any attempt to tamper with a PayJoy-Secured device may cause the device to perform unexpectedly, and may “brick” the device.
  • Installing certain apps which require device administrator permissions
  • Installing apps from sources other than the Google Play store
  • Installing certain apps intended to circumvent Android security measures
  • Accessing Android’s developer settings on the device
  • Completing a factory reset on the device

FAQ’s for Common Issues that Partners Encounter

How does PayJoy’s app interact with a partner’s mobile app? Is there any way that the two apps pass control to each other?

PayJoy’s app interactions with a partner’s app in these two ways: * The partner chooses to whitelist their own app so a user will be able to access it when the phone is locked * The partner chooses to embed their payments page into PayJoy’s Payments tab. If the Partner has a Payments page on their app, we recommend that they don’t also embed the payments page on PayJoy. If they choose to do both, they’re required to have a real-time ability to record the payment that prevents users from trying to pay on both apps.

Can partners whitelist the PayJoy app?

Partners often prefer to whitelist certain apps to keep their store employees from browsing Facebook, Youtube, and other sites. However, PayJoy activation requires an open network.

Solution: Because the partner needs to have an open network, they will need to take the approach of blacklisting certain services like FB, Youtube if they desire.

Does Lock API work with dual SIMs?

Yes. Our Lock API will now read any of the SIM slots in a device.

I encountered errors while entering the PayJoy device tag and order number for a customer

We have noticed that in some cases, there’s human error in entering order that prevents the device to be linked. This is dependent on how the partner has implemented their system, especially if it’s done manually. If the problem was a wrong IMEI in the system, a partner’s customer gets stuck with an error during PayJoy activation which doesn’t show a warning stating that the problem was the IMEI.

Another instance in which this happens is when using phones with dual SIM/IMEI and a different IMEI is being scanned by the store clerk. Please make your store clerks aware of this during training before launching PayJoy Lock on your phones.

Solution: Report the issue to PayJoy. PayJoy’s ops team will first check if there are any issues on PayJoy’s side by doing a demo activation. The ops team can also ask the engineering team if other partners are able to activate devices. If we find that it works, PayJoy will ask the partner to double check whether there are errors on their end.

Faulty Payments Received System (these issues are usually discovered a month post-launch)

Partner receives payment but there’s a break in informing PayJoy about the payment. The customer’s phone locks, and customers must go back to the store to tell the partner that they’re seeing errors due to payment policies. This becomes a terrible user experience, and most frequently occurs because of partner-side human errors.

Solution: During integration testing, partners should test their payment system to make sure it’s working properly. In the interim to help the partner, PayJoy can extend payments manually for a partner while the partner makes fixes to their payment system.

Is there a warranty process?

Partners need to have or build customer service tools - their customer service team should be able to remove the PayJoy app and complete a factory reset. This is a step most Lock API partners forget but is important to build. Once the partner takes in a customer’s phone, PayJoy’s support team can establish procedures with the retail partner on how to remove the app and do a factory reset, and create a clean state to ship to OEM to resolve warranty arrangement.

What happens when a customer changes their SIM card?

The four values that Lock API Partners input for a customer’s device are state, expiration, requiredPhoneNumber, and requiredSimNumber and it’s important to note that all of these values are optional. If you want a customer’s device to be locked to a new SIM or you don’t want a SIM number to be locked, you can do that by using the following API snippet into your internal customer support tools:

If you want to change a customer’s SIM card, just enter the new SIM number and new phone number associated with the SIM for requiredPhoneNumber and requiredSimNumber.

   "requiredPhoneNumber":"[new phone number]”",
   "requiredSimNumber":"[new SIM number]”"

If you don’t want a SIM number to be locked, just enter an empty string for both requiredPhoneNumber and requiredSimNumber. Below is an example for how you do it in the code (see highlighted lines):


What happens if a user is offline and needs to have their payment updated?

Our new Unlock Offline feature allows users to enter a code into the PayJoy app that will update their amount of credit and keep their phone from locking, no internet necessary. This feature is core to our social mission of enabling the world’s underbanked to access credit by designing with their contexts in mind.

How it works:
1. Via Lock API, a PayJoy partner requests a code for a customer who is currently offline.
2. The client sends the generated code to the user by a phone call, SMS, or other user-accessible way.
3. After receiving the code, the user enters it in the following dialogue box that appears in their PayJoy app’s home screen when we detect that the phone is offline.

For security measures, we accept 5 attempts daily per user’s device and will monitor any suspicious fraud activities.