Introduction
Browser‑based tracking methods increasingly fail: cookie blockers, ITP/ETP policies and restricted third‑party cookies lead to lost attribution data. For merchants this means uncertain commission calculations and rising waste. Server‑to‑Server (S2S) and Conversions API (CAPI) complement client‑side tracking and ensure that conversions are reliably captured, validated and delivered for commission. This guide shows how to set up S2S/CAPI with Affilentra, correctly map event payloads, avoid duplicates and define fallback priorities for the commission process.
Overview: Architecture and Roles
Affilentra provides the role‑separated platform: the merchant reports conversions, affiliates supply click/click‑IDs, and the platform handles tracking, validation and billing. For resilient operation we recommend a hybrid architecture:
- Client‑side tracking (pixel/JS) as the primary, lightweight method to pass click‑IDs.
- Server‑side events (S2S/CAPI) as the reliable source for conversion and payment confirmations.
- Postback mechanisms for partners who send their own server events.
Step 1 — Basic Setup of the S2S Interface
Preparation:
- SSL/TLS for all endpoints is mandatory.
- Issuance of an API key or HMAC key to your Affilentra account (self‑hosted: manageable locally).
- Define a binding event schema and versioning (e.g. v1, v2).
Implementation recommendations:
- Expose a secure POST endpoint on the merchant side that accepts conversions and forwards them to Affilentra, or send directly to Affilentra if your infrastructure handles this.
- Authentication via Authorization header (API key) or HMAC signature over header + timestamp to prevent replay attacks.
- Confirmation responses should return a unique server event ID that Affilentra uses for audits.
Step 2 — Payload Mapping: Required Fields and Meaningful Additions
Consistent mapping reduces matching errors. The following fields should be present in every S2S event:
- event_type: e.g. purchase, refund, lead
- event_id: globally unique ID (UUIDv4 or similar) for deduplication
- transaction_id: shop order/payment number
- click_id / affiliate_id: ID from the affiliate tracking (if available)
- amount and currency: gross amount and currency
- status: authorized, paid, refunded — for deciding on commission entitlement
- timestamp: ISO8601 UTC timestamp
- user_identifiers: hashed email (SHA256), customer ID (optional) — never plaintext emails
Useful optional fields:
- item_lines: SKU, quantity, unit_price — for product‑based commissions
- client_ip, user_agent — for forensic and anomaly checks
- payment_method, shipping_status — for time‑based commissions
Step 3 — Deduplicating & Conversion Validation
Goal: Accept each conversion only once for commission calculation while harmonizing legitimate multiple incoming signals.
Recommended dedup strategy:
- Primary key: event_id. If event_id is present and new, accept and store.
- Fallback key: transaction_id + affiliate_id + window. If event_id is missing, the system checks transaction_id combined with affiliate_id within a configurable time window.
- Source priority: Assign each source a trust level (see next section). In conflicts, the source with higher priority wins.
- Signature verification: HMAC or comparable signature to validate the source.
Validation rules for commission eligibility:
- Only events with status = paid (or explicitly confirmed payment status) trigger commission payouts.
- For refunds or chargebacks: auto‑mark and block or reclaim commission, depending on your business practice.
- Verify that click_id / affiliate_id is plausible and matches the campaign.
Step 4 — Fallback Priorities in the Commission Process
Legend: Sources can be client (browser pixel), server (S2S/CAPI) or partner (affiliate postback). Recommended priorities for most merchants:
- 1. Server‑side payment confirmation (Shop -> Affilentra): Highest trust, because payment status comes from the database.
- 2. Partner postback with validated signature and transaction_id: Direct proof from the affiliate system.
- 3. Server CAPI events that include click IDs and are signed.
- 4. Client‑side pixel/JS event: Good for real‑time, but lower trust with cookie loss.
- 5. Manual/batch imports: Lowest priority and only for reconciliation.
Key rules:
- A conversion already confirmed by a higher‑priority signal must not be overwritten by a later, lower‑priority signal.
- Log conflicts and make them visible in reconciliation processes.
- Configurable time windows: e.g. initial attribution by the client and final status by the server within 24–72 hours (adjustable).
Security and Privacy
Recommendations:
- Transmit personal data only hashed (e.g. SHA256 of the email with salt, if needed).
- Authenticate every S2S request and verify timestamp + nonce to prevent replay attacks.
- Log only the data necessary for troubleshooting and anonymize sensitive information.
- Document schema versions and offer a migration strategy (avoid breaking changes).
Operations and Monitoring
How to ensure operational reliability and traceability:
- Implement a dead‑letter system for rejected/failed events.
- Alerts for anomalies (e.g. sudden drop in S2S events or increase in duplicates).
- Regular reconciliations between shop orders, payment providers and Affilentra reports.
- Audit logs that document changes to commission rules and manual adjustments.
Practical Case: Mapping a Purchase Confirmation
Minimal acceptable payload (example fields):
- event_type: purchase
- event_id: uuid-xyz
- transaction_id: 2026‑000123
- click_id: abc123
- amount: 129.90
- currency: EUR
- status: paid
- timestamp: 2026-10-23T12:34:56Z
- user_identifiers: {email_hash: "sha256:..."}
Important: if click_id is missing, the event may still be processed — however with a lower attribution priority and additional verification of the transaction_id.
Summary
S2S/CAPI events are indispensable to reliably capture conversions when client‑side methods fail. Set up a signed, TLS‑protected S2S interface, use unique event_ids, map required fields consistently and implement a clear source priority for commissions. Monitoring, reconciliation and privacy‑compliant hashing rules complete the setup. The combination of client pixel + S2S/CAPI with deduplicating validation provides the most robust basis for transparent billing via Affilentra.
Next step
Try Affilentra yourself
A unified platform that transparently brings together product delivery, tracking, conversion validation, commission calculation and payout across clearly separated roles; option for a self‑hosted installation with a perpetual license without revenue sharing; merchants retain control over products, conditions and advertising materials; partners receive personal tracking links and a verifiable payout history.