The Bridge (Webhooks)

The Bridge is a world-class webhook engine designed for the high-availability needs of Gambian fintech. It pushes payment status, settlement triggers, and reversal events directly to your server in real-time.

Event Life-Cycle

1. Payment Success: User completes a Wave or Bank transaction.
2. Dispatch: SamaPay constructs a cryptographically signed payload.
3. Delivery: Outgoing POST is sent to your configured "Bridge URL".
4. Verification: Your server validates the Sama-Signature and acknowledges (200 OK).

Advanced Implementation (Node.js)

const express = require('express');
const crypto = require('crypto');
const app = express();

const SAMA_WEBHOOK_SECRET = process.env.SAMA_WEBHOOK_SECRET;

app.post('/samapay/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const signature = req.headers['sama-signature'];
    const payload = req.body;

    // 1. Verify Platform Authenticity
    const hmac = crypto.createHmac('sha256', SAMA_WEBHOOK_SECRET);
    const digest = hmac.update(payload).digest('hex');

    if (signature !== digest) {
        return res.status(401).send('Invalid platform signature');
    }

    // 2. Process Business Logic
    const event = JSON.parse(payload);
    console.log(`Processing ${event.type} for Order: ${event.data.metadata.order_id}`);

    res.json({ received: true });
});

---

Testing Scenarios (Simulator)

---

Reliability Features

• Retries: If your server is down, we retry with exponential backoff for up to 24 hours.
• Idempotency: Every event includes a unique event_id to prevent duplicate processing.
• Payload Versioning: We use dated versions to ensure your integration never breaks unexpectedly.