Geliştirici kılavuzuDeveloper guide

LiderHavale Partner API LiderHavale Partner API

Yatırım ve çekim işlemlerini kendi platformunuza bağlayın. Yalnızca HTTPS, JSON gövde; kimlik doğrulama gövdedeki apiKey + secKey ikilisiyle yapılır. Integrate deposit and withdraw operations into your own platform. HTTPS only, JSON body; authentication uses the apiKey + secKey pair in the request body.

Taban adres
Base URL: https://api.liderhavale.com
Taşıma
Transport: HTTPS zorunluHTTPS required
Yöntemler
Methods: GET · POST
Kimlik
Authentication: auth.apiKey + auth.secKey

◧

GirişIntroduction

Beş dakikada ilk yatırımı açın. Open your first deposit in five minutes.

⚡ Hızlı başlangıçQuickstart

Yatırım isteği açınCreate a deposit request
POST /api/payment/deposit/with-partner
Cevaptaki token değerini alın Take the token from the response
Müşteriyi ödeme sayfasına yönlendirin Redirect the customer to the payment page
https://payment.liderhavale.com/?token=${token}
Bildirimi bekleyinWait for the callback
İşlem onaylanınca sunucunuza POST atarız. We POST to your server once the transaction is confirmed.

🔒 GüvenlikSecurity

apiKey ve secKey değerlerini ortam değişkeninde tutun — kaynak koda yazmayın. Keep apiKey and secKey in environment variables — never hard-code them.
Gelen her bildirimin hash alanını SHA1 ile doğrulayın. Verify the hash field of every callback with SHA1.
Bildirim ucunuzu aynı işlemi iki kez işlemeyecek biçimde yazın (idempotent). Write your callback endpoint so the same transaction is never processed twice (idempotent).
İsteğe bağlı: bize IP listesi bildirin, yalnız o adreslerden gelen istekleri kabul ederiz. Optional: give us an IP allowlist and we will only accept requests from those addresses.

≡

Uç noktalarEndpoints overview

Toplam üç uç ve size attığımız bildirim. Three endpoints in total, plus the callback we send you.

İşlevFeature	YöntemMethod	YolPath	KimlikAuth
YatırımDeposit	POST	`/api/payment/deposit/with-partner`	apiKey + secKey
ÇekimWithdraw	POST	`/api/payment/withdraw/with-partner`	apiKey + secKey
Banka listesiBank list	GET	`/api/bank`	GerekmezNone
Bildirim (biz size)Callback (us → you)	POST	`SİZİN_ADRESİNİZYOUR_URL`	SHA1 hash

◆

Durum kodlarıStatus types

Yatırım ve çekimin alabileceği bütün değerler. Every value a deposit or withdraw can take.

DurumStatus	AnlamıMeaning	NotNote
PENDING	Müşteri ya da yönetici onayı bekleniyor Awaiting customer action or admin approval	Ara durumInterim
PROCESSING	İstek alındı, ödeme akışı sürüyor Request accepted, payment flow in progress	İlk durumInitial state
CONFIRMED	Tamamlandı, bildirim gönderildi Completed, callback sent	Yalnızca bu durum bildirim üretir Only this state fires a callback
REJECTED	Yönetici ya da müşteri reddetti Rejected by admin or customer	Kesin durumFinal
TIMEOUT_REJECTED	Süre aşımıyla otomatik reddedildi Auto-rejected after timeout	Kesin durumFinal
SUSPICIOUS	Bizde onaylı, ama bildirim 3 kez iletilemedi Confirmed on our side, but callback failed 3 times	Kurtarılabilir — akışa bakın Recoverable — see the flow
FAILED	İşlem sırasında hata Processing error	Kesin durumFinal
CANCELLED	Müşteri ya da sistem iptali Cancelled by customer or system	Kesin durumFinal

ÖnemliImportant Bildirim yalnızca CONFIRMED ve REJECTED durumları için gönderilir. SUSPICIOUS bir işlem, adresiniz yeniden erişilebilir olduğunda panelden elle kurtarılabilir. Callbacks are sent for CONFIRMED and REJECTED only. A SUSPICIOUS transaction can be recovered manually from the panel once your URL is reachable again.

YatırımDeposit

Müşteriniz adına yatırım isteği açar. Creates a deposit request on behalf of your customer.

POST https://api.liderhavale.com/api/payment/deposit/with-partner

İstek gövdesiRequest body

{
  "auth": {
    "apiKey": "API_ANAHTARINIZ",
    "secKey": "GIZLI_ANAHTARINIZ"
  },
  "customer": {
    "id":       "123123",       // sizdeki müşteri no
    "username": "testmusteri",
    "fullName": "Ahmet Yılmaz"   // banka hesabındaki ad
  },
  "transactionId": "456785",      // sizde tekil olmalı
  "returnUrl":     "https://siteniz.com/hesabim",
  "amount":        1000
}

Başarılı cevapSuccess response

HTTP 200

{
  "status": true,
  "deposit": {
    "customer": {
      "fullName": "Ahmet Yılmaz",
      "username": "testmusteri",
      "id": "123123"
    },
    "transactionId": "456785",
    "amount": 1000,
    "partner": "6453f2b3c4b1361de57edf90",
    "status": "PROCESSING",
    "_id": "64c76bfacfe287ddf963ce49",
    "created_at": "2026-01-01T08:08:26.340Z"
  },
  "token": "pZk3_9vQxT2Lm8Rd...",
  "paymentUrl": "https://payment.liderhavale.com/?token=pZk3_9vQxT2Lm8Rd..."
}

Müşteriyi yönlendirinRedirect the customer

Cevaptaki token ile ödeme sayfasına gönderin. Bağlantı 30 dakika geçerlidir. Send them to the payment page with the token from the response. The link is valid for 30 minutes.

https://payment.liderhavale.com/?token=${token}

Adresi kendiniz kurmak istemiyorsanız cevaptaki paymentUrl alanını olduğu gibi kullanabilirsiniz — aynı şey. If you would rather not build the URL yourself, use the paymentUrl field from the response as is — it is the same thing.

Kapalı yatırım hatalarıDeposit disabled errors Yatırım işlemleri şu anda kapalıdır ya da Bu site için yatırım işlemleri kapalıdır cevabı alıyorsanız, yatırım ya sistem geneline ya da yalnız sizin hesabınıza kapatılmıştır. Bu cevap HTTP 200 ile gelir — gövdedeki status alanına bakın. If you get Yatırım işlemleri şu anda kapalıdır or Bu site için yatırım işlemleri kapalıdır, deposits are off either globally or for your account only. This response arrives with HTTP 200 — check the status field in the body.

ÇekimWithdraw

Müşterinin banka hesabına ödeme talebi açar. Submits a payout to the customer's bank account.

POST https://api.liderhavale.com/api/payment/withdraw/with-partner

İstek gövdesiRequest body

{
  "auth": {
    "apiKey": "API_ANAHTARINIZ",
    "secKey": "GIZLI_ANAHTARINIZ"
  },
  "customer": {
    "id": "123456",
    "username": "testmusteri",
    "fullName": "Ahmet Yılmaz"
  },
  "transactionId": "123123",
  "iban":          "TR760009901234567800100001",
  "bank":          "65c6525532c59fcd5af4a4b3",  // /api/bank içindeki _id
  "amount":        1000
}

Başarılı cevapSuccess response

HTTP 200

{
  "status": true,
  "withdraw": {
    "customer": { "fullName": "Ahmet Yılmaz",
                   "username": "testmusteri",
                   "id": "123456" },
    "bank": "65c6525532c59fcd5af4a4b3",
    "iban": "TR760009901234567800100001",
    "transactionId": "123123",
    "amount": 1000,
    "partner": "6453f2b3c4b1361de57edf90",
    "status": "PROCESSING",
    "_id": "64c769013f547212cdb46415",
    "created_at": "2026-01-01T07:55:45.150Z"
  }
}

Yatırım ve çekim ayrı anahtarlardırDeposit and withdraw toggle separately Bu site için çekim işlemleri kapalıdır cevabı alsanız bile yatırım çalışıyor olabilir; tersi de geçerlidir. IBAN kontrol basamağı bizde doğrulanır — geçersiz IBAN iş kuralı hatası döner. Getting Bu site için çekim işlemleri kapalıdır does not mean deposits are off — and vice versa. We validate the IBAN checksum; an invalid IBAN comes back as a business-logic error.

Banka listesiBank list

Çekim isteğinde kullanacağınız banka kimliklerini verir. Returns the bank ids you use in withdraw requests.

GET https://api.liderhavale.com/api/bank

Kimlik gerekmezNo auth

{
  "status": true,
  "data": [
    {
      "_id": "6453f2c8c4b1361de57edfc2",
      "name": "GARANTİ BANKASI",
      "code": "0062",
      "enabled": true,
      "created_at": "2026-01-01T18:00:40.003Z",
      "updated_at": "2026-01-01T18:00:40.003Z"
    },
    {
      "_id": "64c852d8f7fa26fc12daabb2",
      "name": "HALKBANK",
      "code": "0012",
      "enabled": true,
      "created_at": "2026-01-02T00:33:28.724Z",
      "updated_at": "2026-01-02T00:33:28.724Z"
    }
  ]
}

İpucuTip Çekim isteğindeki bank alanına _id değerini yazın; banka adını değil. Liste değişebilir, günde bir kez tazelemeniz yeter. Put the _id value in the withdraw request's bank field, not the bank name. The list can change; refreshing once a day is enough.

BildirimCallbacks

İşlem sonuçlanınca sizin sunucunuza POST atarız. We POST to your server when a transaction is settled.

AdresDestination	`SİZİN_ADRESİNİZYOUR_URL` — bize bildirdiğiniz uç — the endpoint you gave us
YöntemMethod	POST `application/json`
Beklenen cevapExpected response	HTTP 200
Zaman aşımıTimeout	15 saniye15 seconds
DenemeAttempts	3 · sonra `SUSPICIOUS` 3 · then `SUSPICIOUS`
DoğrulamaVerification	Gövdedeki `hash` — SHA1 `hash` in the body — SHA1

İmza (SHA1)Signature (SHA1)

İmzalanan metnin sırası sözleşmenin parçasıdır — alanları başka sırayla dizerseniz hash tutmaz. The order of the signed text is part of the contract — a different field order produces a different hash.

// Node.js
const crypto = require("crypto");

const hashRequestSignature = (secret, text) =>
  crypto.createHash("sha1").update(`${secret}${text}`).digest("hex");

// Gelen bildirimi doğrulama
function bildirimGecerli(govde, secKey) {
  const metin = `transactionId=${govde.transactionId}&amount=${govde.amount}&status=${govde.status}`;
  return hashRequestSignature(secKey, metin) === govde.hash;
}

↓ Yatırım bildirimiDeposit callback

{
  "transactionId": "456785",
  "status": "CONFIRMED",
  "amount": 1000,
  "hash": "bb2299ae42…",
  "type": "deposit"
}

↑ Çekim bildirimiWithdraw callback

{
  "transactionId": "123123",
  "status": "REJECTED",
  "amount": 1000,
  "hash": "4f1ac07b93…",
  "type": "withdraw"
}

⚙

Bildirim akışı ve kurtarmaCallback flow & recovery

Deneme sayacı ve SUSPICIOUS durumu nasıl çalışır. How the retry counter and the SUSPICIOUS state work.

İşlem bizde onaylanırTransaction is confirmed on our side Yönetici elle onaylar ya da otomatik eşleşme tamamlanır. An admin approves it, or auto-matching completes.

Adresinize POST atılırWe POST to your URL Gövde: transactionId, status, amount, hash, type. Body: transactionId, status, amount, hash, type.

✓

HTTP 200 dönerse iş biterHTTP 200 ends it İşlem CONFIRMED kalır, tekrar denemeyiz. The transaction stays CONFIRMED; we do not retry.

200 dışı cevap ya da zaman aşımıNon-200 or timeout Deneme sayacı artar; 15 saniye içinde cevap gelmezse başarısız sayılır. The attempt counter increases; no answer within 15 seconds counts as failed.

Üçüncü başarısız denemede SUSPICIOUS Third failure moves it to SUSPICIOUS Otomatik denemeyi bırakırız; işlem panelde şüpheli kuyruğuna düşer. We stop retrying automatically; it lands in the suspicious queue.

Panelden elle tekrar gönderilirManual retry from the panel Denemeler arasında 60 saniye bekleme vardır. There is a 60-second cooldown between attempts.

✓

Başarılı olursa CONFIRMED'a döner On success it returns to CONFIRMED Kayda kim kurtardığı ve ne zaman düşülür. Who recovered it and when is written to the audit log.

Çift işleme riski yokNo duplicate risk Sizin tarafınızdan bakıldığında her işlem için tek başarılı bildirim alırsınız — ilk denemede ya da kurtarmada. Yine de bildirim ucunuzu transactionId'ye bakıp iki kez işlemeyecek biçimde yazın. From your side you receive exactly one successful callback per transaction — either on the first attempt or on recovery. Even so, write your handler to check transactionId and never process it twice.

HatalarErrors

İki ayrı hata sınıfı var — karıştırmak en sık yapılan entegrasyon hatası. There are two distinct error classes — confusing them is the most common integration mistake.

Yalnızca HTTP koduna bakmayınDo not look at the HTTP code alone İş kuralı hataları HTTP 200 ile ve gövdede "status": false olarak döner. Sadece response.ok kontrolü yapan entegrasyonlar bunları başarılı sanıp müşteriye bakiye yükler. Her zaman gövdedeki status alanını okuyun. Business-logic errors come back with HTTP 200 and "status": false in the body. Integrations that only check response.ok read these as success and credit the customer. Always read the status field in the body.

HTTP seviyesi hatalarHTTP-level errors

KodCode	AnlamıMeaning	Örnek cevapExample response
401	Parametre eksikMissing parameters	`{"status":false,"message":"Missing parameters apikey or secKey","code":401}`
402	Yetkisiz erişim — anahtar hatalı Unauthorized — wrong key	`{"status":false,"message":"Unauthorized Access.","code":402}`
403	Hesap kapalı ya da IP listede değil Account disabled or IP not allowlisted	`{"status":false,"message":"Unauthorized Access.","code":403}`

İş kuralı hatalarıBusiness-logic errors

HTTP 200 · status:false

MesajMessage	SebepReason
`Sistem geçici bir süreliğine bakım durumundadır`	Sistem geneli kapalı. Bekleyip tekrar deneyin. System-wide switch is off. Wait and retry.
`Yatırım işlemleri şu anda kapalıdır`	Yatırım sistem geneline kapatılmış. Deposits disabled globally.
`Bu site için yatırım işlemleri kapalıdır`	Yatırım yalnız sizin hesabınızda kapalı. Deposits disabled for your account only.
`Çekim işlemleri şu anda kapalıdır`	Çekim sistem geneline kapatılmış. Withdraws disabled globally.
`Bu site için çekim işlemleri kapalıdır`	Çekim yalnız sizin hesabınızda kapalı. Withdraws disabled for your account only.
`Minimum yatırım tutarı X TL'dir`	Tutar alt sınırın altında. Amount below the minimum.
`Maksimum yatırım tutarı X TL'dir`	Tutar üst sınırın üstünde. Amount above the maximum.
`Aynı transactionId ile bir işlem zaten mevcut`	`transactionId` sizde tekil olmalı. `transactionId` must be unique on your side.
`Geçersiz IBAN`	TR + 24 rakam ve kontrol basamağı doğrulanır. TR + 24 digits; the checksum is validated.
`Müşteri bilgileri eksik (id, username, fullName)`	Üç alanın üçü de zorunlu. All three fields are required.

Doğru kontrolThe correct check

const cevap = await fetch(url, { method: "POST", headers, body });
const govde = await cevap.json();

// YANLIŞ: iş kuralı hatası da 200 döner
// if (cevap.ok) { bakiyeYukle(); }

// DOĞRU
if (!cevap.ok)      throw new Error(`HTTP ${cevap.status}: ${govde.message}`);
if (!govde.status)  throw new Error(govde.message);  // iş kuralı

// buraya geldiyseniz işlem gerçekten açıldı
musteriyiYonlendir(govde.token);

◷

NotlarNotes

transactionId sizde tekil olmalı; aynı numarayla ikinci istek reddedilir. Bizde (partner, transactionId) ikilisi üzerinde benzersiz indeks var — eşzamanlı iki istek bile geçemez. transactionId must be unique on your side; a second request with the same number is rejected. We keep a unique index on (partner, transactionId), so even two concurrent requests cannot pass.
returnUrl müşterinin ödemeden sonra döneceği adrestir. Boş bırakırsanız ödeme sayfasında "geri dön" düğmesi çıkmaz. returnUrl is where the customer goes after paying. Leave it empty and the payment page shows no "back" button.
Komisyon yatırım ve çekim için ayrı ayrı, hesap bazında tanımlanır. Değişiklik için hesap yöneticinizle görüşün. Commission is set per account, separately for deposits and withdraws. Contact your account manager to change it.
Limitler sistem geneli varsayılanlardan gelir; hesabınız için ezilebilir. Boş bırakılan limit sistem değerine düşer. Limits come from system-wide defaults and can be overridden per account. An unset limit falls back to the system value.
Ödeme bağlantısı 30 dakika geçerlidir. Süresi dolan bağlantı için yeni bir yatırım isteği açın. The payment link is valid for 30 minutes. Open a new deposit request for an expired link.
Destek için işlem numarasını iletin; panelde o işlemin bize gelen isteği, verdiğimiz cevap ve bildirim denemeleri birlikte görünüyor. For support, quote the transaction id; the panel shows that transaction's incoming request, our response and every callback attempt together.