Panduan Majopay Gateway

1Sebelum mulai

Majopay Gateway tidak mengirim pesan langsung ke server kamu. Pesan yang cocok dikirim ke relay api-proxy.majopay.id, dan relay yang meneruskannya ke endpoint milikmu. Karena itu kamu perlu satu akun relay sebelum aplikasi bisa bekerja penuh.

Yang kamu butuhkan:

• Ponsel Android 10 atau lebih baru dengan koneksi internet.
• Sebuah endpoint HTTPS milikmu yang bisa menerima POST berisi JSON, misalnya webhook di aplikasi toko atau skrip di server kamu.
• Akun di api-proxy.majopay.id dengan satu service yang mengarah ke endpoint itu dan satu API key untuk service tersebut. Cara membuatnya ada di bagian 2.

Satu ponsel bisa memantau SMS dan notifikasi sekaligus, tetapi tiap aturan hanya memilih salah satu sumber.

2Menyiapkan relay di api-proxy.majopay.id

Semua langkah di bagian ini dilakukan dari browser, di komputer atau ponsel. Hasil akhirnya dua nilai yang nanti diketik ke aplikasi: nama service dan API key.

Daftar akun

1. Buka api-proxy.majopay.id/register.
2. Isi Nama (nama kamu atau nama usaha), Prefix service (huruf kecil, angka, dan tanda minus, misalnya tokoku), dan Email. Prefix akan menjadi awalan semua service milikmu dan tidak bisa diganti.
3. Ketuk Daftar. Token akun dikirim ke email kamu. Bentuknya uk_tokoku_…. Tidak ada kata sandi: token ini satu-satunya cara masuk, jadi simpan di tempat aman.

Masuk ke portal

1. Buka api-proxy.majopay.id/me/ui.
2. Tempel token dari email ke kolom token, lalu Masuk. Token disimpan di browser itu saja, jadi di perangkat lain kamu perlu menempelnya lagi.

Bagian Profil menampilkan prefix kamu dan sisa kuota. Akun yang mendaftar sendiri mendapat kuota 3 service.

Buat service yang mengarah ke endpoint kamu

1. Di bagian Service, ketuk Buat service.
2. Nama: ketik tanpa prefix, misalnya gateway. Portal menampilkan prefix terkunci di depannya, sehingga nama lengkapnya tokoku-gateway. Nama lengkap inilah yang nanti diisi sebagai API Key di aplikasi.
3. Template: pilih Tanpa template (isi target sendiri).
4. Target: alamat endpoint kamu, lengkap dengan https://, tanpa garis miring di akhir. Contoh https://toko.example.com/hooks/majopay.
5. Timeout: boleh dikosongkan, bawaannya 10 detik. Kalau endpoint kamu lambat, naikkan supaya pesan tidak dianggap gagal.
6. Auth header dan nilainya: opsional. Isi kalau endpoint kamu meminta header rahasia sendiri, misalnya Authorization dengan nilai Bearer …. Relay menambahkan header ini saat meneruskan, jadi rahasia itu tidak pernah ada di ponsel.
7. Aturan parameter: biarkan kosong supaya payload dari aplikasi diteruskan apa adanya. Ketuk Simpan.

Buat API key untuk service itu

1. Pada baris service tadi, ketuk Keys, lalu Buat key. Beri label, misalnya nama ponsel yang akan memakainya.
2. Key ditampilkan sekali saja. Bentuknya sk_tokoku-gateway_…. Salin sekarang. Kalau hilang, hapus key itu dan buat yang baru.

Kamu boleh membuat beberapa key untuk satu service, misalnya satu per ponsel. Menghapus satu key tidak mengganggu key lainnya.

Pasangkan ke aplikasi

Nilai ini diisi di layar Hubungkan ke Majopay saat aplikasi pertama dibuka, atau kapan saja lewat Pengaturan › Kredensial API. Lihat bagian 3.

Uji sebelum dipakai ponsel

Dari terminal, kirim satu pesan contoh persis seperti yang akan dikirim aplikasi. Kalau endpoint kamu membalas 2xx, relay sudah siap.

curl -X POST "https://api-proxy.majopay.id/tokoku-gateway/" \
  -H "x-app-key: sk_tokoku-gateway_a1b2c3…" \
  -H "Content-Type: application/json" \
  -d '{"sourceType":"SMS","senderNumber":"+628123456789","messageBody":"uji dari terminal"}'

Tombol Contoh di baris service juga membuat perintah curl yang sudah terisi, dan halaman pembuatan key menampilkan perintah yang sudah berisi key baru.

3Setup pertama kali

Saat pertama dibuka, aplikasi menampilkan layar Hubungkan ke Majopay.

1. Isi API Key dengan nama service lengkap dari portal, misalnya tokoku-gateway. Tidak boleh mengandung spasi.
2. Isi API Secret dengan API key service, bentuknya sk_tokoku-gateway_…. Nilai ini rahasia, jangan dibagikan.
3. Ketuk Simpan & lanjut.

Kalau belum punya kredensial, ketuk Lewati dulu. Aplikasi tetap bisa dipakai untuk membuat aturan, tetapi pesan yang cocok belum diteruskan.

Kredensial disimpan terenkripsi di ponsel dan tidak ikut backup Android.

4Memberi izin

Buka tab Pengaturan, bagian Izin akses. Ketuk Izinkan pada baris yang belum bertanda Aktif.

Izin SMS

1. Ketuk Izinkan pada baris Izin SMS.
2. Muncul dialog Sebelum kamu mengizinkan akses SMS yang menjelaskan data apa yang dibaca dan ke mana dikirim. Baca, lalu ketuk Setuju & lanjut.
3. Muncul dialog izin Android. Pilih Izinkan.

Akses notifikasi

1. Ketuk Izinkan pada baris Akses notifikasi.
2. Muncul dialog Sebelum kamu mengaktifkan akses notifikasi. Ketuk Setuju & lanjut.
3. Android membuka layar Akses notifikasi perangkat & aplikasi. Cari Majopay Gateway, nyalakan sakelarnya, lalu konfirmasi Izinkan.
4. Tekan tombol kembali untuk pulang ke aplikasi.

Semua izin bisa kamu cabut kapan saja lewat Setelan Android. Setelah dicabut, sumber yang bersangkutan berhenti dipantau.

5Membuat aturan

Aturan menentukan pesan mana yang diteruskan. Buka tab Aturan, lalu ketuk Buat aturan.

Tujuan pengiriman sudah ditentukan oleh service di relay, jadi tidak ada isian URL. Semua aturan di satu ponsel mengirim ke service yang sama. Ketuk Simpan.

Cara pencocokan bekerja

• Tanpa regex: pesan cocok kalau mengandung pola di mana pun, tidak peduli huruf besar atau kecil. Pola pesanan baru cocok dengan "Ada PESANAN BARU dari Andi".
• Dengan regex: pola dicocokkan sebagai ekspresi reguler, juga tidak peduli huruf. Contoh pesanan #\d+ cocok dengan "Pesanan #4821 sudah dibayar". Kalau regex tidak valid, aplikasi memperlakukannya sebagai teks biasa.
• Untuk notifikasi, yang dicocokkan adalah gabungan judul dan isi dalam bentuk judul: isi. Pola boleh mengacu ke judul, isi, atau keduanya.
• Untuk SMS, yang dicocokkan adalah isi SMS.

Contoh aturan

Mengelola aturan

• Sakelar di kartu aturan menyalakan atau mematikan aturan tanpa menghapusnya.
• Ketuk kartu untuk mengubah aturan.
• Tombol hapus di kartu menghapus aturan. Riwayat pesan yang pernah cocok tidak ikut terhapus.
• Bagian atas tab menampilkan Total aturan dan berapa yang Aktif.

6Membaca riwayat

Tab Riwayat mencatat semua pesan yang diproses, termasuk yang tidak cocok aturan. Ini tempat pertama untuk mengecek kenapa sebuah pesan diteruskan atau tidak.

Status pesan

Mencari dan memfilter

• Kotak Cari pesan, pengirim, atau aplikasi… mencari di isi pesan, pengirim, dan nama aplikasi.
• Tombol Filter riwayat membuka pilihan Aplikasi dan Pola isi pesan. Ketuk Terapkan, atau Reset filter untuk menghapus.
• Daftar dimuat bertahap. Ketuk Muat lebih banyak di bagian bawah untuk pesan lama.

Detail dan kirim ulang

Ketuk sebuah baris untuk melihat Isi pesan, Tujuan, Payload terkirim, dan Respons server. Kalau pesan cocok aturan tetapi statusnya Gagal, ketuk Kirim ulang ke webhook, lalu konfirmasi. Pesan dengan status Tanpa aturan tidak bisa dikirim ulang.

Menghapus

Geser baris ke samping untuk menghapus satu catatan riwayat. Penghapusan hanya berlaku di ponsel ini.

7Apa yang dikirim ke endpoint kamu

Setiap pesan yang cocok dikirim aplikasi sebagai POST dengan body JSON ke relay. Relay memeriksa API key, mencari service, lalu meneruskan pesan ke target service itu tanpa menyimpan isinya.

• Alamat yang dipanggil ponsel: https://api-proxy.majopay.id/<nama service>/, misalnya https://api-proxy.majopay.id/tokoku-gateway/.
• Header x-app-key berisi API Secret, yaitu API key service sk_….
• Relay meneruskan body dan Content-Type apa adanya ke target service, ditambah / di akhir. Target https://toko.example.com/hooks/majopay dipanggil sebagai https://toko.example.com/hooks/majopay/. Kalau kamu mengisi auth header di service, header itu ditambahkan di sini.
• Relay menunggu paling lama sesuai timeout service (bawaan 10 detik), lalu mengembalikan balasan endpoint ke ponsel tanpa diubah. Status di Riwayat mencerminkan balasan itu.
• Kalau gagal, aplikasi mencoba ulang sampai tiga kali dengan jeda 1 detik lalu 2 detik.

Balasan yang berasal dari relay

Kalau relay sendiri yang menolak, body balasannya JSON {"error": "…"} dengan kode berikut. Kode lain datang dari endpoint kamu.

Payload SMS

{
  "sourceType": "SMS",
  "senderNumber": "+628123456789",
  "messageBody": "Ada pesanan baru dari Andi",
  "timestamp": 1757740800000,
  "timestampIso": "2026-09-13T04:00:00Z",
  "receivedAt": 1757740801234
}

Payload notifikasi

{
  "sourceType": "NOTIFICATION",
  "packageName": "id.tokoku.app",
  "appLabel": "Tokoku",
  "title": "Pesanan baru",
  "text": "Andi memesan 2 barang",
  "postTime": 1757740800000,
  "extras": { },
  "timestamp": 1757740801234
}

Field extras berisi data tambahan dari notifikasi bila ada, misalnya teks panjang.

Relay hanya mencatat log teknis tiap panggilan: nama service, label key, method, path, kode status, dan lama proses. Isi pesan tidak pernah ditulis ke database relay.

8Notifikasi yang sengaja dilewati

Supaya riwayat tidak penuh sampah, aplikasi tidak memproses:

• notifikasi dari sistem Android dan Google Play Services,
• notifikasi yang terus berjalan seperti pemutar musik atau unduhan,
• notifikasi yang sama persis dalam jangka 5 detik,
• notifikasi dari Majopay Gateway sendiri.

9Layanan latar belakang

Setelah ponsel dinyalakan ulang dan ada aturan aktif, aplikasi memasang notifikasi diam Majopay Gateway Active. Notifikasi itu tanda pemantauan berjalan. Jangan dihapus paksa lewat pengaturan notifikasi.

10Pengaturan

• Kredensial API: lihat API Key, tampilkan atau sembunyikan Secret, Ubah, atau Hapus. Setelah dihapus, aplikasi kembali ke layar setup.
• Izin akses: status keempat izin, lihat bagian 4.
• Tentang aplikasi: versi, package, target SDK, dan tautan Kebijakan privasi yang terbuka di browser.
• Tips singkat: pengingat cara menguji SMS dan notifikasi.
• Alat debug: tombol Uji visibilitas aplikasi menampilkan aplikasi mana saja yang bisa dilihat pemilih aplikasi. Berguna kalau aplikasi yang kamu cari tidak muncul saat memilih filter.

Mengelola dari sisi relay

Beberapa hal diatur di portal api-proxy.majopay.id/me/ui, bukan di aplikasi:

• Ganti endpoint tujuan: Edit service, ubah Target. Ponsel tidak perlu disentuh.
• Hentikan sementara: nonaktifkan service. Ponsel tetap mencoba mengirim dan mencatat status Gagal (404) sampai service diaktifkan lagi.
• Cabut akses satu ponsel: hapus key ponsel itu di Keys. Ponsel lain dengan key sendiri tetap jalan.
• Ganti rahasia ke endpoint: Edit service, isi nilai auth baru. Nilai lama tidak pernah ditampilkan.

11Kalau ada masalah

12Privasi singkat

• Yang dibaca: nomor pengirim dan isi SMS, serta nama aplikasi, judul, dan isi notifikasi.
• Yang keluar dari ponsel: hanya pesan yang cocok aturan, lewat HTTPS ke relay api-proxy.majopay.id, lalu ke endpoint milikmu.
• Yang disimpan di ponsel: riwayat semua pesan yang diproses, aturan, dan kredensial terenkripsi. Riwayat tidak ikut backup Android.
• Yang disimpan di relay: akun kamu, daftar service beserta target, hash API key, dan log teknis tiap panggilan tanpa isi pesan. Relay berjalan di Cloudflare Workers dan D1.