FastCoins API Publisher
Documentation

FastCoins est un réseau de publishers PTC (Paid-To-Click). Intègre nos publicités sur ton site, tes utilisateurs gagnent des récompenses en tokens en les regardant, et tu perçois automatiquement une part des revenus.

Crée un compte publisher, vérifie que le domaine t'appartient et reçois tes identifiants API une fois qu'il est examiné.

• 1
  Crée un compte publisher sur FastCoins.com/publisher_dashboard. Il te faut un nom de site et une URL.
• 2
  Ajoute un domaine dans l'onglet Domains. Chaque domaine a sa propre API Key, Secret Key, Bearer Token, configuration de token et URL de postback.
• 3
  Définis ton URL de postback — l'endpoint sur ton serveur qui reçoit les notifications de récompense (voir la section Postback ci-dessous).
• 4
  Génère un Bearer Token depuis l'onglet Domains. Indispensable pour authentifier les appels à l'API PTC.
• 5
  Envoie un postback de test depuis l'onglet Domains pour vérifier que ton endpoint répond correctement avant la mise en production.

Une notification serveur à serveur envoyée à ton site web quand un utilisateur termine la vue d'une publicité, pour que tu puisses créditer les récompenses automatiquement, sans aucun code côté client.

🔐 Exigences de sécurité

• IP serveur autorisées: 62.171.140.250, 2a02:c207:2329:8601::1 — vérifie ceci uniquement contre $_SERVER['REMOTE_ADDR']. Il s'agit d'un appel direct de serveur à serveur, pas d'une requête de navigateur : aucun proxy/CDN de notre part ne s'intercale ; un en-tête comme X-Forwarded-For est fourni par le client et trivialement falsifiable, ne te fie donc pas à lui pour cette vérification.
• userIp est obligatoire, pas seulement informatif — rejette le callback s'il est absent ou si ce n'est pas une IP valide. Nous résolvons et envoyons toujours l'IP réelle du visiteur qui a terminé la publicité (via Cloudflare de notre côté) précisément pour que tu puisses t'y fier : détection de fraude, limites par IP, contrôles d'utilisateurs en double — un endpoint qui l'ignore perd complètement ce signal.
• Réponse HTTP requise : exactement ok — en minuscules, sans espaces, sans HTML, HTTP 200
• Algorithme de signature (recommandé) : signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key) — secret_key est la clé HMAC, elle n'est pas concaténée dans le message. userIp n'en fait pas partie.
• Algorithme de signature (ancien, toujours envoyé à chaque callback) : signature = MD5(subId + transId + reward + secret_key) — valeurs concaténées sans séparateur. Maintenu indéfiniment pour les intégrations créées avant l'existence de signature_sha256 ; rien à changer si tu vérifies déjà celle-ci.
• Besoin de plus de 8 décimales ? Chaque callback transporte aussi reward_precise (10 décimales) avec son propre signature_sha256_precise = HMAC-SHA256(subId + transId + reward_precise, secret_key) — totalement optionnel et additif, calculé de la même façon, simplement sur la chaîne plus précise. reward/signature_sha256/signature continuent d'être envoyés exactement comme avant, que tu l'utilises ou non.
• Prévention des doublons : vérifie toujours transId dans ta base de données avant de créditer

📋 Paramètres du postback (GET)

Ton URL de postback reçoit ces paramètres via HTTP GET.

🧮 Exemple : construction et vérification d'une URL signée

Un exemple complet et détaillé pour que tu puisses confronter ton propre calcul de signature au nôtre avant la mise en production. La clé secrète utilisée est inventée, purement pour illustrer.

Secret Key (example only, never a real one): demo_secret_do_not_use_9f8e7d6c

Parameters for this conversion:
  subId   = user_12345
  transId = txn_987654321
  reward  = 0.50
  status  = 1
  userIp  = 127.0.0.1

signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key)
                  = HMAC-SHA256("user_12345" . "txn_987654321" . "0.50", demo_secret_do_not_use_9f8e7d6c)
                  = HMAC-SHA256("user_12345txn_9876543210.50", demo_secret_do_not_use_9f8e7d6c)
                  = df3eafaa3e8cf4fe8fb40c7bed633f34bc7b964bca58d2d691314771a042d59c

signature (legacy) = MD5(subId + transId + reward + secret_key)
                    = MD5("user_12345" . "txn_987654321" . "0.50" . "demo_secret_do_not_use_9f8e7d6c")
                    = MD5("user_12345txn_9876543210.50demo_secret_do_not_use_9f8e7d6c")
                    = d1eb68e41cbd5770de9384c5be8ebb39

Resulting callback URL:
https://yoursite.com/postback.php?subId=user_12345&transId=txn_987654321&reward=0.50&status=1&userIp=127.0.0.1&signature=d1eb68e41cbd5770de9384c5be8ebb39&signature_sha256=df3eafaa3e8cf4fe8fb40c7bed633f34bc7b964bca58d2d691314771a042d59c

📐 Optionnel : précision à 10 décimales (reward_precise)

Même clé secrète, même callback — juste une récompense avec plus de précision décimale que ne le permettent les 8 décimales de reward. Totalement additif : passe ton chemin si 8 décimales couvrent déjà ton cas.

Same secret key and subId/transId as above, but the underlying reward this
time carries more precision:

  reward          = 0.12345679   (8 decimals, rounded)
  reward_precise  = 0.1234567890 (10 decimals)

signature_sha256_precise = HMAC-SHA256(subId + transId + reward_precise, secret_key)
                          = HMAC-SHA256("user_12345" . "txn_987654321" . "0.1234567890", demo_secret_do_not_use_9f8e7d6c)
                          = 219d2101a528b8585161bd26c3bb80c5de8a6741d60d2f1778eb805a05f7a707

💻 Implémentation PHP — postback.php

Enregistre ceci sur ton serveur, renseigne ta Secret Key de l'onglet Domains, puis colle l'URL complète dans le champ Postback URL de ton domaine.

// ── 1. YOUR SECRET KEY (from Domains tab → Secret Key) ─────
$secret = "";  // ← paste your secret key here

// ── 2. IP VALIDATION (callback source) ──────────────────────
// REMOTE_ADDR only — this call comes straight from our server to
// yours, no browser and no proxy of ours in between, so it's the
// one value here that can't be spoofed by whoever is calling you.
// X-Forwarded-For (or any other header) is attacker-controlled and
// must never be trusted for this check.
$allowed_ips = ['62.171.140.250', '2a02:c207:2329:8601::1'];
$ip = $_SERVER['REMOTE_ADDR'] ?? '';
if (!in_array($ip, $allowed_ips, true)) {
    echo "ERROR: Invalid source IP";
    exit;
}

// ── 3. COLLECT PARAMETERS ───────────────────────────────────
$userId    = $_GET['subId']     ?? null;
$transId   = $_GET['transId']   ?? null;
$status    = $_GET['status']    ?? null;
$isTest    = isset($_GET['test']) && $_GET['test'] == 1;
$userIp    = $_GET['userIp']   ?? null;  // real IP of the ad viewer — required, see step 4

// ── 3b. DYNAMIC PRECISION ────────────────────────────────────
// Prefer reward_precise (10 decimals) when the callback carries it;
// fall back to the standard reward (8 decimals) otherwise. Whichever
// pair is picked, it's verified against its own matching signature in
// step 6 — if that signature is valid, the postback is accepted.
$hasPrecise = isset($_GET['reward_precise'], $_GET['signature_sha256_precise']);
$reward    = $hasPrecise ? $_GET['reward_precise']           : ($_GET['reward'] ?? null);
$signature = $hasPrecise ? $_GET['signature_sha256_precise'] : ($_GET['signature_sha256'] ?? null);

// ── 4. VALIDATE USER IP (required) ──────────────────────────
// userIp is mandatory — this is the real IP of the person who
// completed the offer, already resolved through Cloudflare on our
// end. Reject the callback outright rather than silently accepting
// one without it, since your fraud detection / IP-limit / duplicate-
// user checks depend on this value actually being present and valid.
if (!$userIp || !filter_var($userIp, FILTER_VALIDATE_IP)) {
    echo "ERROR: Invalid user IP";
    exit;
}

// ── 5. VALIDATE REQUIRED PARAMS ─────────────────────────────
if (!$userId || !$transId || $reward === null || !$signature) {
    echo "ERROR: Missing parameters";
    exit;
}

// ── 6. VERIFY SIGNATURE ─────────────────────────────────────
// Only subId + transId + reward go into this hash — userIp is NOT
// part of it. $secret is the HMAC key, not concatenated into the
// message. Don't add userIp here unless a different provider's docs
// explicitly say their signature scheme includes it.
$expected = hash_hmac('sha256', $userId . $transId . $reward, $secret);
if (!hash_equals($expected, $signature)) {
    echo "ERROR: Signature mismatch";
    exit;
}

// ── 7. HANDLE CHARGEBACK (status = 2) ───────────────────────
if ((int)$status === 2) {
    $reward = -abs((float)$reward);  // negative = deduct
}

// ── 8. TEST CALLBACK ─────────────────────────────────────────
// Authenticated and validated like any other callback, but must not
// touch a real balance.
if ($isTest) {
    echo "ok";
    exit;
}

// ── 9. PREVENT DUPLICATES, CREDIT REWARD & STORE USER IP ──────
// Replace with your actual DB logic.
if (!isTransactionProcessed($transId)) {
    creditUserReward($userId, $reward, $transId);
    // If your credit function only takes these 3 args, store $userIp
    // with the conversion separately, e.g.:
    //   saveConversionIp($transId, $userId, $userIp);
}

// ── 10. REQUIRED RESPONSE ───────────────────────────────────
echo "ok";  // MUST return exactly this, nothing else

🕓 Vérification ancienne — MD5

$signature = $_GET['signature'] ?? null;
$expected  = md5($userId . $transId . $reward . $secret);
if (!hash_equals($expected, $signature)) {
    echo "ERROR: Signature mismatch";
    exit;
}
// ...same IP check, userIp check, and crediting logic as the main example above.

🔀 Flux du callback

• 1
  Callback reçu
• 2
  Vérifie REMOTE_ADDR contre la liste blanche d'IP
• 3
  Lis les paramètres, y compris userIp
• 4
  Valide userIp — rejette s'il est absent ou si ce n'est pas une IP valide
• 5
  Valide les autres paramètres requis
• 6
  Vérifie la signature
• 7
  Vérifie status — traite comme une rétrofacturation si 2
• 8
  Si test=1, renvoie ok sans rien créditer
• 9
  Vérifie transId dans ta base de données pour éviter les crédits en double
• 10
  Crédite ou annule la récompense, et stocke userIp avec la conversion
• 11
  Renvoie ok

Réponses possibles :

• ok — callback traité (ou validé comme callback de test)
• ERROR: Invalid source IP
• ERROR: Invalid user IP
• ERROR: Missing parameters
• ERROR: Signature mismatch

Interroge les publicités PTC disponibles via une API REST et affiche-les avec ta propre interface. Aucun widget à intégrer.

🌐 Endpoint

🔑 Authentification — Bearer Token

💻 Exemple PHP

// ── YOUR CREDENTIALS (from Domains tab) ─────────────────────
$apiKey      = 'YOUR_API_KEY';
$bearerToken = 'YOUR_BEARER_TOKEN';

// ── USER DATA ────────────────────────────────────────────────
$userId = $_SESSION['user_id'];  // your user's unique ID
// REMOTE_ADDR by default — it's the one value here that can't be
// spoofed by the visitor. Only read a proxy header instead (e.g.
// CF-Connecting-IP) if your own server sits behind a reverse proxy
// you control and trust — never a client-supplied header like
// X-Forwarded-For, which the visitor's own browser can set to
// anything.
$userIp = $_SERVER['REMOTE_ADDR'] ?? '';

// Required once any advertiser runs a device-targeted campaign — this
// script call happens during the visitor's own page load, so THIS
// server's incoming User-Agent is theirs. Don't skip this: a call from a
// background job/cron with no real visitor attached has no correct value
// to send here.
$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
$device    = preg_match('/Mobi|Android|iPhone|iPod|iPad|BlackBerry|IEMobile|Opera Mini/i', $userAgent)
    ? 'mobile' : 'desktop';

// ── BUILD URL ────────────────────────────────────────────────
$url = 'https://FastCoins.com/api/' . $apiKey
     . '/' . urlencode($userId)
     . '/' . urlencode($userIp)
     . '/' . $device;

// ── CURL REQUEST ─────────────────────────────────────────────
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $bearerToken,
        'Accept: application/json',
    ],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

// ── HANDLE RESPONSE ──────────────────────────────────────────
if ($httpCode === 200 && $data['status'] === '200') {
    foreach ($data['data'] as $ad) {
        // $ad['url'] already contains the user subId encoded
        echo '<a href="' . htmlspecialchars($ad['url']) . '" target="_blank">';
        echo htmlspecialchars($ad['title']);
        echo ' — ' . $ad['reward'] . ' ' . $ad['currency_name'];
        echo '</a><br>';
    }
} else {
    echo 'No ads available.';
}

📦 Format de réponse

Les réponses réussies renvoient HTTP 200 avec cette structure JSON :

⚠️ Codes d'erreur

Les réponses d'erreur partagent la même structure JSON avec un champ de statut différent de 200.

Le flux complet, de l'appel API au crédit de la récompense sur ton site.

📡 Flux API + Postback

🧩 Widget intégré (alternative)

Si tu préfères ne pas utiliser l'API, intègre le widget en iframe — il gère tout automatiquement, avec des styles isolés du reste de ta page.

<iframe src="https://fastcoins.click/widget-embed.php?api_key=YOUR_API_KEY&sub_id={USER_ID}"
    style="width:100%;height:640px;border:none;" loading="lazy"></iframe>

Crée une tâche (p. ex. "inscris-toi sur mon site"), finance N complétions et confirme chacune avec un postback signé de serveur à serveur. L'utilisateur est crédité automatiquement dès l'arrivée de ton postback — pas de validation manuelle, pas de retenue de la plateforme.

📡 Comment ça marche

1) L'URL du postback

GET https://fastcoins.click/webhooks/task-postback.php?cka_cid={CLICK_ID}&sign={SIGN}

• cka_cid — le click id que nous avons ajouté à ton URL de destination au départ de l'utilisateur (your-url?cka_cid=…). Renvoie-le tel quel.
• sign — hash_hmac('sha256', $cka_cid, $task_secret) (hex minuscule). Le secret propre à chaque tâche est affiché dans Create Task → My Tasks.

2) Signature

// PHP
$sign = hash_hmac('sha256', $cka_cid, $task_secret);

// Node.js
const sign = crypto.createHmac('sha256', taskSecret).update(ckaCid).digest('hex');

# Python
import hmac, hashlib
sign = hmac.new(task_secret.encode(), cka_cid.encode(), hashlib.sha256).hexdigest()

3) Pixel analytics optionnel

Place ceci sur ta page de conversion pour tes propres statistiques. Il ne crédite jamais — le postback ci-dessus est la seule chose qui crédite.

<img src="https://fastcoins.click/task-pixel.php?cid={CLICK_ID}" width="1" height="1" alt="">

Recommandations pour une intégration fiable, sécurisée et rentable.

⚡ Performances

• Mets les réponses de l'API en cache pendant au moins 60 secondes par utilisateur. N'appelle pas l'API à chaque chargement de page — les publicités changent au maximum toutes les quelques minutes.
• Transmets la vraie IP de l'utilisateur. Utilise REMOTE_ADDR par défaut — c'est la seule valeur impossible à falsifier par le visiteur. Ne lis un en-tête de proxy à la place (p. ex. CF-Connecting-IP) que si ton propre serveur est derrière un reverse proxy que tu contrôles et auquel tu fais confiance ; jamais un en-tête fourni par le client comme X-Forwarded-For. Des IP incorrectes dégradent la qualité du ciblage publicitaire.
• Règle un timeout de 10 secondes sur tes appels cURL pour éviter des chargements de page lents si notre API est temporairement lente.

🔒 Sécurité

• N'expose jamais ta Secret Key dans du code côté client ou des dépôts publics. Elle n'est utilisée que côté serveur, pour la validation des signatures.
• Vérifie toujours transId dans ta base de données avant de créditer — cela évite les récompenses en double dues à des renvois accidentels de postback.
• Valide l'IP source avant de traiter tout postback. N'accepte les requêtes que de 62.171.140.250 ou 2a02:c207:2329:8601::1.
• Utilise HTTPS pour ton endpoint de postback. Les endpoints HTTP peuvent être bloqués.
• Envoie un seul sub_id par utilisateur réel. N'ajoute pas de suffixes numériques à un id de base (123-1/123-2, ABC_1/ABC_2, order.1/order.2) — tout séparateur (- _ .) est détecté comme fraude et rejeté sans crédit de récompense. Voir la règle ci-dessus.

💰 Revenus

• Les publicités boostées (boosted_campaign: true) rapportent plus — mets-les en évidence dans ton interface pour augmenter les taux de clic.
• Les publicités longues (60 s) rapportent nettement plus que les courtes (2 s). Priorise-les quand l'engagement des utilisateurs est élevé.
• Équilibre la part de l'utilisateur — un paiement plus élevé attire plus d'utilisateurs actifs ; un paiement plus faible augmente ta propre marge.
• Les retraits sont ouverts du 1 au 3 de chaque mois — note-le dans ton agenda.

🐛 Débogage

• Utilise le bouton Test Postback dans l'onglet Domains pour vérifier que ton endpoint renvoie exactement ok avec HTTP 200.
• Consulte l'onglet Postback Logs pour voir les réponses HTTP complètes de chaque tentative de postback — il affiche les codes de statut et les réponses du serveur.
• Les postbacks en échec peuvent être renvoyés un par un ou en masse depuis l'onglet des logs. Aucune donnée n'est jamais définitivement perdue.
• Si la signature échoue toujours : pour signature_sha256, vérifie que secret_key est passée comme clé HMAC (et non concaténée dans le message) et que tu haches subId + transId + reward sans séparateur ; pour l'ancien signature, vérifie que tu concatènes subId + transId + reward + secret sans séparateur. Dans tous les cas, assure-toi que reward correspond exactement à la chaîne du paramètre GET (sans arrondi).
• Si tu vérifies signature_sha256_precise : le hachage se fait sur reward_precise, pas sur reward — mélanger les deux champs avec la mauvaise signature est l'erreur la plus courante ici.