FastCoins Publisher API
Dokumentasi

FastCoins adalah jaringan publisher PTC (Paid-To-Click). Sematkan iklan kami di situsmu, penggunamu mendapat hadiah token untuk melihatnya, dan kamu menerima bagian pendapatan secara otomatis.

Buat akun publisher, verifikasi bahwa domain itu milikmu, dan dapatkan kredensial API setelah ditinjau.

• 1
  Buat akun publisher di FastCoins.com/publisher_dashboard. Kamu perlu nama situs dan URL.
• 2
  Tambahkan domain di tab Domains. Setiap domain punya API Key, Secret Key, Bearer Token, konfigurasi token, dan URL postback sendiri.
• 3
  Atur URL postback-mu — endpoint di servermu yang menerima notifikasi hadiah (lihat bagian Postback di bawah).
• 4
  Hasilkan Bearer Token dari tab Domains. Diperlukan untuk mengautentikasi panggilan API PTC.
• 5
  Kirim postback uji dari tab Domains untuk memastikan endpoint-mu merespons dengan benar sebelum going live.

Notifikasi server-ke-server yang dikirim ke situs webmu saat pengguna selesai melihat iklan, sehingga kamu bisa memberi hadiah secara otomatis tanpa kode sisi klien.

🔐 Persyaratan Keamanan

• IP server yang diizinkan: 62.171.140.250, 2a02:c207:2329:8601::1 — periksa ini hanya terhadap $_SERVER['REMOTE_ADDR']. Ini panggilan langsung server-ke-server, bukan permintaan browser, jadi tidak ada proxy/CDN kami di antaranya; header seperti X-Forwarded-For berasal dari klien dan mudah dipalsukan, jadi jangan percaya untuk pemeriksaan ini.
• userIp wajib ada, bukan sekadar informasi — tolak callback jika hilang atau bukan IP yang valid. Kami selalu me-resolve dan mengirim IP asli pengguna yang menyelesaikan iklan (melalui Cloudflare di pihak kami) justru agar kamu bisa mengandalkannya untuk deteksi penipuan, batas berbasis IP, dan pemeriksaan pengguna ganda — endpoint yang mengabaikannya kehilangan sinyal itu sepenuhnya.
• Respons HTTP wajib: tepat ok — huruf kecil, tanpa spasi, tanpa HTML, HTTP 200
• Algoritma tanda tangan (direkomendasikan): signature_sha256 = HMAC-SHA256(subId + transId + reward, secret_key) — secret_key adalah kunci HMAC, tidak digabungkan ke dalam pesan. userIp bukan bagian darinya.
• Algoritma tanda tangan (lama, tetap dikirim di setiap callback): signature = MD5(subId + transId + reward + secret_key) — nilai digabung tanpa pemisah. Tetap berfungsi tanpa batas waktu untuk integrasi yang dibuat sebelum signature_sha256 ada; tidak ada yang perlu diubah jika kamu sudah memverifikasi yang ini.
• Butuh lebih dari 8 desimal? Setiap callback juga membawa reward_precise (10 desimal) dengan signature_sha256_precise sendiri = HMAC-SHA256(subId + transId + reward_precise, secret_key) — sepenuhnya opsional dan aditif, dihitung dengan cara yang sama, hanya saja pada string dengan presisi lebih tinggi. reward/signature_sha256/signature tetap dikirim persis seperti sebelumnya, terlepas dari apakah kamu memakainya.
• Pencegahan duplikat: selalu periksa transId di database-mu sebelum memberi hadiah

📋 Parameter Postback (GET)

URL postback-mu menerima parameter-parameter ini via HTTP GET.

🧮 Contoh: Membangun & Memverifikasi URL Bertanda Tangan

Contoh lengkap yang sudah dikerjakan supaya kamu bisa menguji perhitungan tanda tanganmu sendiri terhadap milik kami sebelum going live. Secret key yang dipakai adalah buatan, murni untuk ilustrasi.

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

📐 Opsional: Presisi 10 Desimal (reward_precise)

Secret yang sama, callback yang sama — hanya hadiah dengan presisi desimal lebih tinggi daripada yang bisa ditampung 8 desimal milik reward. Sepenuhnya aditif: lewati jika 8 desimal sudah mencakup kasusmu.

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

💻 Implementasi PHP — postback.php

Simpan ini di servermu, atur Secret Key dari tab Domains, lalu tempel URL lengkapnya ke kolom Postback URL di domainmu.

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

🕓 Verifikasi Lama — 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.

🔀 Alur Callback

• 1
  Callback diterima
• 2
  Periksa REMOTE_ADDR terhadap whitelist IP
• 3
  Baca parameter, termasuk userIp
• 4
  Validasi userIp — tolak jika hilang atau bukan IP yang valid
• 5
  Validasi parameter wajib lainnya
• 6
  Verifikasi tanda tangan
• 7
  Periksa status — perlakukan sebagai chargeback jika 2
• 8
  Jika test=1, kembalikan ok tanpa memberi hadiah apa pun
• 9
  Periksa transId terhadap database-mu untuk mencegah hadiah ganda
• 10
  Beri atau batalkan hadiah, dan simpan userIp bersama konversinya
• 11
  Kembalikan ok

Kemungkinan respons:

• ok — callback diproses (atau divalidasi sebagai callback uji)
• ERROR: Invalid source IP
• ERROR: Invalid user IP
• ERROR: Missing parameters
• ERROR: Signature mismatch

Kueri iklan PTC yang tersedia via REST API dan render dengan UI buatanmu sendiri. Tanpa perlu menyematkan widget.

🌐 Endpoint

🔑 Autentikasi — Bearer Token

💻 Contoh 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 Respons

Respons berhasil mengembalikan HTTP 200 dengan struktur JSON ini:

⚠️ Kode Error

Respons error berbagi struktur JSON yang sama dengan kolom status selain 200.

Alur lengkap dari panggilan API hingga pemberian hadiah di situsmu.

📡 Alur API + Postback

🧩 Widget Tertanam (alternatif)

Jika kamu lebih suka tidak memakai API, tanamkan widget sebagai iframe — ia menangani semuanya secara otomatis, dengan gaya yang terisolasi dari sisa halamanmu.

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

Buat tugas (mis. "daftar di situs saya"), danai N penyelesaian, dan konfirmasi masing-masing dengan postback server-ke-server yang bertanda tangan. Pengguna diberi hadiah otomatis begitu postbackmu tiba — tanpa persetujuan manual, tanpa penahanan platform.

📡 Cara kerjanya

1) URL postback

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

• cka_cid — click id yang kami tambahkan ke URL tujuanmu saat pengguna memulai (your-url?cka_cid=…). Kirimkan kembali tanpa diubah.
• sign — hash_hmac('sha256', $cka_cid, $task_secret) (heksadesimal huruf kecil). Secret per tugas ditampilkan di Create Task → My Tasks.

2) Tanda tangan

// 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) Piksel analitik opsional

Tempatkan ini di halaman konversimu untuk analitismu sendiri. Ini tidak pernah memberi hadiah — postback di atas adalah satu-satunya yang memberi hadiah.

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

Rekomendasi untuk integrasi yang andal, aman, dan berpendapatan tinggi.

⚡ Performa

• Simpan respons API dalam cache minimal 60 detik per pengguna. Jangan panggil API di setiap pemuatan halaman — iklan berubah paling cepat setiap beberapa menit.
• Kirimkan IP asli pengguna. Gunakan REMOTE_ADDR secara default — itu satu-satunya nilai yang tidak bisa dipalsukan oleh pengunjung. Baca header proxy sebagai gantinya (mis. CF-Connecting-IP) hanya jika servermu sendiri berada di belakang reverse proxy yang kamu kendalikan dan percayai; jangan pernah header dari klien seperti X-Forwarded-For. IP yang salah menurunkan kualitas penargetan iklan.
• Atur timeout 10 detik pada panggilan cURL-mu untuk mencegah pemuatan halaman lambat jika API kami sedang lambat.

🔒 Keamanan

• Jangan pernah membocorkan Secret Key-mu di kode sisi klien atau repositori publik. Nilai itu hanya dipakai di sisi server untuk validasi tanda tangan.
• Selalu periksa transId terhadap database-mu sebelum memberi hadiah — ini mencegah hadiah ganda akibat pengiriman ulang postback yang tidak disengaja.
• Validasi IP sumber sebelum memproses postback apa pun. Hanya terima permintaan dari 62.171.140.250 atau 2a02:c207:2329:8601::1.
• Gunakan HTTPS untuk endpoint postback-mu. Endpoint HTTP bisa diblokir.
• Kirim satu sub_id unik per pengguna sungguhan. Jangan menambahkan sufiks angka pada satu id dasar (123-1/123-2, ABC_1/ABC_2, order.1/order.2) — pemisah apa pun (- _ .) terdeteksi sebagai penipuan dan ditolak tanpa hadiah. Lihat aturan di atas.

💰 Pendapatan

• Iklan yang di-boost (boosted_campaign: true) membayar lebih — tonjolkan di UI-mu untuk menaikkan rasio klik.
• Iklan lebih panjang (60 detik) membayar jauh lebih banyak daripada iklan pendek (2 detik). Prioritaskan saat keterlibatan pengguna tinggi.
• Seimbangkan bagian pengguna — pembayaran lebih tinggi menarik lebih banyak pengguna aktif; pembayaran lebih rendah menambah marginmu sendiri.
• Penarikan dibuka dari tanggal 1 sampai 3 setiap bulan — tandai di kalendermu.

🐛 Debugging

• Gunakan tombol Test Postback di tab Domains untuk memastikan endpoint-mu mengembalikan tepat ok dengan HTTP 200.
• Periksa tab Postback Logs untuk melihat respons HTTP lengkap dari setiap percobaan postback — di sana ada kode status dan balasan server.
• Postback yang gagal bisa dikirim ulang satu per satu atau secara massal dari tab log. Tidak ada data yang pernah hilang permanen.
• Jika tanda tangan selalu gagal: untuk signature_sha256, pastikan secret_key diberikan sebagai kunci HMAC (bukan digabungkan ke pesan) dan kamu meng-hash subId + transId + reward tanpa pemisah; untuk signature lama, pastikan kamu menggabungkan subId + transId + reward + secret tanpa pemisah. Bagaimanapun, pastikan reward cocok persis dengan string dari parameter GET (tanpa pembulatan).
• Jika kamu memverifikasi signature_sha256_precise: nilai itu di-hash atas reward_precise, bukan reward — mencampur kedua kolom dengan tanda tangan yang salah adalah kesalahan tersering di sini.