API referansı

Tüm uç noktaları sunucunuzdan çağırın. İstekler ve yanıtlar JSON'dur. Webhook adresleri ve API anahtarları satıcı panelinde yönetilir.

Temel kurallar

Hatalar

Hatalar 4xx veya 5xx döndürür. Kararı code ile verin; message yalnızca hata ayıklama içindir.

{
  "error": {
    "code": "amount_below_minimum",
    "message": "options[0].amount is below the minimum",
    "details": { "min_amount": "5.00" }
  }
}

Ödemeler

Ödeme, kullanıcının ödeyeceği bir siparişi temsil eder. Kullanıcı ödeme sayfasında öder, sonucu webhook ile alırsınız.

Tutarın asgarinin altında kaldığı zincirler çıkarılır; hiç zincir kalmazsa istek başarısız olur. Varsayılan asgari 5 USD'dir; ücretleriniz panelde projenin Komisyonlar bölümündedir.

Zincir başına token ve tutar belirleme

Birden çok para birimi veya zincire göre farklı tutar için currency, amount ve chains yerine options gönderin. En fazla 16 öğe; token sembol veya sözleşme adresidir.

"options": [
  { "chain": "bsc", "token": "USDT", "amount": "25.00" },
  { "chain": "bsc", "token": "USDC", "amount": "25.00" }
]

Yanıt

201 ve ödeme nesnesini döndürür. checkout_url adresini kullanıcıya açın.

{
  "id": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "object": "payment_intent",
  "status": "pending",
  "livemode": true,
  "customer": "user_42",
  "checkout_url": "https://pay.kokiwa.com/p/pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "metadata": { "order_id": "10086" },
  "success_url": "https://your-shop.com/orders/10086",
  "cancel_url": null,
  "created_at": "2026-11-02T08:30:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "paid_at": null,
  "paid_option": null,
  "options": [
    {
      "id": "pio_5Hq2Tz8rLw0aVb3Kc9XyN1",
      "chain": "bsc",
      "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": "0x8b1F…c04E"
    },
    {
      "id": "pio_2Mn7Xc4bQe6uJs1Ga8RvK3",
      "chain": "base",
      "token": { "symbol": "USDT", "address": "0xfde4…9bb2", "decimals": 6 },
      "amount": "25.00",
      "received": "0.00",
      "deposit_address": null
    }
  ],
  "deposits": []
}

Ödeme nesnesini döndürür. Mutabakat için veya webhook gelmediğinde durumu kontrol etmek için kullanın.

Ödeme durumu

Yatırma adresleri

{
  "object": "deposit_address",
  "customer": "user_42",
  "chain": "bsc",
  "address": "0x3c9A…71d2",
  "tokens": [
    { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18, "min_settle_amount": "5.00" }
  ]
}

Aynı kullanıcı her zaman aynı adresi alır, uzun süre gösterebilirsiniz. Yalnızca tokens içindeki tokenlar yansıtılır.

Her transfer deposit.confirmed gönderir. min_settle_amount altındaki transferler de held durumuyla yansıtılır; adreste asgari tutar birikince hepsi birlikte alım adresinize toplanır ve tek sabit ücret alınır.

Yatırmalar

Yatırma (deposit), bir ödemeden veya yatırma adresinden gelen, yansıtılmış bir zincir içi ödemedir. Bir ödemenin birden çok yatırması olabilir.

{
  "id": "dep_9Kx2Pa6Wn3Ty8Lq5Rb1Ms4",
  "object": "deposit",
  "status": "settled",
  "method": "wallet",
  "chain": "bsc",
  "customer": "user_42",
  "payment_intent": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6",
  "token": { "symbol": "USDT", "address": "0x55d3…7955", "decimals": 18 },
  "amount": "25.00",
  "fee": "0.0875",
  "net": "24.9125",
  "usd_value": "25.00",
  "confirmed_at": "2026-11-02T08:41:07Z",
  "transaction": {
    "hash": "0x4e7a…91c3",
    "log_index": 212,
    "block_number": 44718235,
    "block_time": "2026-11-02T08:40:58Z",
    "from": "0x1f9C…a2B0",
    "to": "0x7d3E…09f1",
    "raw_amount": "25000000000000000000"
  },
  "settlement": {
    "tx_hash": "0x4e7a…91c3",
    "by": "payment",
    "settled_at": "2026-11-02T08:40:58Z"
  }
}

En yeniden eskiye.

curl "https://api.kokiwa.com/v1/deposits?tx_hash=0x4e7a…91c3" \
  -H "Authorization: Bearer $KOKIWA_KEY"

{ "object": "list", "data": [ { "id": "dep_9Kx2…", "object": "deposit", ... } ], "has_more": false }

Zincirler ve tokenlar

kokiwa aşağıdaki zincirleri ve para birimlerini destekler. chains ve options[].chain için chain sütununu, currency için para birimi sütununu kullanın.

Testnet yalnızca USDT destekler. Token tUSDT'dir, ancak currency yine USDT olur.

Bu, kullanılabilecek değerlerin tamamıdır; her projenin hepsini kabul edebileceği anlamına gelmez. Yapılandırma işletmeye göre değişir, bu yüzden kullanılabilir olanları aşağıdaki uç noktayla sorgulayın.

Anahtarın projesinin geçerli ağda neleri kabul edebildiğini döndürür.

{
  "object": "list",
  "livemode": true,
  "currencies": ["USDT"],
  "data": [
    {
      "object": "chain", "chain": "bsc", "name": "BNB Smart Chain", "chain_id": 56, "testnet": false, "native": "BNB",
      "payout_registered": true, "active": true,
      "methods": { "wallet": true, "deposit_address": true },
      "tokens": [
        { "symbol": "USDT", "asset": "USDT", "address": "0x55d398326f99059fF775485246999027B3197955", "decimals": 18, "accepted": true },
        { "symbol": "USDC", "asset": "USDC", "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "decimals": 18, "accepted": false }
      ]
    }
  ]
}

Müşteriler

İsteğe bağlı. Bir customer değeri ilk göründüğünde müşteri oluşturulur; bu uç noktalar yalnızca panelde etikete göre filtrelemek için gerekir.

Etiketleri, notları ve deposit_addresses (zincire göre yatırma adresleri) döndürür.