FractalPay Integration Guide
Accept crypto across 9 chains with a Stripe-shaped API. Post-quantum (Dilithium) signed attestations on every payment. A merchant can go from zero to a working checkout in under 10 minutes.
Quickstart — receive a payment in 5 lines
import { FractalPay } from '@fractalai/pay';
const fp = new FractalPay();
const intent = await fp.intents.create({
amount: '100.00',
currency: 'USDC',
recipientAddress: '0xYourWalletOnBase',
recipientChain: 'base',
description: 'Pro plan — monthly',
callbackUrl: 'https://your-app.com/webhooks/fractalpay',
});
console.log(`Send your customer to: ${intent.webUrl}`);
// → https://fractalai.net.co/pay/{intent.id}The customer lands on a hosted checkout page at /pay/{id}, pays from their wallet on any supported chain, and your webhook fires when the payment settles on-chain.
Payment intent lifecycle
POST /api/pay creates an intent and returns its id, a webUrl for the hosted checkout, and qrData for an in-person/QR flow. Intents are persisted in Postgres, not just in memory, and every field that matters (amount, currency, recipient, chain) is bound into an HMAC so a tampered QR or store entry fails verification rather than silently paying the wrong party.
An intent can also end in expired, failed, or refunded. Query status any time with GET /api/pay?id={id}.
Verify webhooks
The webhook handler verifies the settlement on-chain via eth_getTransactionReceipt before marking an intent completed — it does not trust the callback payload alone. Always verify the signature on your side too before fulfilling an order:
import express from 'express';
import { verifyWebhook, SignatureVerificationError } from '@fractalai/pay';
const app = express();
// IMPORTANT: use raw body, not express.json() — re-serializing breaks the signature
app.post('/webhooks/fractalpay',
express.raw({ type: 'application/json' }),
(req, res) => {
try {
const event = verifyWebhook({
payload: req.body, // Buffer
signature: req.header('x-fractalpay-signature'),
secret: process.env.FRACTALPAY_WEBHOOK_SECRET!,
});
if (event.type === 'payment.completed') {
fulfillOrder(event.intent.metadata?.orderId);
}
res.status(200).send();
} catch (err) {
if (err instanceof SignatureVerificationError) {
return res.status(401).send();
}
throw err;
}
}
);Chains & fees
Supported currencies: FRAC, wFRAC, USDC, USDT, ETH. A customer can pay from any supported chain even if you settle on a different one — FractalPay routes and bridges automatically; the intent's suggestedChains field lists what the customer can use.
Python SDK
Same API surface as the TypeScript SDK — same method names, snake_case instead of camelCase. Live on PyPI, 31 passing tests, zero dependencies beyond httpx.
pip install fractalpay