Banking: payment continuity

// A minimal client for the wede REST API, used by the snippets below
export class WedeError extends Error {
  constructor(public status: number, public code: string, message: string) {
    super(message)
  }
}

export type Credential = { apiKey: string } | { token: string }

export async function wede(cred: Credential, method: string, path: string, body?: unknown) {
  const res = await fetch(`https://api.wede.pt${path}`, {
    method,
    headers: {
      ...('apiKey' in cred ? { 'x-wede-api-key': cred.apiKey } : { authorization: `Bearer ${cred.token}` }),
      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
    },
    body: body !== undefined ? JSON.stringify(body) : undefined,
  })
  const data = res.status === 204 ? null : await res.json().catch(() => null)
  if (!res.ok) throw new WedeError(res.status, data?.error ?? 'api_error', data?.message ?? `HTTP ${res.status}`)
  return data
}

export async function login(email: string, password: string): Promise<string> {
  const res = await fetch('https://api.wede.pt/v1/auth/login', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ email, password }),
  })
  const data = await res.json().catch(() => null)
  if (!res.ok) throw new WedeError(res.status, data?.error ?? 'api_error', data?.message ?? `HTTP ${res.status}`)
  return data.token
}

// Captures an operation for offline sync, with the capture time and the integrity checksum:
// SHA-256 of JSON.stringify(payload) + idempotency_key + offline_generated_at (see Sync)
export async function capture<T extends { idempotency_key: string; payload: Record<string, unknown> }>(event: T) {
  const offline_generated_at = new Date().toISOString()
  const bytes = new TextEncoder().encode(JSON.stringify(event.payload) + event.idempotency_key + offline_generated_at)
  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))
  const integrity_hash = [...digest].map(b => b.toString(16).padStart(2, '0')).join('')
  return { ...event, offline_generated_at, integrity_hash }
}

import { login, wede, WedeError } from './lib/wede'

const admin = { token: await login(process.env.WEDE_ADMIN_EMAIL!, process.env.WEDE_ADMIN_PASSWORD!) }

// The category id of "ATM and POS terminals" (code trm) in the banking vertical
const { data } = await wede(admin, 'GET', '/v1/catalog?vertical=banking')
const terminals = data[0].categories.find((c: any) => c.code === 'trm').id

const types = [
  { code: 'card_payment_confirmed', name: 'Card payment confirmed' },
  { code: 'agent_cash_in', name: 'Agent cash-in' },
  { code: 'agent_cash_out', name: 'Agent cash-out' },
]

for (const t of types) {
  try {
    await wede(admin, 'POST', '/v1/catalog/types', { vertical: 'banking', category_id: terminals, requires_teams: false, ...t })
  } catch (err) {
    // 409 conflict: the code already exists for this vertical, so the script is safe to rerun
    if (!(err instanceof WedeError && err.status === 409)) throw err
  }
}

import { wede, WedeError } from '../lib/wede'

export const server = { apiKey: process.env.WEDE_API_KEY! }

export async function confirmPayment(p: {
  txRef: string
  terminalId: string
  amountMinor: number
  currency: string
  zoneCode: string
}) {
  try {
    const res = await wede(server, 'POST', '/v1/events', {
      type: 'card_payment_confirmed',
      vertical: 'banking',
      priority: 'high',
      idempotency_key: `tx-${p.txRef}`,
      payload: {
        tx_ref: p.txRef,
        terminal_id: p.terminalId,
        amount_minor: p.amountMinor,
        currency: p.currency,
      },
      metadata: { zone_id: p.zoneCode },
    })
    await ledger.setWedeEvent(p.txRef, res.event_id) // your code
  } catch (err) {
    if (err instanceof WedeError && err.code === 'duplicate_event') {
      return // wede already has this payment: it is stored once and never counted twice
    }
    throw err
  }
}

import { capture } from './lib/wede'

export async function recordCashIn(txRef: string, amountMinor: number, customerRef: string) {
  const captured = await capture({
    type: 'agent_cash_in',
    vertical: 'banking',
    priority: 'high',
    idempotency_key: `tx-${txRef}`,
    payload: { tx_ref: txRef, amount_minor: amountMinor, currency: 'AED', customer_ref: customerRef },
  })
  await offlineQueue.push(captured) // your local store, unchanged
}

import { wede } from '../lib/wede'
import { server } from './payments'

export async function syncAgentQueue(captured: object[]) {
  for (let i = 0; i < captured.length; i += 500) {
    const { summary, results } = await wede(server, 'POST', '/v1/sync/batch', { events: captured.slice(i, i + 500) })

    for (const r of results) {
      const txRef = r.idempotency_key.replace(/^tx-/, '')
      switch (r.result) {
        case 'accepted':
        case 'duplicate':
          // wede holds exactly one event for this payment
          await ledger.setWedeEvent(txRef, r.event_id)
          break
        case 'rejected':
          await ledger.flagForReview(txRef, r.error_code) // your code
          break
      }
    }
    await ledger.recordSync(summary) // { total, accepted, duplicates, rejected }
  }
}

import { wede } from '../lib/wede'
import { server } from './payments'

await wede(server, 'POST', '/v1/webhooks', {
  url: 'https://payments.examplebank.ae/webhooks/wede',
  events: ['event.created', 'event.delivered', 'sync.completed', 'connectivity.degraded', 'connectivity.restored'],
  secret: process.env.WEDE_WEBHOOK_SECRET!,
  description: 'Payment continuity backend',
})

{
  "id": "5c2e8b1a-0d4f-4a7e-9c3b-2e1f0a9d8c7b",
  "event": "event.delivered",
  "created_at": "2026-09-27T07:12:44.918Z",
  "tenant_id": "b7a6c5d4-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
  "environment": "production",
  "data": {
    "event_id": "e1d2c3b4-a5f6-4e7d-8c9b-0a1b2c3d4e5f",
    "status": "completed",
    "channel": "rest_full",
    "attempts": 1
  }
}

import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'

const SECRET = process.env.WEDE_WEBHOOK_SECRET!
const TOLERANCE_SECONDS = 300 // your choice

function verify(header: string | undefined, rawBody: Buffer): boolean {
  if (!header) return false
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=', 2) as [string, string]))
  const t = Number(parts.t)
  if (!parts.v1 || !Number.isFinite(t)) return false
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false
  const expected = createHmac('sha256', SECRET).update(`${parts.t}.${rawBody.toString('utf8')}`).digest()
  const received = Buffer.from(parts.v1, 'hex')
  return received.length === expected.length && timingSafeEqual(received, expected)
}

const app = express()

app.post('/webhooks/wede', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verify(req.header('x-wede-signature'), req.body)) return res.status(401).end()

  const delivery = JSON.parse(req.body.toString('utf8'))
  if (await alreadyProcessed(delivery.id)) return res.status(200).end() // retries reuse the same id

  switch (delivery.event) {
    case 'event.created':
      await ledger.noteReceived(delivery.data.event_id, delivery.data.payload?.tx_ref)
      break
    case 'event.delivered':
      await ledger.noteDelivered(delivery.data.event_id, delivery.data.channel)
      break
    case 'sync.completed':
      await ledger.recordSync(delivery.data.summary)
      break
    case 'connectivity.degraded':
      await openResilienceIncident(delivery.data.zone_id, delivery.data.state)
      break
  }
  await markProcessed(delivery.id)
  res.status(200).end()
})

app.listen(3000)