Getting Started

Use REST against your SnapWallet API host. Server-side integrations should use organization API keys (see below). Use Dashboard → API keys to create keys and optional feature scopes. For every HTTP route and schema, open the API Reference tab (loaded from OpenAPI).

1. Configure base URL

# Base URL (no global /api prefix in default Nest bootstrap)
export API=https://your-api-host

2. Integration fetch helper (API key)

const API = process.env.SNAPWALLET_API_BASE_URL;
const SNAPWALLET_API_KEY = process.env.SNAPWALLET_API_KEY;

async function api(path, { method = 'GET', body } = {}) {
  const headers = {
    Accept: 'application/json',
    'api-key': SNAPWALLET_API_KEY,
  };
  if (body) headers['Content-Type'] = 'application/json';
  const res = await fetch(`${API}${path}`, { method, headers, body: body ? JSON.stringify(body) : undefined });
  if (!res.ok) throw new Error(await res.text());
  return res.status === 204 ? null : res.json();
}

3. Public pass creation

// Public issuance — POST /v1/snap (no API key; legacy /snap unchanged)
const res = await fetch(`${API}/v1/snap`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
  body: JSON.stringify({
    fullName: 'Jane Doe',
    phoneNumber: '27123456789',
    cardNumber: '6006123456789012',
    email: 'jane@example.com',
    passId: 'PASS_TEMPLATE_UUID',
    type: 'apple',
  }),
});
if (!res.ok) throw new Error(await res.text());

Authentication and entitlements

Integrations: send your organization API key on every protected request using api-key: <secret> (also accepted: x-api-key). Do not embed keys in browsers or mobile apps.

Console: the dashboard signs in with POST /auth/login and uses Authorization: Bearer <jwt>. JWTs are short-lived sessions, not a substitute for API keys on servers.

Entitlements: your subscription package defines the maximum feature set (keys such as ptm, gct, msp, etr). Each API key's scopesFeatures is intersected with the package.

// Browser / short-lived human session only — use API keys for servers
async function apiBearer(path, { method = 'GET', token, body } = {}) {
  const headers = { Accept: 'application/json', Authorization: `Bearer ${token}` };
  if (body) headers['Content-Type'] = 'application/json';
  const res = await fetch(`${API}${path}`, { method, headers, body: body ? JSON.stringify(body) : undefined });
  if (!res.ok) throw new Error(await res.text());
  return res.status === 204 ? null : res.json();
}

HTTP and errors

SnapWallet uses JSON bodies for REST. Send Content-Type: application/json on writes. Errors from Nest HttpException usually include statusCode, message, and error.

{
  "statusCode": 401,
  "message": "Incorrect username and password",
  "error": "Unauthorized"
}

{
  "statusCode": 403,
  "message": "Not Authorized. Contact your admin.",
  "error": "Forbidden"
}

Solutions

Solution mix is driven by your package and key scopes (see feature keys on each card). The published OpenAPI document lists versioned integration routes under /v1 (e.g. GET /v1/pass-template/organization/:id for templates).

Workflow examples

Distribution and enrolment combine templates, programs, and public issuance; see API Reference for all /v1 routes.

// Server integration — list org templates (versioned public API)
await api('/v1/pass-template/organization/ORG_UUID');

// Example: list gift cards for an organization (versioned public API)
await api('/v1/giftcard/organization/ORG_UUID');

Webhooks

Register outbound webhooks with POST /v1/trigger-events (same payload as the legacy route). Your delivery URL must be HTTPS. Managing triggers requires the etr feature. Configure from Dashboard → Webhooks or the REST routes in API Reference.

await api('/v1/trigger-events', {
  method: 'POST',
  body: {
    title: 'Notify CRM',
    description: 'Forward loyalty snaps',
    trigger: 'pubsub_snap_captured_event',
    delivery: 'https://example.com/webhooks/snapwallet',
    action: 'post_webhook',
    organizationId: 'ORG_UUID',
    isActive: true,
    data: {},
  },
});

// Your HTTPS endpoint receives delivery payloads from SnapWallet (shape depends on trigger).
// Verify authenticity using your shared secret or signing scheme once documented for your tenant.
app.post('/webhooks/snapwallet', express.json(), (req, res) => {
  console.log('Trigger payload', req.body);
  res.status(200).send('OK');
});