Bakiye Yükleme

Cüzdana para üç yoldan girer: kartla, temsilci eliyle nakit ve havale/EFT ile. Üçü de aynı operasyon modelini kullanır — her yükleme bir operasyon kaydı üretir ve sonuç webhook ile bildirilir. Kartla ve temsilci eliyle yükleme başlatılırken Idempotency-Key zorunludur.

Kartla yükleme

Kart yüklemesi ödeme altyapısına delege edilir; kart verisi sizin sunucunuza hiç uğramaz. Yönlendirme, 3D Secure ve sağlayıcı seçimi ödeme tarafında yapılır, sonuç cüzdana yansır.

Yüklemeyi başlatın

POST /api/v1/wallet/topups/card

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/topups/card" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: topup-crm-88213-1" \
  -H "X-Key-Id: …" -H "X-Signature: …" \
  -d '{
    "creditWalletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
    "amount": "25000",
    "currency": "TRY",
    "returnUrl": "https://app.acme.com/wallet/topup/result"
  }'

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "operationId": "4f1b8d2e-6a9c-4b3e-8f7d-1c5e9a2b6d08",
    "paymentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "status": "INITIALIZED",
    "checkoutFormContent": "<script …>",
    "threeDsHtml": "",
    "redirectUrl": ""
  }
}

Yanıtta üç olası devam yolu vardır; hangisi doluysa onu kullanın:

Sonucu öğrenin

GET /api/v1/wallet/topups/{operationId}

Durum akışı:

İlgili webhook'lar

Yükleme iadesi

Tamamlanmış bir kart yüklemesi iade edilebilir — para karta geri gider ve cüzdan bakiyesinden düşer.

POST /api/v1/wallet/topups/{operationId}/refund

İade şu sırayla yürür:

1. Yükleme REVERSING durumuna alınır. Aynı yükleme için eşzamanlı ikinci bir iade ya da geri alma bu adımı kazanamaz ve hiçbir para hareketi yapmaz.
2. Tutar cüzdan bakiyesinden düşülür.
3. Tutar karta iade edilir.
4. Yükleme REVERSED olur ve wallet.topup.refunded webhook'u düşer.

Adım 2 ya da 3'ün sonucu o an kesinleşmezse (zaman aşımı, sağlayıcıya erişilemiyor) yükleme REVERSING durumunda kalır. Sistem iadeyi aynı anahtarlarla otomatik olarak tamamlar; tutar ne cüzdandan ne karttan ikinci kez hareket eder. Bu durumda iadeyi yeniden başlatmanız gerekmez; aynı isteği tekrarlarsanız kaldığı yerden devam eder.

Temsilci ile yükleme

Bayi/temsilci ağınız varsa, temsilci nakdi alır ve kendi float hesabından müşterinin cüzdanına kredi geçer. Para tenant içinde yer değiştirir; dışarıdan giriş yoktur.

POST /api/v1/wallet/agent-topups

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/agent-topups" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-4471-20260807-0012" \
  -H "X-Key-Id: …" -H "X-Signature: …" \
  -d '{
    "agentId": "6b2e9f4a-3c8d-4e1b-9a7f-5d0c3e8b2a61",
    "creditWalletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
    "amount": "50000",
    "currency": "TRY"
  }'

Yanıttaki status normalde COMPLETED olur. Defter kaydının sonucu o an kesinleşmezse INDETERMINATE döner: kredi yapılmış olabilir, sistem işlemi kendiliğinden sonuçlandırır. Bu durumda temsilciye "yükleme olmadı" demeyin ve yeni bir Idempotency-Key ile tekrar denemeyin; aynı anahtarla tekrarlarsanız işlemin güncel durumu döner. Bkz. Belirsiz sonuç.

Temsilci tanımlama ve float yönetimi merchant panelden yapılır: Panel — Programlar.

Havale/EFT ile yükleme

Havale yükleme, kullanıcıya kendisine özel bir yatırma referansı verilmesi esasına dayanır. Kullanıcı bu referansla para gönderir; gelen para referansa göre eşleştirilip cüzdana kredilenir.

Yatırma talimatı oluşturun

POST /api/v1/wallet/end-users/{endUserId}/deposit-instructions

Talimatları listeleyin

GET /api/v1/wallet/end-users/{endUserId}/deposit-instructions

Kullanıcıya gösterdiğiniz IBAN ve referansı her seferinde bu uçtan okuyun; sabit kodlamayın.

Eşleşme tamamlandığında wallet.topup.completed webhook'u fundingSourceType alanıyla havale kaynağını belirterek düşer.

Yaygın hatalar