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={api_key}&event=ftd&player_token={player_id}&amount={amount}&currency={currency}&click_id={click_id}&transaction_id={transaction_id}"

Replace {api_key} with your key and every other {…} with your tracking platform’s placeholder for that value.

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 and we store only a hash. Send postbacks over HTTPS only. If a key leaks, ask your AFFILIFY contact to revoke it and issue a new one. Every postback URL using the old key stops working at once.

Send the key in one of these ways. The api_key parameter wins over the Authorization and X-API-Key headers. In the path form the key in the path is used instead of an api_key query parameter.

https://affilify.partners/pb?api_key={api_key}&event=ftd&player_token={player_id}
Authorization: Bearer {api_key}
X-API-Key: {api_key}
https://affilify.partners/pb/{api_key}/{event}?player_token={player_id}   (path form)

The path form suits platforms that only accept short postback URLs. The key and event travel in the path; every other parameter stays in the query string.

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.

Values your platform fills in must arrive filled in. If one still arrives as a placeholder such as {player_id}, [player_id] or ##player_id##: a placeholder in the player, the event, or the amount of an ftd, deposit, ngr, purchase or subscription is rejected with 422; a placeholder in the click ID, transaction ID, currency or period is ignored and named in warnings (see §7).

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. Always send one: without it we cannot tell a retry from a new event, so a retry may be counted twice, and repeated NGR updates for the same player may be dropped.

{ "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, "event_id": "…", "warnings": ["click_id_macro_dropped"] }   // accepted; see warnings below
200  { "ok": true, "duplicate": true }                  // a retry we'd already recorded
200  { "ok": true, "ignored": true, "reason": "event_not_allowed" }   // this event type is switched off for your brand
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" }
400  { "ok": false, "error": "amount out of range" }
400  { "ok": false, "error": "invalid event_type" }     // use a listed event, or ask us to map yours
401  { "ok": false, "error": "invalid api key" }        // unknown or revoked key
422  { "ok": false, "error": "unsubstituted_macro", "field": "player_token", "value": "{player_id}", "hint": "…", "http_status": 422 }
422  { "ok": false, "error": "placeholder_value" | "partial_macro", "field": "…", "value": "…", "hint": "…", "http_status": 422 }
500  { "ok": false, "error": "internal_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.

A 422 means a value arrived as a placeholder your tracking platform did not replace. field names the parameter, value shows what arrived and hint says what to check. Fix the placeholder name in your postback settings; resending the same request will not help.

warnings appears on an accepted or duplicate response only when something was ignored or defaulted:

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={api_key}&event=registration&player_token={player_id}&click_id={click_id}&transaction_id={transaction_id}

# First-time deposit
https://affilify.partners/pb?api_key={api_key}&event=ftd&player_token={player_id}&amount={amount}&currency={currency}&click_id={click_id}&transaction_id={transaction_id}

# Net gaming revenue for a month
https://affilify.partners/pb?api_key={api_key}&event=ngr&player_token={player_id}&amount={amount}&currency={currency}&period={period}&transaction_id={transaction_id}

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

Each {…} is your tracking platform’s placeholder for that value. {click_id} is a UUID such as 7c9e6679-7425-40de-944b-e07fc1f37d4a; {period} is a month such as 2026-09.

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.

A test postback still creates the player record and uses up its transaction ID. Use a player ID and transaction ID no real player will ever have, and remove test=1 before go-live.