Connect your platform to walletKit.

# Server-side secrets only — never ship these to a browser or mobile app.
WALLETKIT_API_URL=https://passera-service-production.up.railway.app
WALLETKIT_API_KEY=sk_live_...
WALLETKIT_TEMPLATE_ID=<template-id>
WALLETKIT_WEBHOOK_SECRET=whsec_...

// walletkit.mjs — server-side only. Node.js 18+ (built-in fetch).
const BASE_URL = process.env.WALLETKIT_API_URL;
const API_KEY = process.env.WALLETKIT_API_KEY;

export class WalletKitError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

export async function walletkit(path, { method = 'GET', body } = {}) {
  const response = await fetch(new URL(path, BASE_URL), {
    method,
    headers: {
      'X-API-KEY': API_KEY,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(15000),
  });

  // Every response uses one envelope: { success, data, meta?, error? }.
  const payload = await response.json();
  if (!response.ok || !payload.success) {
    const message = [].concat(payload.error?.message ?? 'walletKit request failed').join('; ');
    throw new WalletKitError(response.status, message);
  }
  return payload.data;
}

import { walletkit } from './walletkit.mjs';

// Creates the member's pass, or updates it if one already exists for this ID.
const pass = await walletkit('/passes/upsert', {
  method: 'POST',
  body: {
    externalUserId: 'member_4821', // your own stable member ID
    templateId: process.env.WALLETKIT_TEMPLATE_ID,
    wallets: ['apple', 'google'],
  },
});

// Store pass.id against the member. Send the browser only the links.
console.log(pass.id, pass.links);
// { public: 'https://…/public/passes/…', apple: 'https://…/apple', google: 'https://…/google' }

import { walletkit } from './walletkit.mjs';

const passId = process.env.PASS_ID;

// A unique reference makes retries safe: it is never applied to a pass twice.
await walletkit('/wallet-pass-points/earn', {
  method: 'POST',
  body: { passId, points: 10, reference: 'order_1042', reason: 'Purchase' },
});

const { balance } = await walletkit('/wallet-pass-points/' + passId + '/balance');
console.log('balance', balance);

// webhook.mjs — npm install express
import crypto from 'node:crypto';
import express from 'express';

import { acceptOnce } from './inbox.mjs'; // INSERT ... ON CONFLICT (event_id) DO NOTHING

// Accept the previous secret too while a rotation is activating.
const SECRETS = [
  process.env.WALLETKIT_WEBHOOK_SECRET,
  process.env.WALLETKIT_WEBHOOK_SECRET_PREVIOUS,
].filter(Boolean);

function isValidSignature(rawBody, header) {
  const received = Buffer.from(header || '');
  return SECRETS.some((secret) => {
    const digest = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
    const expected = Buffer.from('sha256=' + digest);
    return expected.length === received.length && crypto.timingSafeEqual(expected, received);
  });
}

const app = express();

// express.raw keeps the exact bytes walletKit signed. Do not JSON-parse first.
app.post('/webhooks/walletkit', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!isValidSignature(req.body, req.get('X-Webhook-Signature'))) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  if (req.get('X-Webhook-Id') !== event.id) return res.sendStatus(400);

  const isNew = await acceptOnce(event); // store durably, process asynchronously
  res.sendStatus(isNew ? 202 : 200);
});

app.listen(process.env.PORT || 4000);

POST /webhooks/walletkit
X-Webhook-Id: e61cb6a2-73c1-48da-9758-54c3ab809b8f
X-Webhook-Event: pass.created
X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body>

{
  "id": "e61cb6a2-73c1-48da-9758-54c3ab809b8f",
  "type": "pass.created",
  "apiVersion": "2026-09-01",
  "createdAt": "2026-09-11T02:39:12.690Z",
  "data": {
    "passId": "956e73b5-b674-400b-9340-3d0bd29bd196",
    "externalUserId": "member_4821",
    "templateId": "58ceb2ff-ba61-4deb-b645-6cd3d3042d75",
    "passType": "loyalty",
    "status": "active",
    "wallets": ["apple"]
  }
}

import { walletkit } from './walletkit.mjs';

// Issue a scoped delegation: this agent may act for this member, only for
// loyalty reward redemptions, only up to £100, and only for one hour.
const { token } = await walletkit('/api/v1/mandates/issue', {
  method: 'POST',
  body: {
    principalId: 'member_4821',       // the human — always the holder
    agentId: 'agent_concierge_01',
    authorizationDetails: [{
      type: 'pass_action',
      pass_class: 'loyalty',
      purpose: 'reward redemption',
      max_spend: 100,
      currency: 'GBP',
      approval_threshold: { spend: 50 }, // above this, the human is asked
    }],
    ttlSeconds: 3600,
  },
});

// Later, from the agent: spend within the mandate's own terms.
// Requests over max_spend are denied; between the threshold and the ceiling
// they come back as ESCALATE with an authReqId for the human to approve.
const result = await walletkit('/api/v1/mandates/enforce', {
  method: 'POST',
  body: {
    mandateToken: token,
    passClassId: 'loyalty',
    spend: 20,
    purpose: 'reward redemption', // must match what the mandate granted
  },
});

console.log(result.decision); // 'ALLOW' | 'DENY' | 'ESCALATE'

// decision: "ALLOW" — spend was within the mandate and under its threshold
{
  "decision": "ALLOW",
  "reason": "Pass successfully issued under mandate mnd_… bound to human principal member_4821",
  "mandateJti": "mnd_ede6563865e344f9b913cd2b35ddfb3f",
  "principalId": "member_4821",
  "agentId": "agent_concierge_01",
  "pass": { "id": "c5d417e6-…", "status": "active", "urls": { "…": "…" } },
  "auditHash": "91c8c766…"
}

// decision: "ESCALATE" — over the £50 approval_threshold, under the £100 ceiling
{
  "decision": "ESCALATE",
  "reason": "Request exceeds approval threshold. Escalation pushed to human principal.",
  "authReqId": "ciba_3a5f531145d542f792be775b9cac32eb",
  "auditHash": "23f2d414…"
}

// decision: "DENY" — over the mandate's own ceiling
{
  "decision": "DENY",
  "reason": "Requested spend (250) exceeds mandate ceiling (100)",
  "auditHash": "e7c469dd…"
}

// A retried request with the same mandate + same request details replays the
// stored outcome instead of re-evaluating — a retry loop cannot turn a
// stored "no" into a "yes".
{ "decision": "DENY", "reason": "…", "isReplay": true }

// Success
{ "success": true, "data": { ... }, "timestamp": "2026-09-11T00:00:00.000Z" }

// Success, paginated
{ "success": true, "data": [ ... ],
  "meta": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 },
  "timestamp": "2026-09-11T00:00:00.000Z" }

// Error — message is a string, or an array for validation errors
{ "success": false,
  "error": { "code": 400, "message": ["wallets must be an array"], "path": "/passes/upsert" },
  "timestamp": "2026-09-11T00:00:00.000Z" }