Custom server integration

Install @monok/server, store your workspace key in MONOK_API_KEY on the server, and mount the middleware before your landing and signup routes. Test with a valid affiliate link using ref on your offer’s exact landing URL.

import {
  monokAffiliateAttribution,
  signup,
  clearMonokAffiliateAttribution,
  reportMonokAffiliateTransaction,
} from "@monok/server";

const apiKey = process.env.MONOK_API_KEY;
if (!apiKey) throw new Error("MONOK_API_KEY is required");
app.use(monokAffiliateAttribution({ apiKey }));

Configure Express proxy trust for your actual proxy setup. Use HTTPS for the default secure attribution cookie.

Run this inside your signup handler after the customer has been saved. Reuse the same stable customer ID when reporting payments.

if (req.monokAttribution) {
  const referral = await signup({
    attributionToken: req.monokAttribution,
    customerId: customer.id,
  }, { apiKey });

  if (referral.status === "created" || referral.status === "existing") {
    clearMonokAffiliateAttribution(res);
  }
}

Call this from your billing backend when payment succeeds. Use the same transaction ID on retries, and send the amount in minor currency units.

await reportMonokAffiliateTransaction({
  customerReference: payment.customerId,
  transaction: {
    id: payment.id,
    amount: payment.amountMinor,
    currency: payment.currency,
    occurredAt: payment.occurredAt,
  },
}, { apiKey });

1. Follow a valid affiliate link and confirm capture at your landing URL.
2. Create a customer through your signup flow and confirm the referral was registered.
3. Report a completed payment and verify it appears for the correct affiliate in Monok. Retrying the same transaction ID should not create a second commission.