Cryptss Pay API Documentation

Create a merchant account. Creates a default USDC wallet automatically.

// 201 Created
{ "ok": true, "user": { "id": 5, "email": "me@studio.com", "name": "Me", "role": "user" } }

Sign in with email + password. Sets the session cookie.

// 200 OK
{ "ok": true, "user": { "id": 1, "email": "demo@cryptss.com", "name": "Layla Haddad", "role": "user" } }

One-click demo login. Used by the sign-in page.

Current session user. 401 when logged out.

Destroys the session.

Always returns success (no account enumeration).

List invoices for the signed-in user.

// 200 OK
{ "invoices": [ { "id": 1, "number": "INV-2041", "token": "aZ…x", "client_name": "Acme Co.",
  "client_email": "client@acme.com", "amount": "2350.00", "asset": "USDC",
  "status": "escrow", "escrow": 1, "due_date": "2026-08-17", "memo": "Brand system",
  "created_at": "…", "paid_at": "…", "pay_url": "https://cryptss.com/app#/pay/aZ…x",
  "track_url": "https://cryptss.com/app#/track/aZ…x" } ] }

Create an invoice.

// 201 Created
{ "ok": true, "invoice": { "number": "INV-2044", "token": "…", "status": "sent", … } }

Cancel a payable invoice. 409 if already paid/escrowed.

Logs a "reminder sent" notification for an overdue invoice.

Invoice snapshot for the pay page.

// 200 OK
{ "invoice": { "number": "INV-2044", "client_name": "Acme Co.", "amount": "650.00",
  "asset": "USDC", "status": "sent", "escrow": false, "due_date": "…",
  "memo": "…", "payee": "Studio Layla — Design", … } }

404 unknown token · 410 cancelled invoice.

Settle an invoice without an account.

// 200 OK — paid, or held in escrow when the invoice has escrow enabled
{ "ok": true, "status": "paid" | "escrow", "tx_hash": "0x…", "invoice": { … } }

Timeline for the payment tracking page.

// 200 OK — steps include created, sent, payment received, escrow held/released
{ "steps": [ { "label": "Invoice created", "at": "…", "done": true }, … ] }

Settled and pending payments, newest first. Optional ?q= search.

// 200 OK
{ "payments": [ { "id": 1, "invoice_id": 1, "payer": "Acme Co.", "amount": "2350.00",
  "asset": "USDC", "tx_hash": "0x…", "method": "wallet", "status": "settled", "created_at": "…" } ] }

List escrows (held · released · disputed).

Release a held escrow to the merchant wallet. 409 if not held.

Open a dispute on a held escrow.

Stablecoin balances across chains.

// 200 OK
{ "wallets": [ { "chain": "base", "asset": "USDC", "address": "0x…", "balance": "8420.00" }, … ] }

Add demo funds to a wallet.

Cash-out history + KYC status.

422 insufficient_balance / 422 kyc_required.

Demo KYC — approves instantly.

Card details (last4, frozen), monthly spend vs limit, recent spends.

Purchase with the card — debits the largest wallet.

403 card_frozen · 422 over_card_limit · 422 insufficient_balance.

Toggles frozen state. Returns { "ok": true, "frozen": bool }.

Recurring schedules (retainers / subscriptions).

Pause / resume. Body: { id }.

Delete. Body: { id }.

Clients with per-client billed totals.

Body: { name, email?, company?, allowlist? }.

Add/remove a client from the agent allowlist. Body: { id }.

Current policy + month spent.

// 200 OK
{ "policy": { "agent_name": "Acme Procurement Bot", "per_payment_cap": "1000",
  "monthly_limit": "10000", "approval_threshold": "500", "allowlist_only": 1,
  "wallet_address": "0x…" }, "month_spent": 300 }

Update policy. Any subset of: agent_name, per_payment_cap, monthly_limit, approval_threshold, allowlist_only.

Ask the agent to pay. Use an existing invoice token, or vendor + amount.

// Decision responses
{ "decision": "settled", "tx_hash": "0x…", "invoice": "INV-2046" }
{ "decision": "denied",  "reason": "vendor_not_allowlisted" | "over_per_payment_cap" | "over_monthly_limit", … }
{ "decision": "paused",  "reason": "over_approval_threshold", "approval_id": 12, "invoice": "INV-2047" }

Human approves a paused payment. Body: { activity_id }. Settles the invoice.

Human denies a paused payment. Body: { activity_id }.

Agent decision log: request · check · settle · pause · approve · deny.

Ask the copilot anything — it answers from your live account data (balances, invoices, overdue items, cash-out timing).

// 200 OK
{ "reply": "Your wallets hold $11,512.50 in total across Base, Polygon and Arbitrum…" }

Last 12 months of settled volume.

Top clients by settled volume.

Invoice status distribution.

Quarterly settled totals + platform fees for the year. Optional ?year=.

// 200 OK
{ "year": 2026, "years": ["2026","2025"], "quarters": [ { "quarter": "Q1", "total": 6080, "fees": 60.8, "n": 2 }, … ],
  "total": 20010, "fees": 200.1 }

Full-year CSV download of settled payments with fees.

Latest 30 notifications + unread count.

// 200 OK
{ "notifications": [ { "id": 1, "title": "Payment received", "body": "INV-2039 · Acme Co. paid 3,200.00 USDC",
  "kind": "payment", "read": 0, "created_at": "…" } ], "unread": 3 }

Mark one ({ id }) or all (empty body) as read.

Due totals, escrow held, paid totals, wallets.

Invoices sent to this client.

Pay a bill from the client wallet.

422 insufficient_balance if the client wallet can't cover it.

Payment history with tx hashes.

Saved payment methods.

Platform-wide numbers.

// 200 OK
{ "users": 3, "merchants": 1, "volume": 26960, "payments_n": 13, "fees": 269.6,
  "escrow_held": 2350, "disputes_open": 0, "cashouts_pending": 2, "agent_volume": 300 }

Merchants with volume + invoice counts.

Open disputes.

Body: { id, outcome: "release" | "refund" }.

Pending cash-outs / KYC queue.

Body: { id, decision: "approved" | "rejected" }.

Provider health with live latency probes.

Key list — prefixes only. Full keys are shown once at creation.

Create a key. Body: { label? }.

// 201 Created — full key returned ONCE
{ "ok": true, "id": 3, "key": "ck_live_…" }

Revoke a key. Body: { id }.