@fanth/pay-form-sdk

TypeScript SDK for interacting with pay-form.fanth.pl.

Install

npm install @fanth/pay-form-sdk

With pnpm:

pnpm add @fanth/pay-form-sdk

Usage

See examples in the examples directory.

import { PayFormClient } from "@fanth/pay-form-sdk";

const client = new PayFormClient({
    apiKey: process.env.PAY_FORM_API_KEY!,
    webhookSecret: process.env.PAY_FORM_WEBHOOK_SECRET!,
    // baseUrl defaults to https://pay-form.fanth.pl
});

Generating a payment link

const url = await client.generatePaymentForm({
    title: "Order #1",
    amount: 10, // PLN, up to 2 decimal places
    paymentMethods: ["payu", "card"],
    payuPosId: 12345, // required when "card" is one of the paymentMethods
    webhookUrl: "https://example.com/api/webhooks/pay-form",
});

Handling the webhook

Once the payer picks a method, pay-form POSTs to your webhookUrl URL and waits for your response before redirecting the payer anywhere. client.parseWebhook verifies and parses that call - it checks the X-Fanth-Signature header against the raw body (and rejects stale timestamps), throwing if the signature is missing or invalid.

Your handler is where the actual payment gets initiated, and the redirectUrl you return is where the payer's browser ends up next - e.g. a hosted payment gateway page for methods that need one more step (payu, paymentic). It's optional: omit it (or return no body) and pay-form redirects the payer to its own default success page instead.

// e.g. a Next.js route handler / any Request-based HTTP framework
export async function POST(request: Request) {
    const payment = await client.parseWebhook(request);

    if (payment.method !== "card") {
        // create the order with the gateway (PayU/Paymentic) and forward the payer to its hosted payment page
        const redirectUrl = await createGatewayOrder(payment);
        return Response.json({ redirectUrl });
    }

    // already charged via payment.cardToken - no redirectUrl needed, pay-form shows its own success page
    return Response.json({});
}

Note: parseWebhook reads the body via request.text(), so pass it the raw Request before any other code consumes the body.