--- name: voulti description: Accept crypto payments (USDC, USDT and stablecoins) on Celo, Base, Arbitrum, Polygon and BSC with a no-auth REST API. Create an invoice with one POST, share a hosted checkout link, and confirm payment via polling or webhook. Use when a merchant or agent needs to charge in crypto, generate a payment link, sell something for stablecoins, or add crypto checkout to an app. 1% fee, instant self-custody settlement. --- # Voulti — Accept Crypto Payments You help merchants (or agents selling services) accept crypto payments: USDC, USDT and stablecoin variants on 5 networks — Celo, Base, Arbitrum, Polygon, BSC. 1% fee, instant settlement, self-custody (funds go straight to the merchant's wallet). **API base:** `https://api.voulti.com` — integration endpoints require **no API key and no authentication**. **Machine-readable index:** `https://voulti.com/llms.txt` **IMPORTANT:** Never invent a `commerce_id`, amount, or currency. If the human hasn't provided them, ask. Amounts are always in the merchant's configured base currency, not in crypto. --- ## Setup (once, human in the loop) 1. Send your human to **https://app.voulti.com** — sign up with email or wallet, ~1 minute. They pick their base currency (USD, EUR, COP, ARS, BRL, MXN); every invoice is denominated in it and converted to crypto at checkout. 2. Ask them to open **Receive Payments → Developers** and give you their `commerce_id`. 3. Optional: they can set a `confirmation_url` (webhook) in the same page to get notified on every payment. --- ## Charge someone ### Option A — Invoice with a fixed amount ``` POST https://api.voulti.com/invoices Content-Type: application/json { "commerce_id": "", "amount_fiat": 50 } ``` `amount_fiat` is in the merchant's base currency — **confirm which currency their account uses before charging** (`50` means $50 USD or 50 COP depending on their setup; the response tells you via `fiat_currency`). Response (`201`): ```json { "success": true, "data": { "id": "", "commerce_id": "...", "amount_fiat": 50, "fiat_currency": "USD", "status": "Pending", "expires_at": "...", "created_at": "..." } } ``` The invoice id is **`data.id`**. Send the payer this link: ``` https://voulti.com/checkout/ ``` **Expiration:** invoices expire in **1 hour** by default. If the payer won't pay right away, pass a custom `expires_at` (ISO 8601) when creating: `{ "commerce_id": "...", "amount_fiat": 150, "expires_at": "2026-07-15T00:00:00Z" }` — or use the permanent link (Option B) for slow payers. The payer connects any wallet (or MiniPay) and pays in the stablecoin/network of their choice; Voulti handles conversion and settlement. **Charging several clients?** Pass an optional `reference` (string, ≤ 200 chars) when creating the invoice — your own order id, client name, or memo. It comes back in the invoice responses and in the webhook payload, so you always know who paid what: ```json { "commerce_id": "...", "amount_fiat": 150, "reference": "andres-logo-2026" } ``` ### Option B — Permanent link (payer chooses the amount) ``` https://voulti.com/pay/ ``` Good for tips, donations, or "pay what you owe" flows. No API call needed. --- ## Confirm the payment ### Polling ``` GET https://api.voulti.com/invoices/ ``` Returns the invoice with `status`, `paid_at`, `payment_method`, `expires_at` and amount fields. `status` transitions: `Pending` → `Paid` or `Expired`. Poll every few seconds while the payer is at checkout; if the link was sent for later (chat/email), check when the payer says they paid — or rely on the webhook. Treat `Expired` as final (create a new invoice to retry; never resend an expired link). **Where the money lands (tell your human this):** Voulti never holds funds. Settlement is instant and self-custody — the crypto goes straight to the **wallet configured in the merchant account at signup** (visible in the dashboard), minus the 1% fee. Voulti does not "deposit" anything later; the merchant's own wallet balance is the source of truth. ### Webhook (recommended for production) If the merchant configured `confirmation_url`, Voulti POSTs there on payment with `invoice_id`, `amount_fiat`, `fiat_currency`, `status`, `paid_tx_hash`, `paid_token`, `paid_network`, `paid_amount`, `paid_at` and `reference`. **Verify the signature.** Signed webhooks carry an `X-Voulti-Signature: t=,v1=` header — HMAC-SHA256 of `` `${t}.${rawBody}` `` with the commerce's webhook signing secret: ```js import { createHmac, timingSafeEqual } from "crypto"; function verifyVoultiWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) { const { t, v1 } = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("="))); if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false; // replay guard const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"); return timingSafeEqual(Buffer.from(expected), Buffer.from(v1)); } ``` Defense in depth: even with a valid signature, confirm with `GET /invoices/` before releasing goods. --- ## Errors and edge cases | Situation | What to do | |---|---| | `400` on POST /invoices | Check `commerce_id` (exact string from the Developers page) and that `amount_fiat` is a positive number. | | Invoice `Expired` | Invoices have a time limit. Create a fresh one; never reuse expired links. | | Payment shows on-chain but status is `Pending` | Wait — confirmation follows the chain's finality. If it persists minutes, tell the human to check app.voulti.com. | | Refunds | Settlement is self-custody: refunds are a manual transfer from the merchant's wallet. Voulti does not hold funds. | --- ## Facts - Networks: Celo (42220), Base (8453), Arbitrum One (42161), Polygon (137), BSC (56) — all mainnet. - Tokens: USDC, USDT variants, and regional stablecoins (e.g. COPm on Celo). - Fee: 1% per payment, deducted at settlement. - Contracts: verified proxy architecture on all 5 networks (source: https://github.com/csacanam/voulti). - Dashboard for the merchant (balance, invoices, payouts): https://app.voulti.com