Shieldz

Developers

A full API reference, error catalog, and webhook spec lives in SHIELDZ_PAYMENTS_FRONTEND_SPEC.md. This page is the 60-second tour.

Auth

Bearer API key in the Authorization header. Keys are sk_live_… or sk_test_…. Mint and revoke from the merchant dashboard.

Create an invoice

POST /api/v1/invoices
{
  "amount_usd_cents": 5000,
  "memo": "Order #1234",
  "expires_in_seconds": 1800,
  "idempotency_key": "ord_1234",
  "metadata": {"order_id": "1234"}
}

Response includes id (the unguessable public id), pay_url, status, expires_at. Share pay_url with your customer.

Webhook events

Every webhook is HMAC-SHA256 signed. Verify with X-Shieldz-Signature:

function verify(rawBody, sig, secret) {
  const [t, v1] = sig.match(/^t=(\d+),v1=([0-9a-f]+)$/).slice(1);
  if (Math.abs(Date.now()/1000 - +t) > 300) throw "stale";
  const expected = require("crypto").createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  if (v1 !== expected) throw "bad sig";
}

Test mode

Use sk_test_… keys to create simulated invoices. The dashboard exposes a "Simulate payment" button that fires a fake invoice.paid webhook to your endpoint with mode: "test". Useful for validating your webhook handler before real money flows.

Retries + idempotency

Webhook deliveries retry on non-2xx with the schedule [1m, 5m, 25m, 2h, 12h] — 5 attempts total, then dead. Your handler should idempotency-key by X-Shieldz-Delivery since retries are at-least-once.

Status codes