Notifications
SpoutPay notifies merchants and customers when a payment moves through its lifecycle. Use webhooks for machine-to-machine updates, and email receipts for customer-facing confirmation.
Notification channels
Webhooks
Signed HTTP callbacks to your server for charge.initialize, charge.processing, charge.completed, and charge.failed. Best for fulfilling orders and updating ledgers.
Email receipts
After a charge completes, SpoutPay can email the customer and your business support address with amount, reference, and status.
Event pipeline
Pick which stages your integration listens to. Narrowing subscriptions reduces noise and keeps your handlers focused.
| Stage | Event | Typical merchant action |
|---|---|---|
| Initialized | charge.initialize | Create pending order; show checkout link |
| Processing | charge.processing | Show in-progress state; avoid double charge |
| Completed | charge.completed | Fulfill order / credit wallet on success |
| Failed | charge.failed | Mark order failed; notify customer (respects enableForFailed) |
Configure subscriptions
Authenticate with a dashboard JWT (Authorization: Bearer <token>). Create with POST /api/v1/settings/webhook; update with PATCH /api/v1/settings/webhook. For POST, live_url, resciveInJson, enableRetries, enableForFailed, and enableSendFromDashboard are required.
JSON body
1{
2 "live_url": "https://merchant.example.com/webhooks/spout",
3 "test_url": "https://merchant.example.com/webhooks/spout-test",
4 "resciveInJson": true,
5 "enableRetries": true,
6 "enableForFailed": true,
7 "enableSendFromDashboard": false,
8 "encryptPayload": false,
9 "subscribed_events": [
10 "charge.initialize",
11 "charge.processing",
12 "charge.completed",
13 "charge.failed"
14 ]
15}live_url/test_url— delivery endpoints (stored aslive_webhook_url/testwebhook_url)resciveInJson— prefer JSON body (API field spelling)enableSendFromDashboard— allow dashboard-triggered sendssubscribed_events— only listed events are delivered (defaults to all four charge events)enableForFailed— delivercharge.failedeventsenableRetries— retry non-2xx responsesencryptPayload— AES-GCM envelope; decrypt withlive_encryption_key/test_encryption_keyfrom API key creation (see webhooks)
Listen in your pipeline
Branch on event.type (also available as X-Spout-Event) after verifying the signature:
Full HMAC verify + optional AES decrypt samples in Webhooks:
1const express = require("express");
2const crypto = require("crypto");
3
4const app = express();
5const WEBHOOK_SECRET = process.env.SPOUT_WEBHOOK_SECRET; // whsec_live_... or whsec_test_...
6const ENCRYPTION_KEY = process.env.SPOUT_ENCRYPTION_KEY; // enc_live_... or enc_test_...
7
8function verifySignature(rawBody, signatureHeader, secret, toleranceSec = 300) {
9 if (!signatureHeader || !secret) return false;
10 const parts = Object.fromEntries(
11 signatureHeader.split(",").map((p) => {
12 const [k, ...rest] = p.trim().split("=");
13 return [k, rest.join("=")];
14 })
15 );
16 const t = Number(parts.t);
17 const v1 = parts.v1;
18 if (!t || !v1) return false;
19 if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
20
21 const expected = crypto
22 .createHmac("sha256", secret)
23 .update(`${t}.${rawBody}`)
24 .digest("hex");
25
26 try {
27 return crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
28 } catch {
29 return false;
30 }
31}
32
33function decryptEncrypted(encrypted, encryptionKey) {
34 const key = crypto.createHash("sha256").update(encryptionKey).digest();
35 const decipher = crypto.createDecipheriv(
36 "aes-256-gcm",
37 key,
38 Buffer.from(encrypted.iv, "base64")
39 );
40 decipher.setAuthTag(Buffer.from(encrypted.tag, "base64"));
41 const pt = Buffer.concat([
42 decipher.update(Buffer.from(encrypted.ciphertext, "base64")),
43 decipher.final(),
44 ]);
45 return JSON.parse(pt.toString("utf8"));
46}
47
48// IMPORTANT: use raw body — do not use express.json() before this route
49app.post(
50 "/webhooks/spout",
51 express.raw({ type: "application/json" }),
52 (req, res) => {
53 const rawBody = Buffer.isBuffer(req.body)
54 ? req.body.toString("utf8")
55 : String(req.body);
56 const signature = req.headers["x-spout-signature"];
57
58 if (!verifySignature(rawBody, signature, WEBHOOK_SECRET)) {
59 return res.status(401).send("invalid signature");
60 }
61
62 const envelope = JSON.parse(rawBody);
63 const event = envelope.encrypted
64 ? decryptEncrypted(envelope.encrypted, ENCRYPTION_KEY)
65 : envelope;
66
67 res.status(200).send("ok");
68
69 // process asynchronously after ack
70 switch (event.type) {
71 case "charge.completed":
72 // fulfill order using event.data.spout_tx_ref
73 break;
74 case "charge.failed":
75 break;
76 default:
77 break;
78 }
79 }
80);
81Customer email notifications
When a charge reaches a terminal state, SpoutPay sends a receipt-style email to the customer address on the transaction and your compliance support email where available. The message includes business name, amount, reference, status, and masked card details when present.
Webhooks remain the source of truth for automation — do not rely on email alone to fulfill orders.
Best practices
- Treat webhook deliveries as at-least-once; make handlers idempotent using
spout_tx_reforX-Spout-Delivery-Id - Acknowledge with
200 OKbefore slow work - Use test webhook URL +
whsec_test_in sandbox - Rotate secrets with
POST /api/v1/settings/webhook-secrets/rotateif leaked - Prefer webhooks over polling
/api/v1/transactions/initialize/:ref/:typefor final status