Developers
PayFresco integration platform
Use these docs to build a PayFresco integration from a plain HTML storefront, a modern app framework, a server-side commerce backend, or a partner workflow that needs payment orchestration and CRM events.
Quick Start
Create sandbox and production API keys in the PayFresco dashboard or request them during onboarding.
PAYFRESCO_API_KEY=pf_sandbox_xxx
PAYFRESCO_API_BASE=https://sandbox-api.payfresco.com/api/public/v1
PAYFRESCO_WEBHOOK_SECRET=whsec_xxxUse the server SDK for sensitive operations and the headless SDK or core browser package for checkout UI.
npm install @payfresco/node-sdk @payfresco/headless-sdk @payfresco/core-jsCreate a session server-side, then send the shopper into hosted checkout or load the session in your custom UI.
const session = await payfresco.checkout.sessions.create({
storeId: "store_abc123",
items: [{ productId: "prod_abc", quantity: 1 }],
successUrl: "https://example.com/thank-you",
cancelUrl: "https://example.com/cart"
});Subscribe to webhooks before going live so fulfillment, recovery, and CRM follow-up are driven by server-side facts.
app.post("/webhooks/payfresco", rawBody, (req, res) => {
const event = verifyPayFrescoSignature(req);
routeEventToFulfillmentOrCRM(event);
res.sendStatus(200);
});Checkout
The simplest integration creates a checkout session on your server and redirects the browser to the returned hosted URL. Keep product, pricing, customer, shipping, promotion, and attribution data in the server request.
const response = await fetch(`${baseUrl}/checkout/init`, {
method: "GET",
headers: { Authorization: `Bearer ${apiKey}` }
});
window.location.assign(response.checkoutUrl);Custom storefronts should load a checkout session in the browser, tokenize card details with the browser package, and send only PayFresco tokens back to your server.
const client = createPayFrescoClient({
storeId: "store_abc123",
environment: "sandbox"
});
const checkout = await client.checkout.loadSession(token);
const cardToken = await client.payment.tokenizeCard(cardFields);
await client.payment.pay({ checkoutSessionId: checkout.id, cardToken });Payments
Configure payment flows with fallback processors, supported currencies, risk checks, and retry behavior.
When a processor pauses for 3DS or device fingerprinting, return the required client action and continue the payment after completion.
Use refund, void, disputed, and dispute-status operations to keep the CRM and payment records in sync.
await payfresco.payments.process({
checkoutSessionId: "cs_123",
paymentFlowId: "pflo_123",
paymentInstrumentId: "pi_123",
amount: 4900,
currency: "USD"
});Webhooks
payment.succeeded for fulfillment and receiptspayment.failed for recovery workflowssubscription.renewed and subscription.canceleddispute.opened and dispute.updatedcustomer.created and order.createdVerify the raw request body with the webhook secret before parsing or trusting event data.
const signature = req.headers["x-payfresco-signature"];
const expected = hmacSha256(rawBody, process.env.PAYFRESCO_WEBHOOK_SECRET);
if (!timingSafeEqual(signature, expected)) {
return res.sendStatus(401);
}SDKs and Tools
Server-side stores, products, customers, checkout sessions, processors, webhooks, subscriptions, and payment operations.
Browser checkout sessions, cart state, customer state, shipping, promotions, offers, and payment initiation.
Low-level browser tokenization, 3DS, device-fingerprint continuation, Apple Pay, Google Pay, and direct payment helpers.
Reusable checkout components, funnel steps, manifests, resources, path remapping, and deployable plugin experiences.
Plugin manifests, environment config, deployments, custom domains, preview aliases, and release promotion.
AI-agent access for CRM diagnostics, processor checks, domain status, template editing, and Studio workflows.
API Reference
All Topics