Example: Payments Integration

Overview

This example illustrates ingesting payment state via /v1/record and handling payment provider webhooks.

REST Flow

import { CloudSDK } from "@syllecta/sdk-js";
 
const sdk = new CloudSDK({
  baseUrl: "https://cloud.syllecta.example",
  auth: { type: "bearer", token: process.env.SYLLECTA_API_KEY! }
});
 
const lock = await sdk.idempotency.checkOrLock({
  scope: "payments",
  key: "pay_123"
});
 
if (lock.cached) {
  return lock.record;
}
 
if (!lock.locked) {
  throw new Error(`Retry after ${lock.retryAfterMs}ms`);
}
 
await sdk.idempotency.save({
  scope: "payments",
  key: "pay_123",
  body: { status: "authorized", amount: 4200, currency: "usd" }
});

• This flow stores a payment status once and avoids duplicate processing.
• If another caller already created the record, you receive cached: true and reuse it.
• If the record is locked by another request, wait retryAfterMs and retry.
• Syllecta enforces plan limits automatically (returns 429 when exceeded).

Webhook Forwarding

1. Configure provider secret/callback via Backoffice UI.
2. Payments provider (Stripe/PayPal) sends events to /v1/webhooks/:provider.
3. Syllecta logs payload, dedupes, and forwards to your configured callback URL.

Example callback handler

app.post("/webhooks/syllecta", express.json(), async (req, res) => {
  const event = req.body;
  if (event.type === "payment.succeeded") {
    await orders.markPaid(event.data.orderId);
  }
  res.json({ ok: true });
});

Normalized events contain provider-agnostic fields, so the handler simply checks event.type and updates local records.

References

• API /record
• Guides → Idempotency
• Examples → Stripe
• Examples → Generic HMAC
• Examples → Shopify