Entegrasyon rehberi

Sunucunuz API ile bir ödeme oluşturur, para geldiğinde kokiwa size webhook gönderir. Fonlar zincir üzerinde doğrudan cüzdanınıza gider; kokiwa fonları tutmaz.

Önce tüm akışı test ağında ücretsiz test tokenlarıyla deneyin, bkz. Test. Kullanıcılarınızın ne gördüğü için Ödemeyi deneyin sayfasına bakın.

Hazırlık

Bunların hepsi satıcı panelinde yapılır.

KaydolunE-postanızı doğrulayın, bir kimlik doğrulayıcı uygulama ekleyin ve kurtarma kodlarını saklayın.
Proje oluşturunBir proje, ürünlerinizden veya sitelerinizden birini temsil eder; kendi alım adresleri, API anahtarları ve webhook'ları vardır.
Tahsilatı ayarlayınProjenin Tahsilat ayarları sayfasında zincirleri, tahsilat yöntemlerini ve tokenları seçin, ardından her zincirde cüzdanınızla bir alım adresi kaydedin. Alım adresi zincire yazılır ve yalnızca kaydeden cüzdan değiştirebilir. Kayıt biraz gas gerektirir; tek cüzdan tüm EVM zincirlerini kaydedebilir.
API anahtarı oluşturunAnahtar yalnızca bir kez gösterilir. Sunucu ortam değişkeninde saklayın, ön yüze veya uygulamaya koymayın.
Webhook ayarlayınWebhook'lar sayfasında https adresinizi girin, imza gizli anahtarını saklayın ve Test olayı gönder ile ulaştığını doğrulayın.

Tahsilat şeklini seçin

	Ödeme	Yatırma adresi
Uygun olduğu durum	Siparişler: sabit tutar, tek seferde ödenir	Hesap yüklemeleri: tutarı kullanıcı belirler, istediği kadar
Adres	Ödeme başına bir tane, süresi dolunca devre dışı	Kullanıcı başına bir tane, kalıcı
Kullanıcı nasıl öder	Ödeme sayfasında cüzdanla; BNB Chain'de özel adrese transfer de yapabilir	Cüzdandan veya borsadan transfer
Zincirler	8 zincirin tümü	BNB Chain
gas	Cüzdanla ödemede kullanıcı öder; transferlerin toplanmasını kokiwa öder	Transferi kullanıcı öder; toplamayı kokiwa öder

İkisini birlikte kullanabilirsiniz.

Ödeme

Kullanıcı sipariş verdiğinde bir ödeme oluşturun ve dönen checkout_url adresini ona açın. Aşağıdaki istek, projenin USDT kabul ettiği tüm zincirleri sunar; kullanıcı birini seçer.

curl https://api.kokiwa.com/v1/payment_intents \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10086" \
  -d '{
    "currency": "USDT",
    "amount": "25.00",
    "customer": "user_42",
    "metadata": { "order_id": "10086" },
    "success_url": "https://your-shop.com/orders/10086"
  }'

Yatırma adresi

customer alanına sisteminizdeki kullanıcı kimliğini yazın. Aynı kullanıcı için tekrarlanan çağrılar aynı adresi döndürür.

curl https://api.kokiwa.com/v1/deposit_addresses \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "user_42" }'

Ödemeyi doğrulayın

Ödeme zincirde onaylanınca kokiwa webhook gönderir. Bakiyeyi yalnızca webhook'a göre yansıtın; kullanıcının success_url adresine dönmesine güvenmeyin.

Ödeme: payment_intent.paid geldiğinde siparişi ödendi olarak işaretleyin.
Yatırma adresi: deposit.confirmed geldiğinde data.deposit.customer bakiyesini artırın.

Her olayın imzasını doğrulayın ve olay id değerine göre tekrarları eleyin, bkz. Webhook'lar.

Tutarlar

Tüm tutarlar token biriminde dizelerdir, örneğin "25.00" veya "24.9125"; istekler, yanıtlar ve webhook'larda aynıdır, zincire göre dönüştürme gerekmez. Tutarlar zincirdeki tam hassasiyeti korur, bu yüzden ondalık sayısı değişebilir. Kayan noktayla hesap yapmayın.

İadeler

Fonlar zaten cüzdanınızdadır, bu yüzden kokiwa'da iade uç noktası yoktur ve ödeme geri alınamaz. İade için alım adresinizden kullanıcıya gönderin. transaction.from yerine kullanıcıdan iade adresi isteyin; borsadan çekim yaptıysa bu adres borsanındır. Ücretler iade edilmez.

Yayın öncesi kontrol

API anahtarları yalnızca sunucuda, kod depolarında ve günlüklerde yok.
Webhook imzaları doğrulanıyor ve tekrarlanan olay iki kez yansıtılmıyor.
Ödemeler Idempotency-Key ile oluşturuluyor, ağ yeniden denemesi iki ödeme yaratmıyor.
payment_intent.paid_late işleniyor, süre dolduktan sonra gelen ödeme kaybolmuyor.
Alım adresleri ana ağda kayıtlı ve sk_live_ ile başlayan anahtara geçildi.
Alım adresinin kurtarma ifadesi yedeklendi.

Sonraki: Test