Kembali ke Blog

Notifikasi pembayaran Stripe: push notification ke ponsel untuk setiap penjualan, tagihan gagal, dan sengketa

Notifikasi pembayaran Stripe: push notification ke ponsel untuk setiap penjualan, tagihan gagal, dan sengketa

Penjualan pertama hari ini adalah kabar yang ingin Anda dengar. Perpanjangan langganan yang gagal pukul 02.00 justru lebih penting, dan sengketa punya tenggat: jika Anda tidak merespons tepat waktu, Anda kehilangan dana tersebut. Stripe mengetahui ketiganya begitu kejadian itu terjadi. Anda baru tahu saat membuka Dasbor berikutnya.

Stripe sebenarnya punya notifikasi sendiri. Aplikasi Stripe Dashboard untuk iOS dan Android dapat mengirim push untuk pembayaran baru, pelanggan baru, pembayaran yang disengketakan, transfer yang sudah masuk, dan ringkasan harian, sementara Dasbor bisa mengirim email tentang peristiwa akun. Itu sudah mencakup banyak hal. Yang tidak diberikannya adalah kendali: Anda tidak bisa memilih redaksi pesannya, tidak bisa membuat invoice gagal lebih mencolok daripada penjualan, dan tidak bisa mengalihkan notifikasi dari sistem Anda sendiri ke aliran yang sama. Webhook dari Stripe ke Pocket Alert bisa melakukannya.

Yang Anda butuhkan

  • Akun Stripe dengan izin untuk membuat webhook (peran Administrator atau Developer).
  • Akun Pocket Alert, kunci API dari API Keys, dan aplikasi di ponsel iPhone atau Android Anda.
  • Untuk jalur kode: Node 20 atau yang lebih baru dan tempat publik untuk menjalankannya.

Level 1: tanpa kode

Stripe mengirim setiap peristiwa sebagai JSON, dan webhook Pocket Alert menerima JSON lalu menampilkannya melalui templat. Hanya itu infrastruktur yang dibutuhkan.

1. Buat satu webhook Pocket Alert per jenis peristiwa

Kuncinya adalah membuat satu webhook untuk setiap jenis peristiwa. Judul push selalu berbentuk Webhook <name>, jadi nama itulah yang muncul di layar kunci, dan setiap webhook punya prioritas default dan tombol aksinya sendiri. Paket Gratis menyertakan satu webhook, jadi mulailah dengan penjualan. Set lengkap empat webhook membutuhkan paket berbayar, yang sekaligus membuka tombol aksi.

Anda bisa membuat webhook di konsol pada Webhooks, yang mengatur nama, templat, dan prioritas default. Tombol aksi diatur melalui API, jadi cara tercepat untuk mengatur semuanya sekaligus adalah satu panggilan curl untuk setiap webhook:

export PA_KEY='YOUR_API_KEY'

curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'EOF'
{
  "name": "Stripe sale",
  "message": "%data.object.amount_total% %data.object.currency% from %data.object.customer_details.email% (%data.object.payment_status%)",
  "default_level": 0,
  "actions": "[{\"type\":\"view\",\"label\":\"Open in Stripe\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
EOF

Respons berisi slug url. URL penerima Anda adalah https://p4a.me/wh/<slug>, dan konsol juga menampilkannya. actions berupa string JSON, bukan array, sehingga tanda kutipnya di-escape.

Ulangi dengan isi berikut untuk tiga webhook lainnya:

{
  "name": "Stripe payment failed",
  "message": "%data.object.amount_due% %data.object.currency% failed for %data.object.customer_email%, attempt %data.object.attempt_count%",
  "default_level": 1,
  "actions": "[{\"type\":\"view\",\"label\":\"Open invoice\",\"value\":\"https://dashboard.stripe.com/invoices/%data.object.id%\"},{\"type\":\"copy\",\"label\":\"Copy pay link\",\"value\":\"%data.object.hosted_invoice_url%\"}]"
}
{
  "name": "Stripe dispute",
  "message": "%data.object.amount% %data.object.currency% disputed. Reason: %data.object.reason%",
  "default_level": 2,
  "actions": "[{\"type\":\"view\",\"label\":\"Open payment\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
{
  "name": "Stripe subscription",
  "message": "New %data.object.status% subscription: %data.object.items.data.0.price.unit_amount% %data.object.currency% per %data.object.items.data.0.price.recurring.interval%",
  "default_level": -1,
  "actions": "[{\"type\":\"view\",\"label\":\"Open subscription\",\"value\":\"https://dashboard.stripe.com/subscriptions/%data.object.id%\"}]"
}

Level berjalan dari -2 (senyap) hingga 2 (kritis). Pembayaran gagal berada di high, yang tetap lolos Fokus di iPhone. Sengketa berada di critical, yang tetap berbunyi meski tombol senyap aktif dan Jangan Ganggu menyala. Notifikasi kritis membutuhkan paket berbayar; di paket Gratis, notifikasi tersebut tiba sebagai high. Langganan baru berada di low: informasi yang bagus diketahui, tapi tidak perlu getar.

Tombol salin pada push pembayaran gagal menyalin halaman pembayaran invoice ke clipboard Anda, siap ditempel ke email "kartu Anda ditolak".

2. Tambahkan event destination di Stripe

Di Stripe Dashboard, buka Workbench, masuk ke tab Webhooks, lalu klik Create an event destination. Kemudian:

  1. Pilih Your account.
  2. Pilih payload Snapshot. Stripe sekarang merekomendasikan Thin untuk kode baru, tetapi event thin hanya membawa ID objek, sehingga templat tidak punya nominal atau email untuk ditampilkan. Snapshot mengirim objek lengkap.
  3. Pilih event, misalnya checkout.session.completed.
  4. Pilih Webhook endpoint sebagai jenis tujuan, lalu tempel URL https://p4a.me/wh/... yang sesuai.

Lakukan ini sekali untuk setiap webhook Pocket Alert, sehingga setiap event destination Stripe membawa satu jenis peristiwa ke satu URL:

Event StripeWebhook Pocket AlertJudul pushLevel
checkout.session.completedStripe saleWebhook Stripe saledefault
invoice.payment_failedStripe payment failedWebhook Stripe payment failedhigh
charge.dispute.createdStripe disputeWebhook Stripe disputecritical
customer.subscription.createdStripe subscriptionWebhook Stripe subscriptionlow

Stripe mengizinkan 16 event destination per akun, jadi empat sudah cukup.

Checkout atau PaymentIntents? Jika pelanggan membayar melalui Checkout atau Payment Links, gunakan checkout.session.completed. Jika Anda membangun formulir pembayaran sendiri, gunakan payment_intent.succeeded sebagai gantinya, lalu ubah templat menjadi %data.object.amount% %data.object.currency% %data.object.receipt_email% dan tombolnya menjadi /payments/%data.object.id%. Berlangganan keduanya akan menghasilkan dua push per penjualan, karena pembayaran Checkout memicu kedua event.

3. Uji coba

Buat pembayaran uji di sandbox, atau jalankan stripe trigger checkout.session.completed dengan Stripe CLI. Lalu buka webhook di konsol Pocket Alert: riwayatnya menampilkan setiap permintaan yang dikirim Stripe, lengkap dengan header, body mentah, pesan yang sudah dirender, dan status respons. Jika sebuah field tampil kosong, di situlah Anda melihat path mana yang salah.

Penjualan akan tampil seperti ini:

Webhook Stripe sale
4900 usd from [email protected] (paid)
[Open in Stripe]

Yang tidak bisa dilakukan templat

Pahami batasannya sebelum Anda mengandalkannya:

  • Nominal dalam satuan terkecil. Stripe mengirim 4900 untuk $49.00 dan 5000 untuk ¥5.000, karena yen tidak punya sen. Templat menyalin nilai apa adanya dan tidak bisa membaginya dengan 100. Anda cepat terbiasa membaca 4900 usd, tetapi jika ingin $49.00, gunakan Level 2.
  • Tidak ada verifikasi tanda tangan. Stripe menandatangani setiap permintaan dengan header Stripe-Signature. Pocket Alert tidak memverifikasi tanda tangan pihak ketiga; slug acak di URL adalah satu-satunya rahasia. Siapa pun yang mengetahuinya bisa mengirim "penjualan" palsu kepada Anda. Untuk notifikasi, ini merupakan gangguan, bukan pelanggaran keamanan, karena tidak ada pesanan yang terpenuhi. Tetap jaga URL tersebut tetap rahasia, dan gunakan Level 2 jika Anda memerlukan bukti bahwa push berasal dari Stripe.
  • Tidak ada kondisi. Templat tidak bisa mengatakan "hanya kirim push untuk penjualan di atas $500" atau "lewati mode uji". Penyaringan dilakukan di Stripe melalui event yang Anda pilih, atau di dalam kode.
  • Tombol Dasbor mengarah ke mode live. Objek uji berada di bawah dashboard.stripe.com/test/..., sehingga untuk event mode uji, tombolnya membuka halaman yang tidak ada. Sengketa dari Charges API lama tidak memiliki payment_intent, sehingga tombol itu mengarah ke tautan kosong.
  • Langganan hanya menampilkan harga pertama. items.data.0 adalah item baris pertama. Event hanya membawa ID pelanggan, bukan email.
  • Setiap event dihitung ke kuota harian Anda. Paket Gratis memiliki 50 pesan per hari. Lewat dari itu, Pocket Alert merespons 429, dan Stripe menganggapnya pengiriman gagal, lalu dalam mode live mencoba ulang hingga tiga hari.

Level 2: handler terverifikasi sederhana

Ketika Anda menginginkan format mata uang yang sesungguhnya, verifikasi tanda tangan, dan satu endpoint untuk semua event, letakkan sekitar enam puluh baris Node di antara Stripe dan Pocket Alert. Kode ini menggunakan library resmi Stripe untuk memverifikasi tanda tangan dan POST /v1/messages untuk mengirim push.

npm install express stripe
// server.mjs
import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

function money(minor, currency) {
  const fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency: currency.toUpperCase() });
  return fmt.format(minor / 10 ** fmt.resolvedOptions().maximumFractionDigits);
}

function toPush(event) {
  const o = event.data.object;
  switch (event.type) {
    case 'checkout.session.completed':
      return { title: `Sale ${money(o.amount_total, o.currency)}`, level: 'default',
        message: `${o.customer_details?.email ?? 'no email'} · ${o.payment_status}`,
        path: o.payment_intent ? `payments/${o.payment_intent}` : `customers/${o.customer}` };
    case 'invoice.payment_failed':
      return { title: `Payment failed ${money(o.amount_due, o.currency)}`, level: 'high',
        message: `${o.customer_email ?? o.customer} · attempt ${o.attempt_count}`,
        path: `invoices/${o.id}` };
    case 'charge.dispute.created':
      return { title: `Dispute ${money(o.amount, o.currency)}`, level: 'critical',
        message: `Reason: ${o.reason}. Evidence due ${new Date(o.evidence_details.due_by * 1000).toDateString()}`,
        path: `payments/${o.payment_intent ?? o.charge}` };
    case 'customer.subscription.created': {
      const price = o.items.data[0]?.price;
      return { title: 'New subscription', level: 'low',
        message: price?.unit_amount != null
          ? `${money(price.unit_amount, price.currency)} per ${price.recurring?.interval} · ${o.status}`
          : o.status,
        path: `subscriptions/${o.id}` };
    }
  }
  return null;
}

app.post('/stripe-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send(`Bad signature: ${err.message}`);
  }
  res.sendStatus(200);

  const push = toPush(event);
  if (!push) return;
  const dashboard = event.livemode ? 'https://dashboard.stripe.com/' : 'https://dashboard.stripe.com/test/';

  await fetch('https://api.pocketalert.app/v1/messages', {
    method: 'POST',
    headers: { Token: process.env.POCKETALERT_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: push.title,
      message: push.message,
      level: push.level,
      actions: [{ type: 'view', label: 'Open in Stripe', value: dashboard + push.path }],
    }),
  }).catch((err) => console.error('Pocket Alert:', err.message));
});

app.listen(process.env.PORT ?? 4242);
STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_... POCKETALERT_KEY=... node server.mjs

Detail yang penting:

  • express.raw menyimpan body sebagai byte. constructEvent membutuhkan permintaan persis seperti yang dikirim Stripe, dan parser body JSON akan merusak tanda tangan. Fungsi ini juga menolak event yang lebih dari lima menit, sehingga replay dicegah.
  • Handler membalas 200 sebelum memanggil Pocket Alert, karena Stripe menginginkan respons 2xx yang cepat. Kunci terbatas dengan akses baca sudah cukup untuk STRIPE_SECRET_KEY; kode ini tidak pernah memanggil API Stripe.
  • Intl.NumberFormat mengetahui jumlah desimal setiap mata uang, sehingga 4900 usd menjadi $49.00 dan 5000 jpy menjadi ¥5,000.
  • Flag livemode memilih path Dasbor yang tepat, sehingga event mode uji membuka halaman mode uji.

Di Stripe, buat satu event destination dengan payload Snapshot, keempat event, dan URL server Anda, lalu salin rahasia penandatanganan whsec_ dari halaman destination tersebut. Untuk menguji secara lokal, stripe listen --forward-to localhost:4242/stripe-webhook menampilkan rahasia yang bisa digunakan, dan stripe trigger invoice.payment_failed mengirim event uji yang sudah ditandatangani.

Hasilnya di ponsel Anda adalah push berjudul "Sale $49.00" dengan "[email protected] · paid" di bawahnya, serta sengketa yang membangunkan Anda dengan tenggat di dalam isi pesan.

Ingin penjualan dan pendaftaran ada dalam satu aliran? Kirim formulir pendaftaran Anda ke aplikasi yang sama dengan notifikasi pendaftaran, dan keduanya akan terbaca seperti sebuah corong.

Jika tidak ada yang masuk

  • Periksa Stripe terlebih dahulu. Buka destination di Workbench dan lihat tab Event deliveries. Respons 400 dengan "Invalid JSON" berarti sesuatu selain JSON Stripe mencapai URL tersebut. 429 berarti Anda mencapai batas harian.
  • Lalu riwayat webhook Pocket Alert. Jika permintaannya ada tetapi pesannya kosong di beberapa bagian, path templat tidak ada di event tersebut. Salin body dari riwayat dan periksa nama field-nya.
  • Payload thin secara tidak sengaja. Jika push menampilkan nominal kosong dan body di riwayat memiliki related_object alih-alih data, destination dibuat sebagai Thin. Buat yang baru dengan Snapshot.
  • Kesalahan tanda tangan di Level 2. Setiap destination punya rahasia whsec_ sendiri, dan rahasia sandbox berbeda dengan rahasia live. Pastikan juga tidak ada yang di hulu, seperti proxy atau middleware framework, yang mengenkode ulang body.

FAQ

Apakah ini menggantikan aplikasi Stripe Dashboard?

Tidak, dan memang tidak perlu. Aplikasi Stripe adalah tempat untuk refund, mencari pelanggan, atau memeriksa saldo. Pocket Alert memberi Anda peringatannya: redaksi, level prioritas, dan tombol Anda sendiri, dalam aliran yang sama dengan notifikasi lain dari server, CI, dan formulir.

Event mana yang layak dijadikan push?

Mulailah dengan empat yang di atas. invoice.paid adalah tambahan yang baik untuk perpanjangan SaaS, dan customer.subscription.deleted memberi tahu Anda tentang churn. Stripe menyarankan untuk berlangganan hanya ke event yang Anda gunakan, dan itu juga membuat ponsel Anda lebih tenang.

Bisakah saya mendapat satu push per hari alih-alih satu per penjualan?

Tidak dari webhook. Turunkan level webhook penjualan menjadi silent agar penjualan terkumpul di aliran tanpa suara, dan simpan high serta critical untuk event yang memerlukan perhatian Anda.

Apakah ini gratis?

Webhook Stripe tidak dipungut biaya. Paket Gratis Pocket Alert mencakup 50 pesan per hari pada satu perangkat, yang cukup untuk toko kecil. Notifikasi kritis yang menembus Jangan Ganggu tersedia di paket berbayar.

Buat akun gratis, tempel satu URL ke Stripe, dan penjualan berikutnya akan langsung masuk ke ponsel Anda.

Bagikan artikel ini