LinkCash.id Partner API

API untuk mitra yang membangun aplikasi cashback sendiri di atas LinkCash.id. Dipanggil dari server mitra (bukan dari aplikasi/peramban pengguna), berformat JSON lewat HTTPS.

Mulai

  1. Minta akses ke pengelola LinkCash.id (support@linkcash.id) dengan menyertakan alamat website/aplikasimu, IP publik server, dan URL callback (boleh menyusul).
  2. Kamu menerima API key (hanya diberikan sekali — simpan di variabel lingkungan server) dan secret callback.
  3. Uji sambungan dengan GET /ping.

Postman

Import → pilih berkas openapi.yaml → di tab Authorization koleksinya pilih Bearer Token dan isi API key. Permintaan hanya diterima dari IP terdaftar, jadi daftarkan juga IP tempat kamu menjalankan Postman.

Base URL

https://api.linkcash.id/v1

Header wajib

Authorization: Bearer lc_live_xxxxxxxxxxxxxxxx

Alur integrasi

  1. Tampilkan toko (GET /merchants) dan/atau produk (GET /products) di aplikasimu.
  2. Saat user memilih, servermu memanggil POST /links dengan user_id milikmu → dapat link https://linkcash.id/go/….
  3. Arahkan user ke link itu tepat sebelum belanja. User belanja dan membayar seperti biasa di tokonya.
  4. Transaksi tercatat (umumnya 1–2 hari) berstatus pending → kamu menerima callback, atau menariknya lewat GET /conversions.
  5. Setelah toko memvalidasi pesanan (umumnya 30–60 hari) status menjadi approved, lalu paid setelah dibayarkan ke mitra. Pesanan batal/retur menjadi rejected.

Satu tingkat. Pendapatan dihitung per transaksi untuk akun mitra (earning). Pembagian ke user — termasuk skema referral/berjenjang apa pun — sepenuhnya diatur di sistemmu sendiri.

Status transaksi

pending   tercatat, menunggu validasi toko
approved  divalidasi, menunggu dibayarkan
paid      sudah dibayarkan ke mitra
rejected  batal / retur / ditolak toko

Autentikasi & batas

  • Setiap permintaan menyertakan API key di header Authorization: Bearer …. Key tidak diterima lewat URL.
  • Jangan menaruh key di aplikasi Android/iOS atau JavaScript peramban — aplikasi user memanggil servermu, servermu yang memanggil API ini.
  • Daftar IP: hanya IP server terdaftar yang diterima. Dari IP lain, key yang benar pun dibalas 403 ip_not_allowed; pesannya memuat IP yang terlihat oleh server kami supaya mudah dilaporkan.
  • Batas laju: 120 permintaan per menit. Selebihnya 429 rate_limited + header Retry-After (detik). Percobaan berulang dengan key salah dari satu IP diblokir sementara.
  • Key bocor? Minta pengelola membuat key baru — key lama mati saat itu juga.

IP belum terdaftar 403

{
  "error": {
    "code": "ip_not_allowed",
    "message": "IP 203.0.113.9 belum terdaftar untuk client ini. Minta pengelola menambahkannya."
  }
}

Melewati batas laju 429

Retry-After: 37

{ "error": { "code": "rate_limited", "message": "…" } }

Error

Semua error berbentuk sama. Andalkan code di programmu; message bisa berubah.

HTTPcodeArti
400invalid_requestParameter/body salah atau kurang.
401unauthorizedHeader Authorization tidak ada, atau key tidak dikenali.
403client_disabled
ip_not_allowed
Akun dinonaktifkan · IP belum didaftarkan.
404not_found
merchant_not_found
product_not_found
Alamat/transaksi, toko, atau produk tidak ada.
422unsupported_urlLink bukan dari toko yang didukung.
422product_not_eligibleProduk itu tidak ikut program komisi tokonya — minta user memilih produk lain.
422url_requiredToko ini hanya mendukung link per produk; kirim url.
422callback_not_setURL callback belum didaftarkan.
429rate_limited
too_many_failed_attempts
Lihat header Retry-After.
503merchant_unavailable
temporarily_unavailable
maintenance
Sementara; coba lagi nanti.
500server_errorKesalahan di sisi kami.

Bentuk error 4xx / 5xx

{
  "error": {
    "code": "unsupported_url",
    "message": "Link ini bukan dari toko yang didukung. Lihat GET /merchants."
  }
}

GETPing

https://api.linkcash.id/v1/ping

Memastikan key dan IP server sudah benar. Tidak mengubah apa pun.

Example Request

curl https://api.linkcash.id/v1/ping \
  -H "Authorization: Bearer $LINKCASH_API_KEY"

Example Response 200 OK

{
  "ok": true,
  "client": { "code": "CL0001", "name": "PT Mitra Aplikasi", "commission_pct": 50 },
  "ip": "103.10.20.30",
  "time": "2026-09-20T09:00:00Z"
}

GETDaftar toko

https://api.linkcash.id/v1/merchants

Toko yang bisa dibuatkan link.

Field respons

slugPengenal toko — dipakai di POST /links.
rate_text
max_rate_pct
Estimasi tertinggi pendapatanmu dari nilai belanja, sudah disesuaikan dengan porsi komisi akunmu. Nilai pasti per pesanan ada di transaksi.
store_linktrue = bisa dibuatkan link ke beranda toko (kirim merchant).
product_linktrue = bisa dibuatkan link ke produk tertentu (kirim url).
logoURL gambar; kosong bila tidak ada.

Example Request

curl https://api.linkcash.id/v1/merchants \
  -H "Authorization: Bearer $LINKCASH_API_KEY"

Example Response 200 OK

{
  "data": [
    {
      "slug": "traveloka",
      "name": "Traveloka",
      "category": "Travel",
      "homepage": "https://www.traveloka.com",
      "logo": "https://…/traveloka.svg",
      "rate_text": "s/d 6%",
      "max_rate_pct": 6,
      "store_link": true,
      "product_link": false
    }
  ]
}

GETCari produk

https://api.linkcash.id/v1/products?q=sepatu&page=1&limit=20

Katalog produk yang bisa dicari. Buat link-nya dengan product_id. Katalog diperbarui tiap hari — jangan menyimpan product_id terlalu lama.

Params

qKata kunci (maks. 100 karakter). Kosong = produk pilihan.
page1–200, bawaan 1.
limit1–50, bawaan 20.

Field respons

price
original_price
Harga sekarang dan harga coret (Rp).
est_earning
est_rate_pct
Estimasi pendapatanmu untuk produk itu (Rp dan persen dari harga).
has_moretrue = masih ada halaman berikutnya.

Example Request

curl "https://api.linkcash.id/v1/products?q=sepatu&limit=20" \
  -H "Authorization: Bearer $LINKCASH_API_KEY"

Example Response 200 OK

{
  "data": [
    {
      "product_id": 555,
      "name": "Sepatu Lari",
      "image": "https://…/sepatu.jpg",
      "price": 200000,
      "original_price": 250000,
      "platform": "tokopedia",
      "category": "Olahraga",
      "shop_name": "",
      "est_rate_pct": 1.5,
      "est_earning": 3000
    }
  ],
  "page": 1,
  "has_more": false
}

GETDaftar transaksi

https://api.linkcash.id/v1/conversions?status=pending&limit=50

Transaksi akunmu, terbaru lebih dulu.

Params

statuspending, approved, rejected, atau paid.
user_idHanya transaksi milik satu user.
updated_sinceRFC 3339, mis. 2026-09-20T00:00:00Z — hanya yang berubah sejak waktu itu. Pakai untuk sinkronisasi berkala; perubahan status ikut terbawa.
limit1–200, bawaan 50.
cursorNilai next_cursor dari respons sebelumnya. Ulangi sampai next_cursor bernilai null.

Field respons

earningPendapatanmu (Rp). Bersama amount bisa terkoreksi selama status masih pending.
commission_pctPorsi komisi yang berlaku untuk transaksi itu — tidak berubah lagi walau porsi akunmu diubah kemudian.
order_idNomor pesanan di toko (bisa kosong).

Example Request

curl "https://api.linkcash.id/v1/conversions?updated_since=2026-09-20T00:00:00Z" \
  -H "Authorization: Bearer $LINKCASH_API_KEY"

Example Response 200 OK

{
  "data": [
    {
      "id": "trx_1024",
      "user_id": "u-1001",
      "merchant": "Traveloka",
      "order_id": "ORD-778812",
      "amount": 200000,
      "commission_pct": 50,
      "earning": 5000,
      "status": "pending",
      "created_at": "2026-09-20T09:00:00Z",
      "updated_at": "2026-09-20T09:00:00Z"
    }
  ],
  "next_cursor": "1023"
}

GETSatu transaksi

https://api.linkcash.id/v1/conversions/{id}

Mengambil satu transaksi berdasarkan id (mis. trx_1024). Transaksi milik akun lain dibalas 404 not_found.

Example Request

curl https://api.linkcash.id/v1/conversions/trx_1024 \
  -H "Authorization: Bearer $LINKCASH_API_KEY"

Example Response 200 OK

{ "id": "trx_1024", "user_id": "u-1001", "status": "approved", "earning": 5000, … }

GETSaldo

https://api.linkcash.id/v1/balance

Total pendapatan akunmu per status, dalam rupiah. commission_pct = porsi komisi akunmu saat ini (berlaku untuk transaksi berikutnya).

Example Request

curl https://api.linkcash.id/v1/balance \
  -H "Authorization: Bearer $LINKCASH_API_KEY"

Example Response 200 OK

{
  "currency": "IDR",
  "commission_pct": 50,
  "earning": {
    "pending": 12500,
    "approved": 40000,
    "paid": 150000,
    "rejected": 3000
  }
}

Callback

Kalau URL callback didaftarkan (wajib https://, alamat publik), kami mengirim POST JSON ke sana saat transaksimu tercatat (conversion.created) dan saat status/nilainya berubah (conversion.updated). Isi data sama persis dengan objek transaksi.

Header kiriman

X-LinkCash-Eventconversion.created, conversion.updated, atau ping.
X-LinkCash-TimestampWaktu kirim (detik Unix).
X-LinkCash-Signaturesha256= + HMAC-SHA256 heksadesimal.

Wajib: verifikasi tanda tangan

Tanpa ini siapa pun yang tahu URL-mu bisa mengirim transaksi palsu. Rumus: HMAC-SHA256(secret, timestamp + "." + body_mentah). Pakai body mentah (sebelum di-parse), bandingkan dengan fungsi aman-waktu, dan tolak kalau selisih timestamp lebih dari 5 menit.

Aturan penerima

  • Balas 2xx dalam 10 detik. Selain itu kami mencoba lagi beberapa kali dengan jeda; redirect tidak diikuti.
  • Event yang sama bisa datang lebih dari sekali dan urutannya tidak dijamin — jadikan data.id sebagai kunci dan proses secara idempoten (timpa dengan keadaan terbaru).
  • Callback adalah percepatan, bukan satu-satunya jalur: tetap jalankan tarikan berkala GET /conversions?updated_since=… sebagai jaring pengaman.

Kiriman dari kami

POST /linkcash/callback
Content-Type: application/json
X-LinkCash-Event: conversion.updated
X-LinkCash-Timestamp: 1790000000
X-LinkCash-Signature: sha256=5f2b…

{
  "event": "conversion.updated",
  "created_at": "2026-10-25T03:00:00Z",
  "data": { "id": "trx_1024", "status": "approved", … }
}

Verifikasi — PHP

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_LINKCASH_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_LINKCASH_SIGNATURE'] ?? '';
$mau  = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body,
          getenv('LINKCASH_CALLBACK_SECRET'));

if (!hash_equals($mau, $sig) || abs(time() - (int)$ts) > 300) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);   // aman diproses
http_response_code(204);

Verifikasi — Node.js (Express)

const crypto = require('crypto');

// body mentah wajib tersedia: express.raw()
app.post('/linkcash/callback',
  express.raw({ type: 'application/json' }), (req, res) => {
    const ts  = req.get('X-LinkCash-Timestamp') || '';
    const sig = req.get('X-LinkCash-Signature') || '';
    const mau = 'sha256=' + crypto
      .createHmac('sha256', process.env.LINKCASH_CALLBACK_SECRET)
      .update(ts + '.').update(req.body).digest('hex');

    const sah = sig.length === mau.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mau));
    if (!sah || Math.abs(Date.now() / 1000 - Number(ts)) > 300)
      return res.sendStatus(401);

    const event = JSON.parse(req.body);  // aman diproses
    res.sendStatus(204);
  });

POSTTes callback

https://api.linkcash.id/v1/callback/test

Mengirim event ping ke URL callback-mu saat itu juga dan melaporkan hasilnya — untuk menguji penerima dan verifikasi tanda tanganmu tanpa menunggu transaksi sungguhan. Tanpa body.

Example Request

curl -X POST https://api.linkcash.id/v1/callback/test \
  -H "Authorization: Bearer $LINKCASH_API_KEY"

Example Response 200 OK

{
  "delivered": true,
  "url": "https://api.mitra.com/linkcash/callback",
  "http_status": 204
}