Sending conversions to AFFILIFY

1. Quick start

1. Get an API key from your AFFILIFY contact (issued per brand; shown once).
2. When a player converts, fire a GET or POST to the postback URL with the event and the player’s identifier.
3. Pass the click identifier (click_id) we appended to the landing URL so we can attribute the player to the right affiliate.

curl "https://affilify.partners/pb?api_key=YOUR_KEY&event=ftd&player_token=PLAYER123&amount=200&currency=USD&click_id=CLICK_ID&transaction_id=TXN_987"

2. Endpoint

Both methods are accepted. Parameters may be sent as query string (GET or POST) or as a JSON body (POST).

GET  https://affilify.partners/pb
POST https://affilify.partners/pb           (query string or application/json body)
POST https://affilify.partners/api/public/postback   (identical long alias)

3. Authentication

Every request must include your api_key. Keys are scoped to a single brand; we store only a hash, so a leaked key can be revoked and re-issued without affecting anyone else. Send postbacks over HTTPS only.

4. Parameters

We accept common aliases for each field, so you can usually keep your existing naming. The whole raw payload is stored either way, so nothing you send is lost.

5. Event types

Send the event under the value above. If your system uses different names (e.g. first_deposit), tell us and we map it to the right type on our side — you don’t have to change your stack.

6. Idempotency & retries

Send a unique transaction_id (or idempotency_key) per event. We dedupe on it, so you can safely retry on a network error or timeout — a repeated event is acknowledged but never double-counted. If you omit it, we derive one from brand + player + event + period.

{ "ok": true, "duplicate": true }   // a retry we’d already recorded

7. Responses

Every response is JSON with a meaningful HTTP status. 4xx means the request was rejected — fix it, don’t blindly retry. Retry only on 5xx or a network/timeout error (see §6).

200  { "ok": true, "event_id": "…", "affiliate_attributed": true, "test": false }
200  { "ok": true, "duplicate": true }                  // a retry we'd already recorded
400  { "ok": false, "error": "missing api_key" }
400  { "ok": false, "error": "missing event or player_token" }
400  { "ok": false, "error": "amount must be a number" }
401  { "ok": false, "error": "invalid api key" }
401  { "ok": false, "error": "invalid event_type" }     // use a listed event, or ask us to map yours
500  { "ok": false, "error": "…" }                       // transient — safe to retry

affiliate_attributed: false means we accepted the event but couldn’t tie it to an affiliate (usually a missing click_id). It’s stored regardless and can be reconciled later.

8. How attribution works

1. An affiliate shares a tracking link: https://affilify.partners/r/CODE.
2. We record the click and redirect to your landing page, appending a click_id to the URL.
3. You persist that click_id against the player on registration.
4. On every conversion postback, you echo it back as click_id — we attribute the player to that affiliate. After the first event the player is remembered, so later postbacks attribute automatically.

9. Examples

# Registration
https://affilify.partners/pb?api_key=KEY&event=registration&player_token=P1&click_id=CID&transaction_id=reg_P1

# First-time deposit
https://affilify.partners/pb?api_key=KEY&event=ftd&player_token=P1&amount=200&currency=USD&transaction_id=dep_55

# Net gaming revenue for a period
https://affilify.partners/pb?api_key=KEY&event=ngr&player_token=P1&amount=84.50&period=2026-06&transaction_id=ngr_P1_202606

# JSON POST
curl -X POST https://affilify.partners/pb -H "content-type: application/json" \
  -d '{"api_key":"KEY","event":"deposit","player_token":"P1","amount":50,"transaction_id":"dep_56"}'

10. Testing

Add test=1 to any postback. It validates and stores end-to-end exactly like a live event, but is flagged as a test and excluded from commissions and payouts — so you can wire up and verify safely before go-live.