Build payments into your own stack

Quickstart

Three calls take you from nothing to a paid order. Everything below runs in the sandbox, where you can settle a payment yourself without touching a chain.

1. Raise an invoice

Amounts are strings so nothing is lost to floating point, and they are denominated in your pricing currency — not in crypto. Velt converts at the moment the shopper picks a rail.

curl -X POST https://api.velt.example/v1/invoices \
  -H "authorization: Bearer velt_sandbox_xxx" \
  -H "content-type: application/json" \
  -H "idempotency-key: 7f3c1d90-invoice-001" \
  -d '{
    "customer": "Helio Hosting",
    "email": "ap@helio.host",
    "amount": "2400.00",
    "currency": "USD",
    "dueInDays": 7
  }'

2. Send the customer to checkout

The response carries a paymentUrl. Redirect to it, drop it in an email, or embed it in an iframe with ?embed=1 and listen for postMessage status updates. The shopper picks an asset, the rate locks for twenty minutes, and a one-time deposit address is minted.

3. Fulfil on the webhook

Do not fulfil on a redirect back to your site — a shopper can close the tab, and a chain payment can arrive minutes later. Fulfil on order.paid, which fires once the payment has the confirmations that rail requires.

// Express, using the official Node SDK
import { Velt } from "@velt/sdk";

const velt = new Velt({ apiKey: process.env.VELT_API_KEY });

app.post("/webhooks/velt", express.raw({ type: "*/*" }), (req, res) => {
  const event = velt.webhooks.verify(
    req.body,                          // the raw body, not the parsed object
    req.header("x-velt-signature"),
    process.env.VELT_WEBHOOK_SECRET,
  );

  if (event.type === "order.paid") {
    fulfil(event.data.sourceId);       // your invoice or link id
  }

  res.sendStatus(200);                 // 2xx stops the retries
});

Authentication

Send your key as a bearer token on every request. Keys are server-side only: anything that reaches a browser is compromised, and a leaked key can move money.

authorization: Bearer velt_live_xxx

A key is bound to one environment when it is minted and cannot act outside it. That boundary is enforced on our side, so a sandbox key pointed at production data fails closed rather than doing something surprising.

Create and revoke keys in the dashboard under Developers. Revocation is immediate. Rotate rather than share: a key identifies an integration, and revoking one should never take down another.

Conventions

Base URL

https://api.velt.example

Idempotency

Send an Idempotency-Key header on any write. Replaying the key with the same body returns the original response instead of acting twice; replaying it with a different body is a conflict. Networks fail halfway, and a retried payout that sends twice is not recoverable — so treat this as required on anything that moves money, not optional.

idempotency-key: 550e8400-e29b-41d4-a716-446655440000

Pagination

Every list returns the same envelope. Walk it with the cursor rather than an offset: the cursor pins a position in the ordering, so a page stays correct even when invoices are voided or orders expire while you are reading.

GET /v1/invoices?limit=50&cursor=aW52XzlhcDEgMjAy...

{
  "object": "list",
  "data": [ ... ],
  "hasMore": true,
  "nextCursor": "aW52XzhhbDIgMjAy..."
}

limit defaults to 50 and caps at 200. Lists run newest first.

Rate limits

300 requests per minute per key by default. Over the limit you get 429 with rate_limited; back off and retry. The SDKs already retry with exponential backoff and jitter.

Amounts

Fiat amounts are decimal strings in the pricing currency, such as "2400.00". Crypto amounts are returned as strings at the asset's own precision — eight decimal places for BTC, six for USDC and USDT. Never parse either into a binary float.

Errors

Every failure returns the same envelope. Branch on code, which is stable, rather than on the message, which is written for people and may change. Quote requestId to support and we can find the exact request in our logs.

{
  "error": {
    "code": "insufficient_funds",
    "message": "Available USDC balance is 120.00, payout requested 500.00",
    "requestId": "req_8f21ac09"
  }
}

API reference

Grouped by what you are trying to do. Every path below is relative to the base URL, and every list endpoint takes limit and cursor.

Webhooks

Anything that happens after your request returns — a shopper paying an hour later, a payout clearing, a reorg reversing a confirmed order — reaches you as a signed webhook. Register endpoints in the dashboard or through the API, and subscribe each one to the events it cares about.

Verifying a delivery

Each delivery carries x-velt-signature: t=<unix seconds>,v1=<hex hmac>. The HMAC is SHA-256 over "<timestamp>.<raw body>" using your organization's signing secret. Verify before you trust the payload, compare in constant time, and reject a timestamp outside a five minute window so a captured delivery cannot be replayed at you later.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!Number.isFinite(age) || age > 300) throw new Error("stale signature");

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    throw new Error("bad signature");
  }
  return JSON.parse(rawBody);
}

Both SDKs ship this as one call. Note that it takes the raw body: if your framework has already parsed and re-serialised the JSON, the bytes no longer match and every signature fails.

Delivery and retries

Reply 2xx to acknowledge. Anything else, or a timeout, is retried with backoff, and the delivery log in the dashboard shows every attempt and its response. Handlers must be idempotent: a retry after your endpoint timed out but succeeded will deliver the same event twice.

Events

Fulfil on order.paid, and only on order.paid. order.confirming means the money has been seen, not that it is final — and order.reorged exists because a confirmed payment can still be undone by the chain.

Assets and networks

A shopper pays in any of these; you hold and settle in whichever asset you choose. Confirmation counts are per rail, because the chains do not agree on what finality costs.

Call GET /v1/currencies rather than hard-coding this table — it returns the rails your environment currently accepts, with their confirmation counts, and sandbox runs on testnets.

SDKs and integrations

Going live

Before you switch a key from sandbox to live, the short list that matters:

1. Verify your business. Submit your details in Settings. An operator reviews the filing manually; live keys are issued after approval.
2. Register a production webhook endpoint and verify signatures on it. Confirm your handler is idempotent by replaying a delivery from the log.
3. Fulfil on order.paid only, and handle order.underpaid and order.reorged deliberately rather than ignoring them.
4. Send Idempotency-Key on every write, especially payouts and refunds.
5. Add your withdrawal addresses to the address book and set a withdrawal policy. Payouts are approved by an operator before they are signed.
6. Keep keys server-side and rotate the webhook secret on a schedule.