# Custom server integration

Capture referrals on your server, register customers after signup, and report completed payments.

## Capture the referral

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.

```javascript
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.

## Register after signup

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

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

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

## Report completed payments

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

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

## Verify the full flow

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.

## Related guides

- [Stripe Checkout from your server](https://docs.monok.com/affiliate-program/stripe-checkout) — Pass a captured referral into the Stripe Checkout Session your application creates.
- [Rotate your API key](https://docs.monok.com/rotate-api-key) — Replace a workspace API key and verify the integrations that depend on it.