FastCoins API de Publisher
Documentación

FastCoins es una red de publishers PTC (Paid-To-Click). Inserta nuestros anuncios en tu sitio, tus usuarios ganan recompensas en tokens por verlos y tú recibes una parte de los ingresos automáticamente.

Crea una cuenta de publisher, verifica que el dominio es tuyo y recibe tus credenciales de API una vez revisado.

• 1
  Crea una cuenta de publisher en FastCoins.com/publisher_dashboard. Necesitarás un nombre de sitio y una URL.
• 2
  Añade un dominio en la pestaña Dominios. Cada dominio tiene su propia API Key, Secret Key, Bearer Token, configuración de token y URL de postback.
• 3
  Configura tu URL de postback: el endpoint de tu servidor que recibe las notificaciones de recompensas (ver la sección de Postback más abajo).
• 4
  Genera un Bearer Token desde la pestaña Dominios. Es necesario para autenticar las llamadas a la API PTC.
• 5
  Envía un postback de prueba desde la pestaña Dominios para verificar que tu endpoint responde correctamente antes de salir a producción.

Una notificación de servidor a servidor que se envía a tu sitio web cuando un usuario termina de ver un anuncio, para que puedas acreditar recompensas automáticamente sin código en el lado del cliente.

🔐 Requisitos de seguridad

• IP del servidor autorizadas: 62.171.140.250, 2a02:c207:2329:8601::1 — comprueba esto únicamente contra $_SERVER['REMOTE_ADDR']. Es una llamada directa de servidor a servidor, no una petición de navegador, así que no hay ningún proxy/CDN nuestro en medio; una cabecera como X-Forwarded-For la suministra el cliente y es trivial falsificarla, así que no confíes en ella para esta comprobación.
• userIp es obligatorio, no es solo informativo: rechaza el callback si falta o no es una IP válida. Siempre resolvemos y enviamos la IP real del usuario que completó el anuncio (a través de Cloudflare en nuestro lado) precisamente para que puedas confiar en ella para detección de fraude, límites por IP y comprobaciones de usuarios duplicados; un endpoint que la ignora pierde por completo esa señal.
• Respuesta HTTP obligatoria: exactamente ok — en minúsculas, sin espacios, sin HTML, HTTP 200
• Algoritmo de firma (recomendado): signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key) — secret_key es la clave HMAC, no se concatena en el mensaje. userIp no forma parte de ella.
• Algoritmo de firma (antiguo, aún se envía en cada callback): signature = MD5(subId + transId + reward + secret_key) — valores concatenados sin separadores. Se mantiene funcionando indefinidamente para las integraciones creadas antes de que existiera signature_sha256; no tienes que cambiar nada si ya verificas esta.
• ¿Necesitas más de 8 decimales? Cada callback también incluye reward_precise (10 decimales) con su propia signature_sha256_precise = HMAC-SHA256(subId + transId + reward_precise, secret_key) — totalmente opcional y aditivo, se calcula igual, solo que sobre la cadena de mayor precisión. reward/signature_sha256/signature siguen enviándose exactamente igual, uses o no esta opción.
• Prevención de duplicados: comprueba siempre transId en tu base de datos antes de acreditar

📋 Parámetros del postback (GET)

Tu URL de postback recibe estos parámetros vía HTTP GET.

🧮 Ejemplo: construcción y verificación de una URL firmada

Un ejemplo completo resuelto para que puedas comprobar tu propio cálculo de firma contra el nuestro antes de salir a producción. La clave secreta usada es inventada, solo a modo de ilustración.

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

📐 Opcional: precisión de 10 decimales (reward_precise)

Misma clave secreta, mismo callback — solo una recompensa con más precisión decimal de la que los 8 decimales de reward pueden contener. Totalmente aditivo: ignóralo si 8 decimales ya cubren tu caso de uso.

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

💻 Implementación en PHP — postback.php

Guarda esto en tu servidor, configura tu Secret Key de la pestaña Dominios y pega la URL completa en el campo Postback URL de tu dominio.

// ── 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

🕓 Verificación antigua — 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.

🔀 Flujo del callback

• 1
  Callback recibido
• 2
  Comprueba REMOTE_ADDR contra la lista blanca de IP
• 3
  Lee los parámetros, incluido userIp
• 4
  Valida userIp — recházalo si falta o no es una IP válida
• 5
  Valida los demás parámetros obligatorios
• 6
  Verifica la firma
• 7
  Comprueba status — aplícalo como contracargo si es 2
• 8
  Si test=1, devuelve ok sin acreditar nada
• 9
  Comprueba transId contra tu base de datos para evitar acreditar duplicados
• 10
  Acredita o revierte la recompensa, y guarda userIp junto a la conversión
• 11
  Devuelve ok

Respuestas posibles:

• ok — callback procesado (o validado como callback de prueba)
• ERROR: Invalid source IP
• ERROR: Invalid user IP
• ERROR: Missing parameters
• ERROR: Signature mismatch

Consulta los anuncios PTC disponibles mediante una API REST y muéstralos con tu propia interfaz. No requiere insertar ningún widget.

🌐 Endpoint

🔑 Autenticación — Bearer Token

💻 Ejemplo en 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.';
}

📦 Formato de respuesta

Las respuestas correctas devuelven HTTP 200 con esta estructura JSON:

⚠️ Códigos de error

Las respuestas de error comparten la misma estructura JSON con un campo de estado distinto de 200.

El flujo completo, desde la llamada a la API hasta el crédito de la recompensa en tu sitio.

📡 Flujo de API + Postback

🧩 Widget insertado (alternativa)

Si prefieres no usar la API, inserta el widget como un iframe — gestiona todo automáticamente y con estilos aislados del resto de tu página.

<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>

Crea una tarea (p. ej. "regístrate en mi sitio"), fondea N finalizaciones y confirma cada una con un postback firmado de servidor a servidor. El usuario recibe la recompensa automáticamente en cuanto llega tu postback — sin aprobación manual ni retención de la plataforma.

📡 Cómo funciona

1) La URL del postback

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

• cka_cid — el click id que añadimos a tu URL de destino cuando el usuario empezó (your-url?cka_cid=…). Devuélvelo sin cambios.
• sign — hash_hmac('sha256', $cka_cid, $task_secret) (hex en minúsculas). El secreto de cada tarea se muestra en Create Task → My Tasks.

2) Firma

// 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) Píxel de analítica opcional

Coloca esto en tu página de conversión para tu propia analítica. Nunca acredita — el postback de arriba es lo único que acredita.

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

Recomendaciones para una integración fiable, segura y con altos ingresos.

⚡ Rendimiento

• Guarda en caché las respuestas de la API durante al menos 60 segundos por usuario. No llames a la API en cada carga de página — los anuncios cambian como mucho cada pocos minutos.
• Pasa la IP real del usuario. Usa REMOTE_ADDR por defecto — es el único valor que el visitante no puede falsificar. Lee una cabecera de proxy en su lugar (p. ej. CF-Connecting-IP) solo si tu propio servidor está detrás de un proxy inverso que controlas y en el que confías; nunca una cabecera suministrada por el cliente como X-Forwarded-For. Las IP incorrectas reducen la calidad de la segmentación de anuncios.
• Configura un timeout de 10 segundos en tus llamadas cURL para evitar cargas de página lentas si nuestra API va lenta temporalmente.

🔒 Seguridad

• Nunca expongas tu Secret Key en código del lado del cliente ni en repositorios públicos. Solo se usa en el servidor para validar firmas.
• Comprueba siempre transId contra tu base de datos antes de acreditar — esto evita recompensas duplicadas por reenvíos accidentales del postback.
• Valida la IP de origen antes de procesar cualquier postback. Acepta únicamente peticiones de 62.171.140.250 o 2a02:c207:2329:8601::1.
• Usa HTTPS en tu endpoint de postback. Los endpoints HTTP pueden bloquearse.
• Envía un único sub_id por usuario real. No añadas sufijos numéricos a un id base (123-1/123-2, ABC_1/ABC_2, order.1/order.2) — cualquier separador (- _ .) se detecta como fraude y se rechaza sin acreditar recompensa. Ver la regla anterior.

💰 Ingresos

• Los anuncios potenciados (boosted_campaign: true) pagan más — destácalos en tu interfaz para aumentar las tasas de clic.
• Los anuncios largos (60 s) pagan bastante más que los cortos (2 s). Priorízalos cuando la participación de tus usuarios sea alta.
• Equilibra el porcentaje del usuario — un pago mayor atrae más usuarios activos; un pago menor aumenta tu propio margen.
• Los retiros están abiertos del 1 al 3 de cada mes — márcalo en tu calendario.

🐛 Depuración

• Usa el botón Probar postback de la pestaña Dominios para verificar que tu endpoint devuelve exactamente ok con HTTP 200.
• Consulta la pestaña Registros de postback para ver las respuestas HTTP completas de cada intento de postback — muestra los códigos de estado y las respuestas del servidor.
• Los postbacks fallidos pueden reenviarse individualmente o en lote desde la pestaña de registros. Nunca se pierden datos de forma permanente.
• Si la firma siempre falla: para signature_sha256, comprueba que secret_key se pasa como la clave HMAC (no concatenada en el mensaje) y que calculas el hash de subId + transId + reward sin separadores; para el signature antiguo, comprueba que concatenas subId + transId + reward + secret sin separadores. En cualquier caso, asegúrate de que reward coincide exactamente con la cadena del parámetro GET (sin redondear).
• Si verificas signature_sha256_precise: se calcula sobre reward_precise, no sobre reward — mezclar los dos campos con la firma equivocada es el error más común aquí.