spout

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.

Read webhook docs →

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.

StageEventTypical merchant action
Initializedcharge.initializeCreate pending order; show checkout link
Processingcharge.processingShow in-progress state; avoid double charge
Completedcharge.completedFulfill order / credit wallet on success
Failedcharge.failedMark 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 as live_webhook_url / testwebhook_url)
  • resciveInJson — prefer JSON body (API field spelling)
  • enableSendFromDashboard — allow dashboard-triggered sends
  • subscribed_events — only listed events are delivered (defaults to all four charge events)
  • enableForFailed — deliver charge.failed events
  • enableRetries — retry non-2xx responses
  • encryptPayload — AES-GCM envelope; decrypt with live_encryption_key / test_encryption_key from 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);
81

Customer 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

  1. Treat webhook deliveries as at-least-once; make handlers idempotent using spout_tx_ref or X-Spout-Delivery-Id
  2. Acknowledge with 200 OK before slow work
  3. Use test webhook URL + whsec_test_ in sandbox
  4. Rotate secrets with POST /api/v1/settings/webhook-secrets/rotate if leaked
  5. Prefer webhooks over polling /api/v1/transactions/initialize/:ref/:type for final status