API Dokümantasyonu & Geliştirici Rehberi

Hızlı Başlangıç

Coinzen ile sitenizde kripto ödeme almaya başlamak yalnızca 3 adımdır: API anahtarı oluşturun, tahsilat cüzdan adreslerinizi tanımlayın ve ilk ödeme faturanızı açın. Aracısız mimarimiz sayesinde tahsilatlar doğrudan sizin kontrolünüzdeki cüzdana aktarılır.

• POST /v1/merchants/{merchant_id}/api-keys — Güvenli istekler için API anahtar çiftinizi üretir.
• POST /v1/addresses — USDT gibi token tahsilatları için statik cüzdan adresinizi tanımlar (her ağ ve varlık için bir adet).
• POST /v1/sweep-addresses — TRX, BNB, GRAM gibi native coin tahsilatlarının toplanacağı ana cüzdanınızı (süpürme adresi) tanımlar.
• POST /v1/webhooks — Ödeme tamamlandığında sisteminize anında bildirim gönderecek URL uç noktanızı kaydeder.

İstek İmzalama (HMAC Güvenliği)

API güvenliğiniz için tüm HTTP istekleri HMAC-SHA256 standardı ile imzalanır. İmza, isteğin ham gövdesi (raw bytes) üzerinden hesaplanır; böylece JSON formatındaki anahtar sıralaması değişse dahi imza geçerliliğini korur.

METHOD \n PATH \n TIMESTAMP \n NONCE \n SHA256(raw_body)

X-Api-Key

API Anahtar Kimliği (pk_…)

X-Timestamp

Unix zaman damgası (saniye bazında sunucu saati toleranslı)

X-Nonce

Benzersiz rastgele dize (en fazla 128 karakter, tek kullanımlık)

X-Signature

hex(hmac_sha256(secret, canonical)) imza değeri

İstek güvenliği iki katmanda korunur: Zaman damgası belirlenen tolerans aralığında olmalı ve nonce değeri yalnızca bir kez kullanılmalıdır. Aynı isteğin mükerrer olarak tekrar gönderilmesi otomatik olarak engellenir (HTTP 401).

1import hashlib, hmac, os, time, json, urllib.request
2 
3KEY_ID  = os.environ["COINZEN_KEY_ID"]
4SECRET  = os.environ["COINZEN_SECRET"]
5BASE    = "https://pay.example.com"
6 
7def request(method: str, path: str, payload: dict | None = None) -> bytes:
8    body = json.dumps(payload).encode() if payload is not None else b""
9    ts = str(int(time.time()))
10    nonce = os.urandom(16).hex()
11    canonical = "\n".join(
12        [method.upper(), path, ts, nonce, hashlib.sha256(body).hexdigest()]
13    )
14    signature = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
15 
16    req = urllib.request.Request(
17        BASE + path,
18        data=body or None,
19        method=method.upper(),
20        headers={
21            "X-Api-Key": KEY_ID,
22            "X-Timestamp": ts,
23            "X-Nonce": nonce,
24            "X-Signature": signature,
25            "Content-Type": "application/json",
26        },
27    )
28    with urllib.request.urlopen(req) as resp:
29        return resp.read()

Fatura Yaşam Döngüsü

Bir ödeme faturası oluşturulduğunda akıllı durum makinesi devreye girer. Ağ ve varlık belirtilmemişse fatura selecting (Seçim Bekleniyor) durumunda başlar. Müşteri ödeme sayfasında dilediği ağı ve kripto parayı seçtiğinde fatura pending (Ödeme Bekleniyor) aşamasına geçer ve ödeme adresi tahsis edilir.

• selecting → pending, expired, cancelled
• pending → confirming, partially_paid, expired, cancelled
• confirming → paid, overpaid, failed
• paid ⇄ overpaid — Ödenmiş faturaya müşteri ek bir transfer daha gönderirse tutar otomatik olarak güncellenir.

paid, overpaid, expired, cancelled ve failed durumları nihai durumlardır. Olası blokzincir reorg (düzeltme) veya gecikmeli ödeme senaryolarında sistem durumu otomatik günceller ve webhook ile sisteminize bilgi iletir.

Webhook Bildirimleri

Ödeme durumundaki tüm değişiklikler kayıtlı webhook uç noktanıza anlık olarak iletilir. Gönderilen her paket HMAC-SHA256 ile imzalanır; böylece gelen verinin orijinalliğini ve Coinzen tarafından gönderildiğini güvenle doğrulayabilirsiniz.

X-Coinzen-Signature

t=<unix>,v1=<hex hmac_sha256(secret, "<t>.<raw_body>")>

X-Coinzen-Delivery

Benzersiz bildirim teslimat kimliği (UUID)

X-Coinzen-Event

Tetiklenen olay adı (örn: invoice.paid)

1import hashlib, hmac, time
2 
3def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
4    """X-Coinzen-Signature: t=<unix>,v1=<hex>"""
5    parts = dict(p.split("=", 1) for p in header.split(","))
6    t, v1 = parts["t"], parts["v1"]
7    if abs(time.time() - int(t)) > tolerance:
8        return False
9    expected = hmac.new(
10        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
11    ).hexdigest()
12    return hmac.compare_digest(expected, v1)

Desteklenen Webhook Olayları

• invoice.pending
• invoice.confirming
• invoice.partially_paid
• invoice.paid
• invoice.overpaid
• invoice.expired
• invoice.cancelled
• payment.reverted
• deposit.unmatched
• credit.low
• credit.exhausted

Akıllı Yeniden Deneme Mekanizması

İlk deneme ödeme gerçekleştikten hemen sonra anlık olarak yapılır. Sunucunuzdan 200 OK yanıtı alınamazsa bildirimler 30 · 120 · 600 · 3600 · 21600 · 86400 saniye aralıklarla 7 kademede otomatik tekrar denenir. Tüm denemeler sonuçsuz kalırsa kayıt dead_letter durumuna alınır ve yönetim panelinden tek tıkla tekrar kuyruğa gönderilebilir.

Komisyon ve Kontör Sistemi

Coinzen'de komisyon asla müşteri ödemesinin içinden kesilmez. USDT ve diğer kripto ödemeleri doğrudan sizin adresinize geçer ve o cüzdanın anahtarları yalnızca sizdedir. Platform hizmet bedeli önceden yüklediğiniz kontör bakiyenizden düşer; böylece tahsilatınız her zaman tam, net ve eksiksiz kalır.

• Standart komisyon oranımız %1'dir. Yeni açılan hesaplara özel ilk 45 gün boyunca avantajlı oran olan %0,1 uygulanır. Mağazanıza tanımlı güncel komisyon oranını GET /v1/credit yanıtındaki fee_bps alanından görebilirsiniz (on binde: 10 = %0,1; 100 = %1).
• Komisyon yalnızca başarıyla tamamlanan (paid ve overpaid) faturalardan tahsil edilir.
• İptal edilen, süresi dolan veya eksik kalan faturalardan hiçbir komisyon alınmaz.
• Kontör bakiyeniz bittiğinde açık faturaların tahsilat süreci etkilenmez, güvenle işlenir; yalnızca yeni fatura açma istekleri bakiye uyarısı (HTTP 402) alır.

İki Adımlı İşlem Modeli

Fatura ödendiğinde komisyon kaydı blokzincir takip hızını yavaşlatmamak için anında pending olarak açılır ve hiçbir dış servise bağımlı olmadan hızlıca işlenir. Döviz kuru hesaplaması arka planda yapılarak net tutar bakiyenizden düşülür.

Olası bir blokzincir reorg durumunda ödeme geri çekilirse komisyon kesintisi de anında iptal edilir; düşülmüşse reversal kaydıyla bakiyenize iade edilir.

Hızlı Kontör Yükleme

POST /v1/credit/deposit-addresses çağrısı ile size özel kalıcı bir USDT yükleme cüzdan adresi alırsınız. Bu adrese gönderdiğiniz bakiye blokzincirde onaylandığı anda kontörünüze otomatik olarak eklenir — manuel onay veya bekleme yoktur.

Otomatik Kontör Tamamlama

Bu özellik aktif edildiğinde, kontör bakiyeniz sıfırlansa dahi mağazanızın satışları durmaz. Bir sonraki küçük faturanızın tahsilatı doğrudan kontör bakiyenize aktarılır. Hizmetiniz kesintisiz sürer.

• Kontöre yönlendirilen bu faturadan ayrıca komisyon alınmaz.
• Güvenliğiniz için üst sınır uygulanır (varsayılan 25 USD). Üst sınırı aşan faturalar yönlendirilmez, büyük siparişleriniz riske edilmez.
• PUT /v1/credit/auto API uç noktası veya panel üzerinden dilediğiniz an açıp kapatabilir, kendi üst sınırınızı belirleyebilirsiniz.

Bakiye Uyarıları

Kontör bakiyeniz kritik eşiğin altına indiğinde credit.low, tükendiğinde ise credit.exhausted webhook olayı tetiklenir; böylece önceden haberdar olursunuz.

Desteklenen Blokzincir Ağları ve Varlıklar

Aşağıdaki tablo canlı mainnet ağ kayıt defterinin özetidir. Çalışma zamanındaki anlık liste için GET /v1/networks uç noktasını kullanabilirsiniz.

API Uç Noktaları