OpenMasjid Docs
Home
GitHub
Home
GitHub

Build a donation kiosk

What you need

Time: 2 hours for the first one, 30 minutes for each one after

  • OpenMasjidOS installed, with your Stripe account added.
  • An Android tablet, Android 8.0 or newer.
  • A Stripe Reader M2. Optional — see below.
  • A power socket near where the kiosk will live, and a charging cable.
  • A wall mount or a floor stand.

A kiosk is a tablet by the door running one app, full screen, that takes a tap of a card. Nobody signs in and nobody chooses anything except an amount.

Step 1 — Install the app on the tablet

  1. In OpenMasjidOS, install OpenMasjid Kiosk and press Open.
  2. Note the address it shows. Add /new to the end of it.
  3. On the tablet, open that address in the browser.
  4. Tap Download the kiosk app.
  5. Allow installing from that source when Android asks.
  6. Open the downloaded file to install it.
Result:

OpenMasjid Kiosk appears in the tablet's app list.

Step 2 — Pair the tablet with your server

  1. In the app's admin panel, go to Devices, then Add kiosk.
  2. It gives you a 6-digit code, valid for 10 minutes.
  3. On the tablet, open the kiosk app.
  4. Type the server address and the 6-digit code, then tap Pair.
Result:

The kiosk appears under Devices with live status: battery, whether it is charging, the reader, and its version.

Step 3 — Set the exit PIN

Do this before the kiosk goes on a wall.

  1. In the admin panel, open Devices and find this kiosk.
  2. Set its exit PIN.

To reach the maintenance screen later, tap the top-left corner 10 times within 3 seconds, then enter that PIN.

Step 4 — Connect the card reader

  1. Charge the reader. Hold its power button until the light comes on.
  2. Open the maintenance screen on the tablet.
  3. Find the Card reader section.
  4. Choose Bluetooth, USB, or Test reader.
  5. Tap Find a reader, and allow the permissions Android asks for.
  6. When your reader appears, tap Connect.
Result:

It says Reader connected and shows the battery level. Tap Return to kiosk.

Try it with no money and no hardware

Test reader is Stripe's simulator. It runs the whole donation flow with no reader attached and no real charge. Use it to check your amounts, your thank-you screen and your receipts before any hardware arrives.

Step 5 — Lock the tablet down

Without this, anybody can press Home and start browsing on your tablet. Everything here is done on the tablet.

  1. From the maintenance screen, tap Set as Home app and choose OpenMasjid Kiosk.
  2. Tap Open tablet Settings (for Screen pinning).
  3. Turn on Screen pinning, called App pinning on some tablets.
  4. Turn on Ask for PIN/pattern before unpinning.
  5. Set a screen lock, if the tablet does not have one.
  6. Back on the maintenance screen, tap Turn on shade lock (Accessibility) and enable it.
  7. Return to the kiosk.
Result:

The notification shade is blocked, Home and Recents are blocked, and Back does nothing. Getting out by hand needs the device PIN. The maintenance screen still opens behind your exit PIN.

Step 6 — Mount it and plug it in

Do not run the cable across a walkway. If the only socket is across a doorway, move the kiosk rather than taping a cable to the floor.

Day to day

What you want Where
Check a kiosk is alive Devices in the admin panel: battery, charging, reader, version
Update the app Maintenance screen, then Update app
Move it to another server Maintenance screen, then Re-pair
Check the reader's battery Devices, which shows its serial and charge

Checkpoint

The kiosk shows the giving screen. A tap of a real card takes a real donation, and it appears in your records. Pressing Home does not leave the app.

If something goes wrong

What you seeWhyWhat to do
No readers found, over Bluetooth.The reader is off or flat, or it was paired in Android’s Bluetooth settings, or Location is off.Charge it and power it on. Remove it from Android’s Bluetooth list. Turn Location on in quick settings. Then Find a reader again.
No readers found, over USB.A charge-only cable, or the Android permission was refused.Use a data cable, reseat it, and accept the USB permission prompt.
The reader keeps disconnecting.A low battery drops the connection.Charge the reader, and keep it within a metre of the tablet.
I cannot reach the maintenance screen.The taps were too slow, or in the wrong corner.Tap the top-left corner 10 times within 3 seconds, then enter the exit PIN.
Nobody knows the exit PIN.It was set and not written down.Change it in the admin panel under Devices. It applies to the tablet on its next connection.
A donor can press Home and leave the app.Screen pinning is not on, or the app is not the Home app.Redo step 5. Both settings are needed, not one.
On this page