@h33/commerce
Proof-of-payment without identity disclosure. Three API calls. Ten minutes. Developer sees approved: true, never sees customer identity. 35 circuits handle the complexity -- you never touch one. PQ-signed with ML-DSA-65 + FALCON-512 + SLH-DSA-128f.
$ npm install @h33/commerce
import { H33Commerce } from '@h33/commerce';
// 1. Initialize (API key from env or constructor)
const commerce = new H33Commerce({
apiKey: process.env.H33_API_KEY,
});
// 2. Create a privacy-preserving invoice
const invoice = await commerce.createInvoice({
amount: 49.99,
currency: 'USD',
});
// 3. Customer pays -- you get a 32-byte commitment, not identity
console.log(invoice.commitment); // "a1b2c3...64 hex chars"
console.log(invoice.qrPayload); // render this with any QR library
// 4. Check settlement
const settlement = await commerce.getSettlement(invoice.commitment);
console.log(settlement.approved); // true
// 5. Verify -- publicly, no API key needed
const proof = await commerce.verify(invoice.commitment);
console.log(proof.valid); // true
console.log(proof.complianceValid); // true (KYC/AML passed, identity hidden)
That is the complete integration. Three calls: create, settle, verify. The H33Commerce class handles compliance circuits, PQ signing, commitment generation, and settlement verification. You never see the customer's identity. The 35 circuits prove compliance to the regulator while proving privacy to the user.
| Concept | Description |
|---|---|
| Commitment | A 32-byte hex string that represents a payment without revealing payer identity. This is the universal identifier -- pass it to getSettlement() and verify(). |
| Invoice | Created by the merchant. Contains the amount, currency, commitment, expiration, and a QR payload for customer-facing payment flows. |
| Settlement | The result of payment processing. Contains approved, compliance status, attestation commitment, and the PQ-signed proof key. Merchants see approval status, never customer identity. |
| Verification | Public, unauthenticated proof retrieval. Anyone with a commitment can verify that payment was approved, compliance passed, and the attestation is PQ-signed. No API key needed. |
| Circuits | 35 privacy circuits handle KYC, AML, sanctions screening, age verification, and jurisdiction checks. You never configure, deploy, or interact with a circuit directly. |
| PQ Signing | Every attestation is signed with three independent PQ families: ML-DSA-65, FALCON-512, and SLH-DSA-128f. Breaks iff lattices, NTRU, and stateless hash functions are simultaneously broken. |
Primary integration surface. Handles invoicing, settlement, verification, webhooks, and health checks.
Typed error with code, message, and status. Thrown on all API failures.
Response from createInvoice(). Contains commitment, QR payload, expiration, and total.
Response from getSettlement(). Contains approval status, compliance result, and proof key.
Response from verify(). Public proof of payment validity and compliance status.
Response from health(). Service status, circuit count, and test suite results.
H33CommerceThe primary integration class. Wraps all commerce endpoints into five methods.
| Property | Type | Default | Description |
|---|---|---|---|
apiKey | string | H33_API_KEY env | API key. Falls back to environment variable |
baseUrl | string | https://privacy.h33.ai | API base URL |
timeoutMs | number | 30000 | Request timeout in milliseconds |
webhookSecret | string | H33_WEBHOOK_SECRET env | Secret for webhook signature verification |
createInvoice()Create a privacy-preserving invoice. Returns a 32-byte commitment and QR payload for customer-facing flows.
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Invoice amount (e.g. 49.99) |
currency | string | Yes | ISO 4217 currency code (e.g. 'USD') |
tax | number | No | Tax amount to add |
expiresIn | number | No | Expiration in seconds (default: 3600) |
items | LineItem[] | No | Array of line items for itemized invoices |
idempotencyKey | string | No | Idempotency key to prevent duplicate invoices |
getSettlement()Retrieve the settlement status for a payment commitment. Returns approval status, compliance result, and the PQ-signed proof key.
verify()Public verification of a payment commitment. No API key is required. Anyone with the commitment can verify payment validity and compliance status.
health()Check service health. No API key is required. Returns service status, active circuit count, and test suite results.
verifyWebhook()Verify the authenticity of a webhook payload using the configured webhookSecret. Returns true if the signature is valid. Use this before processing any webhook event.
Invoice| Field | Type | Description |
|---|---|---|
invoiceId | string | Unique invoice identifier |
commitment | string | 32-byte hex commitment (64 hex chars). The universal payment identifier |
totalCents | number | Total amount in cents (e.g. 4999) |
total | string | Formatted total (e.g. "49.99") |
currency | string | ISO 4217 currency code |
expiresAt | string | ISO-8601 expiration timestamp |
qrPayload | string | Encoded payload for QR code rendering |
Settlement| Field | Type | Description |
|---|---|---|
invoiceId | string | Invoice this settlement belongs to |
approved | boolean | Whether the payment was approved |
settlementStatus | string | Settlement state: 'settled', 'pending', 'failed' |
complianceValid | boolean | Whether all compliance circuits passed |
attestationCommitment | string | PQ-signed attestation commitment |
verifiedAt | string | ISO-8601 timestamp of verification |
proofKey | string | Key for retrieving the full cryptographic proof |
Verification| Field | Type | Description |
|---|---|---|
valid | boolean | Whether the commitment is valid and verifiable |
approved | boolean | Whether the payment was approved |
complianceValid | boolean | Whether compliance circuits passed |
attestationCommitment | string | PQ-signed attestation commitment |
verifiedAt | string | ISO-8601 timestamp of verification |
Health| Field | Type | Description |
|---|---|---|
status | string | Service status: 'healthy', 'degraded', 'down' |
service | string | Service identifier |
circuits | number | Number of active privacy circuits (35) |
tests_passing | number | Number of passing tests (113) |
// app/api/checkout/route.ts
import { NextResponse } from 'next/server';
import { H33Commerce } from '@h33/commerce';
const commerce = new H33Commerce();
export async function POST(req: Request) {
const { amount, currency, items } = await req.json();
const invoice = await commerce.createInvoice({
amount,
currency,
items,
expiresIn: 1800, // 30 minutes
});
// Return commitment + QR -- never customer identity
return NextResponse.json({
invoiceId: invoice.invoiceId,
commitment: invoice.commitment,
qrPayload: invoice.qrPayload,
total: invoice.total,
expiresAt: invoice.expiresAt,
});
}
import express from 'express';
import { H33Commerce, H33Error } from '@h33/commerce';
const app = express();
const commerce = new H33Commerce();
app.post('/api/invoice', async (req, res) => {
try {
const invoice = await commerce.createInvoice(req.body);
res.json(invoice);
} catch (err) {
if (err instanceof H33Error) {
res.status(err.status).json({ code: err.code, message: err.message });
} else {
res.status(500).json({ error: 'Internal server error' });
}
}
});
app.get('/api/settlement/:commitment', async (req, res) => {
const settlement = await commerce.getSettlement(req.params.commitment);
res.json(settlement);
});
app.get('/api/verify/:commitment', async (req, res) => {
const proof = await commerce.verify(req.params.commitment);
res.json(proof);
});
app.listen(3000);
The invoice.qrPayload field contains an encoded payment string ready for any QR library. Render it on a checkout page, email, or receipt -- the customer scans, pays, and the merchant never sees their identity.
import QRCode from 'qrcode.react';
function CheckoutQR({ invoice }: { invoice: Invoice }) {
return (
<div>
<QRCode
value={invoice.qrPayload}
size={256}
level={"H"}
/>
<p>Total: {invoice.total} {invoice.currency}</p>
<p>Expires: {invoice.expiresAt}</p>
</div>
);
}
import QRCode from 'qrcode';
// Generate QR as data URL for embedding in HTML
const dataUrl = await QRCode.toDataURL(invoice.qrPayload, {
errorCorrectionLevel: 'H',
width: 256,
});
// Or save as PNG
await QRCode.toFile('./invoice-qr.png', invoice.qrPayload);
Register a webhook URL in your H33 dashboard to receive real-time payment events. Always verify the signature before processing.
| Event | Description |
|---|---|
payment.verified | Payment has been verified by the compliance circuits. The customer has paid and all checks passed. |
payment.settled | Payment has been fully settled. Funds are available. |
import { H33Commerce } from '@h33/commerce';
const commerce = new H33Commerce({
webhookSecret: process.env.H33_WEBHOOK_SECRET,
});
app.post('/webhooks/h33', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-h33-signature'] as string;
// Always verify before processing
if (!commerce.verifyWebhook(req.body, signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = JSON.parse(req.body.toString());
switch (event.type) {
case 'payment.verified':
console.log('Payment verified:', event.commitment);
// Update order status
break;
case 'payment.settled':
console.log('Payment settled:', event.commitment);
// Release goods/services
break;
}
res.status(200).json({ received: true });
});
Always use express.raw() (not express.json()) for the webhook route so you receive the raw body for signature verification. Parsing the body before verification defeats the purpose.
All API errors throw H33Error with a typed code, human-readable message, and HTTP status.
import { H33Commerce, H33Error } from '@h33/commerce';
try {
const invoice = await commerce.createInvoice({
amount: -10,
currency: 'USD',
});
} catch (err) {
if (err instanceof H33Error) {
console.log(err.code); // "invalid_amount"
console.log(err.message); // "Amount must be positive"
console.log(err.status); // 400
}
}
| Code | Status | Description |
|---|---|---|
invalid_amount | 400 | Amount must be a positive number |
invalid_currency | 400 | Currency code is not a valid ISO 4217 code |
invoice_not_found | 404 | No invoice exists for the given commitment |
invoice_expired | 410 | Invoice has expired and can no longer be paid |
double_payment | 409 | This invoice has already been paid |
amount_mismatch | 400 | Payment amount does not match invoice amount |
rate_limited | 429 | Too many requests. Back off and retry with exponential delay |
missing_auth | 401 | API key is missing or invalid. Set H33_API_KEY env or pass to constructor |
createInvoice() generates a 32-byte commitment and registers the invoice with the privacy layer at https://privacy.h33.ai.getSettlement() returns approved: true when all circuits pass and payment clears. The merchant never sees who paid.verify() requires no API key. Auditors, regulators, and counterparties can independently confirm payment validity and compliance status using only the commitment.The merchant sees approved: true. The regulator sees compliance proof. The customer retains privacy. All three are cryptographically guaranteed by the same 32-byte commitment.