MNY WAY – Integration Docs

1) Create a Program

As a merchant, go to Dashboard → New Program. Copy the Webhook Secret (API key) and your Program Slug.

2) Create an Offer

Add at least one Offer with a target URL (your landing page).

3) Affiliate Links

Format: https://mnyway.com/go/<programSlug>?aff=<AFF_PUBLIC_ID>&offer=<offerSlug>

Optional params: &subid=YOUR_SUBID for campaign / keyword / placement tracking, and &redirect=/path-or-url to override the landing URL with a same-domain URL (for example, a multi-step funnel). Redirect overrides that point to a different domain are ignored for security.

4) Conversion API

Simple POST request:

POST /api/conversions
X-Api-Key: {PROGRAM_WEBHOOK_SECRET}
Content-Type: application/json

{"programSlug":"demoprogram","orderId":"123","amount":99.99,"currency":"USD","cid":"{clickId}","meta":{"sku":"abc"}}

If you don't have the click ID, you can send an affPublicId instead. In that case, MNY WAY will attribute the conversion to the most recent click for that affiliate in the same program within the program's cookie window.

MNY WAY currently settles all reporting and payouts in USD. The currency field must be "USD" or omitted; non-USD currencies are rejected.

Optional HMAC signing

For additional integrity, you can enable CONVERSION_HMAC_SECRET in your environment. When set, each request must include:

X-Timestamp – a UNIX timestamp in milliseconds (must be within 5 minutes of our server time).
X-Signature – a hex HMAC-SHA256 signature of the string `${timestamp}.${JSON.stringify(body)}` computed with CONVERSION_HMAC_SECRET.

Make sure you use the exact JSON body that you send over the wire when computing the signature – the same field order and values. A typical Node.js implementation looks like:

const crypto = require('crypto')

const body = { /* ...your payload... */ }
const timestamp = Date.now()
const payload = `${timestamp}.${JSON.stringify(body)}`
const signature = crypto
  .createHmac('sha256', process.env.CONVERSION_HMAC_SECRET)
  .update(payload)
  .digest('hex')

Requests with invalid signatures, missing headers, or stale timestamps are rejected with 400/401.

Rotating program API keys

Each program has its own Webhook Secret. You can rotate it at any time from Dashboard → Programs → [Program]. Rotating immediately invalidates the previous key, so remember to update your integration's X-Api-Key header at the same time.

5) Reconciliation & Payouts

Nightly cron marks non-flagged conversions older than 3 days as APPROVED. Export CSV from /reports/payouts to pay affiliates manually (Stripe, ACH, etc.), or use the Stripe Connect batch payout runner on the same screen to send funds to connected affiliate accounts.

6) Environment Variables

DATABASE_URL=postgresql://... (Neon or other pooled Postgres)
AUTH_URL=https://yourdomain.com
AUTH_SECRET=...

# Rate limiting (Upstash) – required in production
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...

# Optional: Sentry
SENTRY_DSN=...
SENTRY_ENVIRONMENT=production

7) Affiliate applications & marketplace

Each program has a Join type:

Open join – affiliates can join instantly; an application row is still created for auditing.
By approval only – affiliates must apply; merchants approve/reject from the Program screen.

Affiliates discover programs from /programs (Program Directory) and apply / join from there.

8) JS Pixel

For merchants who prefer a client-side integration, include this on the thank-you page:

<script src="https://mnyway.com/mnyway.js" async></script>
<script>
  mnyway.trackConversion({
    programSlug: 'your-program-slug',
    orderId: 'ORDER-123',
    amount: 99.99,
    currency: 'USD',
    sku: 'SKU123',
    coupon: 'WELCOME10',
    meta: { source: 'shopify' }
  });
</script>

The pixel reads mny_cid and mny_aff cookies set by your tracking links and posts a conversion to /api/conversions/pixel.

9) Webhooks & developer APIs

MNY WAY supports merchant and affiliate webhooks for conversion events. Each webhook endpoint receives a signed JSON payload with conversion and click data.

CONVERSION_RECORDED
CONVERSION_APPROVED
CONVERSION_PAID

Webhook endpoints can be managed from the /webhooks screen (merchant or affiliate dashboard). You can create endpoints per program or globally, rotate secrets, and send test payloads to verify your integration.

10) JSON reporting APIs

For programmatic reporting (BI tools, internal dashboards) MNY WAY exposes read-only JSON APIs for affiliates and merchants.

Affiliate reporting API

Generate an Affiliate API key from the affiliate dashboard (Affiliate → API keys) and call:

GET https://mnyway.com/api/reporting/affiliate/conversions?from=2025-01-01&to=2025-01-31&status=APPROVED&limit=200

Headers:
  X-Api-Key: {AFFILIATE_API_KEY}
  Accept: application/json

The response contains a stats block (clicks, conversions, EPC) and a paginated items array of conversions. Use the nextCursor value to fetch subsequent pages.

Merchant / program reporting API

Merchants (or the network operator) can use a per-program Webhook Secret as the program API key:

GET https://mnyway.com/api/reporting/program/{programSlug}/conversions?from=2025-01-01&to=2025-01-31&status=APPROVED

Headers:
  X-Api-Key: {PROGRAM_WEBHOOK_SECRET}
  Accept: application/json

Both APIs are rate-limited and read-only. Keys should be treated as server-side secrets and never exposed in browser code or public repositories.

11) White-label & subdomains

Each merchant can configure a white-label subdomain and branding via MerchantProfile.subdomain, brandName and logoUrl. When traffic hits <subdomain>.your-root-domain, the UI automatically switches to that merchant's brand (logo + name) while keeping tracking links and APIs fully compatible.

For production, point CNAME records such as merchant1.your-root-domain → app.your-root-domain and set the matching subdomain on the merchant profile.