FonProxy API — Referral

All /referral/* endpoints require Authorization: Bearer <token>.

---

Get Referral Info

GET /referral

Returns the user's referral code, percentages, and stats. Auto-creates a referral code on first access.

Response (200):

{
  "id": "xK9mR2pL1w",
  "code": "a3f8c2d1",
  "incomePercentage": 5,
  "salePercentage": 0,
  "clicks": 142,
  "registrations": 23,
  "totalIncome": 12.50,
  "pendingIncome": 3.75
}

Field	Type	Description
id	string	Referral hashId
code	string	Editable referral code (used in referral link)
incomePercentage	number	Percentage the referrer earns from each referred top-up
salePercentage	number	Discount percentage for referred users (future)
clicks	number	Total visitors who came via this referral
registrations	number	Total users who registered via this referral
totalIncome	number	Total completed referral income (USD)
pendingIncome	number	Pending referral income not yet credited (USD)

---

Update Referral Code

PATCH /referral/code

Update the referral code. Must be 3–30 characters, alphanumeric + underscore + hyphen.

Request body:

{ "code": "john_doe" }

Response (200):

{ "code": "john_doe", "message": "referral.code_updated" }

Errors:

{ "message": "referral.code_invalid" }
{ "message": "referral.code_taken" }

---

Referral Graph

GET /referral/graph

Returns time-series chart data for clicks, registrations, and income.

Query parameters:

Param	Type	Default	Description
from	string	30 days ago	ISO date start
to	string	now	ISO date end
granularity	string	auto	hour, day, week, month

Response (200):

{
  "graph": "referral",
  "granularity": "day",
  "from": "2026-02-23T00:00:00.000Z",
  "to": "2026-03-25T00:00:00.000Z",
  "series": [
    {
      "key": "clicks",
      "label": "Clicks",
      "color": "#3B82F6",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 15 },
        { "t": "2026-03-25T00:00:00.000Z", "v": 8 }
      ]
    },
    {
      "key": "registrations",
      "label": "Registrations",
      "color": "#22C55E",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 3 },
        { "t": "2026-03-25T00:00:00.000Z", "v": 1 }
      ]
    },
    {
      "key": "income",
      "label": "Income (USD)",
      "color": "#E6318B",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 2.50 },
        { "t": "2026-03-25T00:00:00.000Z", "v": 0 }
      ]
    }
  ],
  "meta": { "currency": "USD" }
}

---

How Referrals Work

1. User gets a unique referral code from GET /referral
2. Frontend builds a link: https://fonproxy.com/?ref=<code>
3. Visitor arrives → frontend calls POST /track/init with invitedBy: "<code_owner_hashId>"
4. Visitor registers → invitedById is set on the new user + referrer is notified
5. Referred user tops up → a pending referral income transaction is created for the referrer
6. After 2 days (instant in dev mode) the pending transaction is credited to the referrer's balance + referrer is notified
7. User can track everything in GET /referral and GET /referral/graph