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
- Minta akses ke pengelola LinkCash.id (support@linkcash.id) dengan menyertakan alamat website/aplikasimu, IP publik server, dan URL callback (boleh menyusul).
- Kamu menerima API key (hanya diberikan sekali — simpan di variabel lingkungan server) dan secret callback.
- 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
- Tampilkan toko (
GET /merchants) dan/atau produk (GET /products) di aplikasimu. - Saat user memilih, servermu memanggil
POST /linksdenganuser_idmilikmu → dapat linkhttps://linkcash.id/go/…. - Arahkan user ke link itu tepat sebelum belanja. User belanja dan membayar seperti biasa di tokonya.
- Transaksi tercatat (umumnya 1–2 hari) berstatus
pending→ kamu menerima callback, atau menariknya lewatGET /conversions. - Setelah toko memvalidasi pesanan (umumnya 30–60 hari) status menjadi
approved, lalupaidsetelah dibayarkan ke mitra. Pesanan batal/retur menjadirejected.
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+ headerRetry-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.
| HTTP | code | Arti |
|---|---|---|
| 400 | invalid_request | Parameter/body salah atau kurang. |
| 401 | unauthorized | Header Authorization tidak ada, atau key tidak dikenali. |
| 403 | client_disabledip_not_allowed | Akun dinonaktifkan · IP belum didaftarkan. |
| 404 | not_foundmerchant_not_foundproduct_not_found | Alamat/transaksi, toko, atau produk tidak ada. |
| 422 | unsupported_url | Link bukan dari toko yang didukung. |
| 422 | product_not_eligible | Produk itu tidak ikut program komisi tokonya — minta user memilih produk lain. |
| 422 | url_required | Toko ini hanya mendukung link per produk; kirim url. |
| 422 | callback_not_set | URL callback belum didaftarkan. |
| 429 | rate_limitedtoo_many_failed_attempts | Lihat header Retry-After. |
| 503 | merchant_unavailabletemporarily_unavailablemaintenance | Sementara; coba lagi nanti. |
| 500 | server_error | Kesalahan di sisi kami. |
Bentuk error 4xx / 5xx
{
"error": {
"code": "unsupported_url",
"message": "Link ini bukan dari toko yang didukung. Lihat GET /merchants."
}
}GETPing
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
Toko yang bisa dibuatkan link.
Field respons
| slug | Pengenal 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_link | true = bisa dibuatkan link ke beranda toko (kirim merchant). |
| product_link | true = bisa dibuatkan link ke produk tertentu (kirim url). |
| logo | URL 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
Katalog produk yang bisa dicari. Buat link-nya dengan product_id. Katalog diperbarui tiap hari — jangan menyimpan product_id terlalu lama.
Params
| q | Kata kunci (maks. 100 karakter). Kosong = produk pilihan. |
| page | 1–200, bawaan 1. |
| limit | 1–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_more | true = 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
}POSTBuat link
Membuat link cashback untuk satu user. Arahkan user ke url pada respons tepat sebelum ia belanja.
Body (JSON)
| user_idwajib | ID user di sistemmu, 1–64 karakter A-Z a-z 0-9 . _ : @ -. Pakai ID internal, jangan data pribadi. Nilai inilah yang kembali di transaksi. |
| …ditambah tepat satu dari: | |
| merchant | User membuka toko — slug dari GET /merchants yang store_link-nya true. |
| url | User menempel link produk yang disalin dari aplikasi toko. Boleh berupa teks "Bagikan" utuh — link-nya dicari otomatis. |
| product_id | User memilih produk dari GET /products. |
Catatan
scope: "store"berarti link menuju beranda toko. Untuk sebagian toko, link produk yang dikirim lewaturltetap menghasilkan link toko — user lalu mencari produknya di sana; transaksinya tetap tercatat.- Permintaan yang sama untuk user yang sama mengembalikan link yang sama (
200, bukan201) — aman diulang. - Link bersifat per user: jangan dibagikan antar-user, karena transaksinya tercatat ke user pemilik link.
Example Request
curl -X POST https://api.linkcash.id/v1/links \
-H "Authorization: Bearer $LINKCASH_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id":"u-1001","merchant":"traveloka"}'Body lain yang sah
{"user_id":"u-1001","url":"https://shopee.co.id/produk-i.123.456"}
{"user_id":"u-1001","product_id":555}Example Response 201 Created
{
"code": "k3m9x2p7qa",
"url": "https://linkcash.id/go/k3m9x2p7qa",
"merchant": "traveloka",
"scope": "store",
"user_id": "u-1001",
"clicks": 0,
"created_at": "2026-09-20T09:00:00Z"
}GETDaftar transaksi
Transaksi akunmu, terbaru lebih dulu.
Params
| status | pending, approved, rejected, atau paid. |
| user_id | Hanya transaksi milik satu user. |
| updated_since | RFC 3339, mis. 2026-09-20T00:00:00Z — hanya yang berubah sejak waktu itu. Pakai untuk sinkronisasi berkala; perubahan status ikut terbawa. |
| limit | 1–200, bawaan 50. |
| cursor | Nilai next_cursor dari respons sebelumnya. Ulangi sampai next_cursor bernilai null. |
Field respons
| earning | Pendapatanmu (Rp). Bersama amount bisa terkoreksi selama status masih pending. |
| commission_pct | Porsi komisi yang berlaku untuk transaksi itu — tidak berubah lagi walau porsi akunmu diubah kemudian. |
| order_id | Nomor 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
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
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-Event | conversion.created, conversion.updated, atau ping. |
| X-LinkCash-Timestamp | Waktu kirim (detik Unix). |
| X-LinkCash-Signature | sha256= + 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.idsebagai 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
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
}