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

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

To reach the maintenance screen later, tap an empty part of the screen 10 times within 3 seconds, then enter that PIN. A tap that a button or the number pad already used does not count, so entering an amount never opens it by accident.

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. Choose OpenMasjid Kiosk.
  2. On the Shade lock (Accessibility) row, tap Open the setting.
  3. In Android Settings, open Accessibility, then Installed apps.
  4. Enable OpenMasjid Kiosk — shade lock.
  5. Return to the kiosk.
Result:

The navigation bar is hidden, so there is no Home or Recents button to press. Back does nothing. The notification shade shuts again if a donor pulls it down. The kiosk starts itself after a power cut. 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

Collecting at an event, on a volunteer's phone

A wall kiosk is for the entrance. For a dinner, a bazaar or a collection round, there is a second app: OpenMasjid Mobile Donations. It runs on a volunteer's own Android phone. It uses the same server and the same card reader, and only the server ever records a donation.

  1. On the phone, open your server address with /new on the end.
  2. Download the Mobile Donations app.
  3. Pair it with a 6-digit code from Devices, the same way as a kiosk.
Result:

The volunteer can take cards. With remote access on, they can do this from anywhere, without joining the masjid's network.

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 they landed on a button.Tap an empty part of the screen 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.The kiosk is not the tablet’s Home app.Open the maintenance screen and tap Set as Home app. Choose OpenMasjid Kiosk.
On this page