Ödeme API v2

Hızlı başlangıç

1. Panelde Geliştiriciler bölümünden ağ geçidiniz için bir API anahtarı oluşturun. 2. Sipariş tutarıyla bir ödeme oluşturun. 3. Müşteriyi dönen checkout_url adresine yönlendirin. 4. Webhook geldiğinde (veya müşteri geri döndüğünde) ödemeyi tekrar okuyun ve durumu "paid" olunca siparişi gönderin.

 curl https://coino.live/api/v2/payments \
  -H "Authorization: Bearer ck_live_..." \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"amount": "25.00", "currency": "EUR", "order_id": "1001",
       "success_url": "https://shop.example/thanks",
       "notify_url": "https://shop.example/coino-webhook"}' 

Kimlik doğrulama

Gizli anahtarınızı her isteğin Authorization başlığında gönderin. Anahtarlar tek bir ağ geçidine aittir ve yalnızca o ağ geçidinin ödemelerini görür. Anahtarı sunucunuzda tutun: asla tarayıcıya, uygulamaya veya herkese açık bir depoya koymayın. Anahtar sızarsa panelden iptal edin ve yenisini oluşturun.

Authorization: Bearer ck_live_...
Temel URL: https://coino.live/api/v2

Tüm tutarlar ondalık metindir (sayı değil), tüm zamanlar UTC'de ISO 8601 biçimindedir ve her yanıt, sonucu "data" altında içeren JSON'dur.

Ödeme oluşturun

Fiyatlar USD veya GET /currencies listesindeki herhangi bir para biriminde olabilir; diğer para birimleri ödeme oluşturulurken güncel kurla USD'ye çevrilir. Müşteri coin ve ağı ödeme sayfasında seçer.

Yanıt (oluşturulduğunda 201, tekrarlanan anahtarda 200) aşağıdaki ödeme nesnesidir.

Ödeme nesnesi

{
  "data": {
    "id": "01m62ewd502p9774d6trd7rhr7",
    "status": "paid",
    "amount": "22.32",
    "currency": "USD",
    "requested_amount": "20.00",
    "requested_currency": "EUR",
    "exchange_rate_usd": "1.115926958947",
    "received_usd": "22.32",
    "remaining_usd": "0.00",
    "order_id": "943",
    "description": "Order #943",
    "customer_email": "[email protected]",
    "metadata": {"cart": "abc"},
    "checkout_url": "https://coino.live/pay/01m62ewd502p9774d6trd7rhr7",
    "success_url": "https://shop.example/thanks",
    "cancel_url": "https://shop.example/cart",
    "asset": null,
    "quote": {
      "asset": "usdc-ethereum", "symbol": "USDC", "network": "Ethereum",
      "address": "0x8e2e…61bc", "amount": "22.330545",
      "network_fee": "0.000001", "rate_usd": "0.9995", "expires_at": "…"
    },
    "deposits": [{
      "asset": "usdc-ethereum", "symbol": "USDC", "network": "Ethereum",
      "tx_hash": "0xf13d…1439", "explorer_url": "https://etherscan.io/tx/0xf13d…1439",
      "amount": "22.330545", "network_fee": "0.000001",
      "platform_fee": "0.223305", "net": "22.107239",
      "usd_value": "22.32", "credited_at": "…"
    }],
    "expires_at": "…", "paid_at": "…", "created_at": "…"
  }
}

amount ve currency müşterinin USD olarak ödediği tutardır; requested_amount ve requested_currency sizin istediğinizdir. quote, müşteriye şu anda gösterilen coin, adres ve tutardır; deposits alınan her işlemi, kesilen ücret ve bakiyenize eklenen tutarla (net) birlikte listeler.

Tutara çok yakın bir ödeme ödendi sayılır, böylece cüzdanların yuvarlaması siparişleri açık bırakmaz.

Ödemeleri okuma ve iptal etme

Ödemenin güncel durumuna ihtiyaç duyduğunuzda onu tekrar okuyun: webhook'tan sonra, müşteri döndüğünde veya zamanlanmış bir görevden. Bilinmeyen kimlikler ve diğer ağ geçitlerinin ödemeleri 404 döner.

Ödemelerinizi en yeniden başlayarak, sayfa başına 50 adet listeler. İki filtre de isteğe bağlıdır. meta.next_cursor ve meta.prev_cursor sonuçlar arasında gezinir.

Hiçbir şey almamış açık bir ödemeyi iptal eder, örneğin müşteri sepeti boşalttığında. Para yatırılmış ödemeler iptal edilemez (422).

Webhook'lar

Coino Live, bir ödemenin durumu her değiştiğinde notify_url adresine (veya ağ geçidi webhook adresine) bir POST gönderir. Webhook'lar yalnızca ağ geçidinizin bir imza anahtarı varsa gönderilir: onu ağ geçidi ayarlarında oluşturun.

 POST /coino-webhook
X-Coino-Event: payment.paid
X-Coino-Delivery: 01m62f23xhkz39ahqv4h64ttfk
X-Coino-Signature: t=1761696953,v1=5f2c…

{"id": "01m62f23xhkz39ahqv4h64ttfk", "event": "payment.paid",
 "created_at": "…", "data": { …the payment object… }} 

İmzayı doğrulayın: imza anahtarınızla "<t>.<raw body>" için HMAC-SHA256 hesaplayın, sabit sürede v1 ile karşılaştırın ve beş dakikadan eski zaman damgalarını reddedin.

// PHP
$header = $_SERVER['HTTP_X_COINO_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $header), $sig);
$ok = isset($sig['t'], $sig['v1'])
    && abs(time() - (int) $sig['t']) <= 300
    && hash_equals(hash_hmac('sha256', $sig['t'] . '.' . $body, $secret), $sig['v1']);

// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const ok = Math.abs(Date.now() / 1000 - t) <= 300
  && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

# Python
t, v1 = (p.split('=', 1)[1] for p in header.split(','))
expected = hmac.new(secret.encode(), f'{t}.{raw_body}'.encode(), 'sha256').hexdigest()
ok = abs(time.time() - int(t)) <= 300 and hmac.compare_digest(expected, v1)

Para birimleri, coinler ve bakiyeler

Bir ödemenin fiyatlandırılabileceği para birimleri, her biri USD değeriyle: {"code": "EUR", "usd_per_unit": "1.09"}. Mağaza para biriminiz listede yoksa kripto ödemeyi gizleyin.

Müşterilerin şu anda ödeme yapabileceği coinler: code (örneğin "usdt-tron"), symbol, name, network, decimals ve price_usd.

Ücretler düşüldükten sonra coin başına hesap bakiyeniz: asset, symbol, network, balance ve usd_value (fiyat yokken null).

Custody hesapları

Kullanıcı hesapları olan uygulamalar için: her kullanıcı kalıcı yatırma adresleri alır ve yatırımlar o kullanıcının ağ geçidinizdeki bakiyesine eklenir.

Para çekme

Bakiyenizden bir adrese ödeme yapar: asset, amount ve address zorunludur; custody_user bir saklama kullanıcısının bakiyesinden düşer; reference (ağ geçidi başına benzersiz) isteği güvenle tekrarlamanızı sağlar. Varsayılan olarak kapalıdır: API ile para çekmeyi ağ geçidi ayarlarından açın; orada günlük USD sınırını ve çağırmasına izin verilen sunucu IP adreslerini de belirlersiniz (her iki uç nokta yalnızca bu IP'lere yanıt verir). Farklı bir çekim için yeniden kullanılan reference 409 ile reddedilir. Büyük çekimler incelemeyi bekleyebilir.

Durum: pending_review, approved, processing, broadcast, completed, rejected (error'a bakın), cancelled veya failed. Gönderildiğinde tx_hash dolar.

Hatalar ve sınırlar

{"message": "The minimum payment is 1.00 USD."}

{"message": "amount must be a decimal string with at most 2 decimals, e.g. \"25.00\".",
 "errors": {"amount": ["amount must be a decimal string with at most 2 decimals, e.g. \"25.00\"."]}}

Kod kütüphaneleri

Bu API için resmi kütüphaneler, hiçbir bağımlılık olmadan. Webhook imzalarını doğrular, her ret için anlaşılır bir hata verir ve ağ hatalarını yalnızca isteği tekrarlamak güvenliyse yeniden dener.

// PHP
$coino = new \CoinoLive\Client('ck_live_...');
$payment = $coino->payments->create(['amount' => '25.00', 'currency' => 'EUR', 'order_id' => '1001']);

// Node.js
const coino = new CoinoLive('ck_live_...');
const payment = await coino.payments.create({ amount: '25.00', currency: 'EUR', order_id: '1001' });

# Python
coino = coinolive.Client("ck_live_...")
payment = coino.payments.create(amount="25.00", currency="EUR", order_id="1001") 

Her indirmede tüm çağrıları, webhook işlemeyi ve hata sınıflarını anlatan bir README bulunur.

Platform entegrasyonları

Bu API üzerine kurulu hazır eklentiler. Birini kurun, bir API anahtarı yapıştırın ve etkinleştirin: siparişler otomatik güncellenir ve her eklenti bakiyenizi ve ödemelerinizi kendi yönetim panelinde gösterir.

Diğer platformlar: API'yi yukarıda anlatıldığı gibi doğrudan kullanın.