PayFresco integration platform

Developer instructions for checkout, payments, CRM, routing, subscriptions, pixels, and webhooks.

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.

Start integration Browse API reference

234 developer topics

165 REST operations

2 environments

1 webhook contract

Quick Start

Go from API key to a working checkout flow.

Get credentials

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://api.tagada.dev/api/public/v1
PAYFRESCO_WEBHOOK_SECRET=whsec_xxx

Install SDKs

Use the server SDK for sensitive operations and the headless SDK or core browser package for checkout UI.

npm install @tagadapay/node-sdk @tagadapay/headless-sdk @tagadapay/core-js

Create a checkout session

Create 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"
});

Handle payment events

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

Choose hosted checkout, headless checkout, or funnel handoff.

Hosted redirect

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);

Headless checkout

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

Process, route, retry, void, refund, and continue payments.

Payment flow routing

Configure payment flows with fallback processors, supported currencies, risk checks, and retry behavior.

3DS and paused payments

When a processor pauses for 3DS or device fingerprinting, return the required client action and continue the payment after completion.

Disputes and refunds

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"
});

Wallet examples

Accept Apple Pay and Google Pay through the same charge path as cards.

Each wallet returns an encrypted payload. Convert that payload to the platform token, create a payment instrument on your server, then continue through the same payment and optional 3DS flow used for cards.

Apple Pay

Requires HTTPS and a supported Safari device with an active Wallet card.

Google Pay

Use the SDK environment helper to select the correct tenant instead of hard-coding it.

// Published package name retained intentionally
import {
  createTagadaTokenFromApplePay,
  createTagadaTokenFromGooglePay,
  getGoogleTenantId
} from "@tagadapay/core-js/core";

const appleToken = await createTagadaTokenFromApplePay(
  applePaymentData.token.paymentData
);

const googleToken = await createTagadaTokenFromGooglePay(
  googlePaymentData.paymentMethodData.tokenizationData.token
);

const tenantId = getGoogleTenantId("development");

Open the wallet guide Card tokenization & 3DS

Webhooks

Receive PayFresco events from the server side.

Recommended events

payment.succeeded for fulfillment and receipts
payment.failed for recovery workflows
subscription.renewed and subscription.canceled
dispute.opened and dispute.updated
customer.created and order.created

Verification pattern

Verify 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

Pick the integration surface that matches your build.

Node SDK

Server-side stores, products, customers, checkout sessions, processors, webhooks, subscriptions, and payment operations.

Headless SDK

Browser checkout sessions, cart state, customer state, shipping, promotions, offers, and payment initiation.

Core JS

Low-level browser tokenization, 3DS, device-fingerprint continuation, Apple Pay, Google Pay, and direct payment helpers.

Plugin SDK

Reusable checkout components, funnel steps, manifests, resources, path remapping, and deployable plugin experiences.

CLI

Plugin manifests, environment config, deployments, custom domains, preview aliases, and release promotion.

MCP tools

AI-agent access for CRM diagnostics, processor checks, domain status, template editing, and Studio workflows.

API Reference

REST operations grouped by product area.

All Topics

PayFresco guidance mapped to the complete current platform catalog.

Search titles, summaries, aliases, SDK names, paths, payment methods, and REST operations.