Tracking, Tag, and S2S

Affiliate projects support redirect tracking, browser tag conversion tracking, and server-to-server postbacks.

Partner Tracking URL

Partners receive a URL in this format:

https://ads.mcv.network/aff/{trackingCode}

When opened, MCV records an AffiliateClick and redirects to the advertiser destination URL with UTM parameters plus:

mcv_aff={trackingCode}
mcv_click_id={clickId}

Advertisers should store mcv_click_id when possible. It gives stronger attribution than tracking code alone.

Browser Tag Endpoint

Use the browser tag endpoint for simple client-side conversion reporting:

https://ads.mcv.network/affiliate/tag/{projectSlug}?tracking_code={trackingCode}&event_type=qualified_lead&external_id=lead_123

Accepted parameters:

Parameter	Required	Description
tracking_code	Required unless click_id is sent	Partner tracking code.
click_id	Required unless tracking_code is sent	Click ID from mcv_click_id.
event_type	Yes	qualified_lead or sale.
external_id	Recommended	Advertiser-side lead/order ID for idempotency.
order_id	Required for sale S2S	Advertiser order ID for reconciliation.
sale_amount	Sale only	Sale amount in project currency.
currency	Sale only	Three-letter currency code. Defaults to project currency.
customer_hash	Optional	Hashed customer identifier for fraud review without exposing PII.

The tag endpoint returns a 1x1 GIF by default. Add format=json to receive a JSON response.

Server-to-Server Postback

Use S2S when the advertiser backend can report conversions directly.

POST https://ads.mcv.network/affiliate/s2s/{projectSlug}

Payload:

{
  "tracking_code": "aff_1_2_partner",
  "click_id": "clk_...",
  "event_type": "sale",
  "order_id": "ORDER-1001",
  "external_id": "checkout_1001",
  "sale_amount": "100.00",
  "currency": "USD",
  "customer_hash": "sha256_customer_identifier",
  "signature": "..."
}

S2S Signature

Build the signature payload in this exact order:

tracking_code|click_id|event_type|order_id|sale_amount|currency

Then sign it with the affiliate project postback secret:

signature = HMAC_SHA256(payload, postback_secret)

Requests with invalid signatures return 403.

Response Body

Successful postbacks return order-level reconciliation data:

{
  "ok": true,
  "response_code": "000000",
  "message": "Conversion accepted.",
  "project": "q3-partner-program",
  "conversion_id": 123,
  "order_id": "ORDER-1001",
  "external_id": "checkout_1001",
  "event_type": "sale",
  "status": "pending",
  "deduped": false,
  "sale_amount_cents": 10000,
  "commission_cents": 3500,
  "currency": "USD",
  "occurred_at": "2026-07-09T10:30:00+07:00"
}

Idempotency and Reconciliation

Send a stable order_id for each sale. MCV stores one conversion per project and order ID, preventing duplicate payouts for repeated postbacks.

Conversions enter pending status first. The advertiser that owns the project can approve a valid order and then pay the commission from their wallet to the partner wallet. Operations can still approve, reject, or settle conversions from the affiliate reconciliation console when support or dispute handling is needed.

When a commission is paid, MCV sends the partner a wallet credit email immediately. At the end of each day, MCV sends each advertiser a digest of affiliate conversions paid that day plus the advertiser wallet ending balance. The digest command is php artisan affiliate:send-daily-paid-digest and is scheduled daily at 23:55 Asia/Ho_Chi_Minh.