@flowpay-io/shared

Shared TypeScript type definitions and utilities for Flowpay SDK packages.

Installation

pnpm add @flowpay-io/shared

Launch payloads

FlowpayLaunchPayload is a union of merchant and customer launch payloads. Use the right shape depending on whether you are logging in a new or previously activated merchant or an existing Flowpay customer you previously activated.

Later in the process, use different integrationType setting based on the payload type (merchant or customer), passed as parameter to the SDK functions or with manual implementation, add it directly in the fp:LOGIN envelope in the meta field.

Merchant launch payload

For logging in a new or previously activated merchant:

import type { MerchantLaunchPayload } from "@flowpay-io/shared/types";
import { IsoCountryCode } from "@flowpay-io/shared/types";

const payload: MerchantLaunchPayload = {
  country: IsoCountryCode.CZ,
  merchantId: "merchant-123",
  partnerCode: "partner-abc",
  regNum: "12345678",
  userId: "user-456",
  createdAt: new Date().toISOString(),
  // optional: pre-fill and skip in-app input
  email: "[email protected]",
  phone: "+420123456789",
  // optional: merchant branches (e-shops, locations, etc.)
  tenants: [{ id: "branch-1", name: "Main store" }],
};

Customer launch payload

For logging in an existing Flowpay customer entity (previously activated by the partner):

import type { CustomerLaunchPayload } from "@flowpay-io/shared/types";

const payload: CustomerLaunchPayload = {
  partnerCode: "partner-abc",
  customerId: "flowpay-customer-id",
  userId: "user-456",
  repId: "rep-123",
  createdAt: new Date().toISOString(),
};

When using @flowpay-io/embed-core, createdAt can be omitted; the client sets it automatically if autoSetCreatedAt is enabled (default).

Utilities

The package also provides utility functions:

import { getCanonicalPayloadString } from "@flowpay-io/shared/utils";

// Merchant payload: integrationType defaults to "merchant" when omitted
const canonicalMerchantPayload = getCanonicalPayloadString(payload);

// Customer payload: explicitly pass "customer" as the integrationType
const canonicalCustomerPayload = getCanonicalPayloadString(
  customerPayload,
  "customer",
);

Canonical form and signatures

getCanonicalPayloadString produces a stable JSON string used for HMAC signature generation and verification. The field order in that string is fixed:

• Customer payload: alphabetical key order: createdAt, customerId, partnerCode, repId, userId.
• Merchant payload: alphabetical key order for top-level fields; tenants (when present) sorted by id.

Any change to this ordering would change the serialized string and break signature validation. Backends that reconstruct or verify the payload must use the same canonical order; the implementation in packages/shared/src/utils.ts is the source of truth.

Links

• Homepage: https://www.flowpay.io
• Documentation: https://developers.flowpay.io