Professor Vaulty mascot
$VAULTY
Docs/Partners·SDK·Dashboard
Developer Guides

API Reference

Server-to-server access for advanced integrations: create payment intents, query status, manage webhooks.

Base URL & authentication

Base: https://api.vaulty.world/v1
Header: Authorization: Bearer sk_live_xxx  (or sk_test_xxx in sandbox)
Keep secret keys on your server. Never ship them in client bundles.

Create a payment

curl -X POST https://api.vaulty.world/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "12.50",
    "token": "USDC",
    "ref": "order_8721",
    "redirect": "https://yourshop.com/thanks",
    "webhook": "https://api.yourshop.com/vaulty-hook"
  }'
{
  "id": "pay_01HV...",
  "status": "pending",
  "url": "https://pay.vaulty.world/p/...",
  "expires_at": "2026-06-10T12:30:00Z"
}

Query a payment

GET /v1/payments/pay_01HV...

Webhooks

  • POST to your configured URL on every status change.
  • Header X-Vaulty-Signature contains HMAC-SHA256 of the raw body.
  • Verify before trusting payload contents.
  • Respond 2xx within 10s or we retry with exponential backoff.
import { createHmac, timingSafeEqual } from "crypto";

const sig = req.headers["x-vaulty-signature"];
const expected = createHmac("sha256", process.env.VAULTY_WEBHOOK_SECRET!)
  .update(rawBody).digest("hex");
if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) throw new Error("bad sig");

Errors

  • 400 invalid_request — missing or malformed fields
  • 401 unauthorized — bad or missing API key
  • 404 not_found — resource doesn't exist or belongs to another partner
  • 409 conflict — duplicate ref already used
  • 429 rate_limited — slow down or contact us to raise limits
Next: Sandbox Testing