Dokumentasi NotivGo

1. Webhook: yang NotivGo kirim ke Anda

HP Anda mengirim POST ke URL webhook Anda setiap ada notifikasi yang cocok. Nominal diekstrak di HP, dan kiriman webhook berangkat langsung dari HP ke URL Anda — tidak lewat server kami.

POST https://webhook-anda.com/notivgo
Content-Type: application/json; charset=utf-8
X-Device-Id: dev_xxx
X-Timestamp: 1723800000
X-Nonce: 3f2a…
X-Signature: sha256=…
X-NotivGo-Event: notification.forwarded
X-NotivGo-Schema: 2
X-NotivGo-Attempt: 1
Idempotency-Key: evt_01H…

{
  "event_id": "evt_01H…",
  "device_id": "dev_xxx",
  "source": "notivgo",
  "package": "id.dana",
  "app_name": "DANA",
  "post_time": 1723799995000,
  "captured_at": 1723799995120,
  "amount": 150000,
  "direction": "in",
  "currency": "IDR",
  "title": "Dana masuk",
  "text": "Anda menerima Rp150.000 dari B***",
  "big_text": "",
  "sub_text": "",
  "summary_text": "",
  "ticker_text": "",
  "channel_id": "…",
  "event": "notification.forwarded",
  "schema_version": 2,
  "attempt": 1
}

Selain webhook, HP juga bisa mengirim ke Telegram (pesan ke chat/grup Anda) dan Google Sheets (baris baru lewat Apps Script). Atur di portal → Tujuan kiriman.

2. Isi kiriman (field)

Keputusan akhir "sudah dibayar" tetap di tangan Anda: cocokkan dengan mutasi resmi sebelum menyerahkan barang bernilai besar.

3. Verifikasi tanda tangan (WAJIB)

Jangan percaya isi request sebelum tanda tangannya cocok. Basis tanda tangan adalah timestamp.nonce.rawbody — pakai raw body, bukan hasil parse JSON, karena spasi sekecil apa pun mengubah hasilnya.

<?php
$raw   = file_get_contents('php://input');
$ts    = $_SERVER['HTTP_X_TIMESTAMP'];
$nonce = $_SERVER['HTTP_X_NONCE'];
$sig   = $_SERVER['HTTP_X_SIGNATURE'];

$want = 'sha256=' . hash_hmac('sha256', "$ts.$nonce.$raw", $WEBHOOK_SECRET);
if (!hash_equals($want, $sig)) { http_response_code(401); exit; }

// Tolak yang terlalu tua (anti replay) — balas clock_skew supaya HP mengoreksi jamnya.
if (abs(time() - (int)$ts) > 300) {
  http_response_code(401);
  header('Content-Type: application/json');
  echo json_encode(['error' => 'clock_skew', 'server_time' => time()]);
  exit;
}
// Lalu abaikan event_id yang sudah pernah diproses.

// Node.js (Express, body mentah)
const crypto = require('crypto');
app.post('/notivgo', express.raw({type: '*/*'}), (req, res) => {
  const ts = req.get('X-Timestamp'), nonce = req.get('X-Nonce');
  const want = 'sha256=' + crypto.createHmac('sha256', SECRET)
    .update(ts + '.' + nonce + '.' + req.body).digest('hex');
  const got = req.get('X-Signature') || '';
  if (got.length !== want.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want))) return res.sendStatus(401);
  const ev = JSON.parse(req.body);
  // … simpan ev.event_id, abaikan bila sudah pernah …
  res.sendStatus(200);
});

Secret webhook ada di portal → Webhook. Bisa dirotasi kapan saja; HP mengikuti otomatis lewat heartbeat (≤15 menit), tanpa pairing ulang.

4. Balasan & coba ulang

Idempotensi

Jaringan seluler bisa membuat satu event terkirim lebih dari sekali. Simpan event_id dan abaikan yang sudah pernah diproses — inilah pengaman agar pesanan tidak terhitung dua kali.

5. API QRIS dinamis (opsional)

Buat QR bernominal dari QRIS statis Anda lewat API. Dibayar per QR yang dibuat. API key dibuat di portal → Developer.

POST /v1/generate
Authorization: Bearer ngk_…
Content-Type: application/json

{"order_ref":"INV-001","amount":"150000","format":"payload"}

HTTP 201
{"generate_id":"gen_…","order_ref":"INV-001","qris_payload":"000201…6304ABCD","metered":true}

metered:false + HTTP 200 berarti ulang-kirim ref yang sama (tidak ditagih lagi).

6. API pesanan (pencocokan terkelola)

Daftarkan pesanan beserta nominalnya; saat HP melaporkan uang masuk bernominal sama dalam jendela waktunya, server menandai pesanan itu paid. Nominal kembar pada saat bersamaan tidak ditebak — ditandai untuk Anda tinjau di portal.

POST /v1/orders
Authorization: Bearer ngk_…
{"order_ref":"INV-001","amount":150000,"note":"Meja 4","expires_in":1800}

→ 201 {"order_ref":"INV-001","amount":150000,"status":"open","expires_at":1723801800}

GET  /v1/orders/INV-001          → {"order_ref":…,"status":"open|paid|expired|canceled","paid_at":…}
POST /v1/orders/INV-001/cancel   → {"order_ref":"INV-001","status":"canceled"}

expires_in dalam detik (0 = tanpa kedaluwarsa, maks 90 hari). Mengirim ulang order_ref yang sama dengan isi sama → 200 "duplicate":true; dengan nominal/catatan berbeda → 409. Batas 600 permintaan per menit per akun.

7. Kode galat API

Semua galat berbentuk {"error":"kode","message":"penjelasan"}.