Cryptomus uyumlu API

blockwallets ile USDT ve USDC, ayrıca BTC, LTC, DOGE, BCH ve ağların kendi coin'lerini kabul edersiniz (sabitlenen kurla ABD doları olarak yatırılır): müşteri öder, biz zincir üzerinde onaylarız, ardından size haber veririz. API, imzalar ve webhook'lar Cryptomus ile aynıdır — Cryptomus'u entegre ettiyseniz alan adını değiştirmeniz yeterli. Önce nasıl çalıştığı, sonra API.

Ödeme almanın iki yolu

İkisi de her tutarı kabul eder: sabit fiyatlı siparişler ve müşterinin tutarı kendisinin yazdığı bakiye yüklemeleri. Ödeme gelince ürünü gönderirsiniz ya da müşterinin bakiyesine yüklersiniz. Tek fark, her ödemenin yeni bir adres alıp almadığıdır.

Emin değilseniz faturaları kullanın. Kod yazmadan, panelin ödeme bağlantıları sizin yerinize oluşturulan faturalardır. Henüz satıcı değil misiniz? Ana sayfadan erişim isteyin; onaylanınca satıcı paneline giriş yapın ve önce panel ana sayfasındaki “Bir ödeme dene” ile küçük bir tutar ödeyin (para kendi bakiyenize gider).

Bir fatura nasıl ilerler

Bir ödemede dört taraf vardır: müşteri, siteniz, blockwallets ve blockchain. Diyagram zamanda yukarıdan aşağı akar; sağ sütun her adımda faturanın durumudur.

Kısaca, beş adım:

1. Bir fatura oluşturursunuz (ödeme bağlantısı bunu sizin yerinize yapar ya da sunucunuz /v1/payment çağırır), ödeme sayfasının url adresini alır ve müşteriyi oraya yönlendirirsiniz.
2. Ödeme sayfasında müşteri bir coin ve bir ağ seçer, kendine ait adresi ve tutarı alır, cüzdanından ya da borsadan öder.
3. Transferi zincirde görürüz, yeterli onayı bekleriz, ardından ikinci bir node sağlayıcısıyla çapraz kontrol ederiz (bir node sahte veri veremesin diye).
4. Fatura paid olur ve hemen url_callback adresinize imzalı bir webhook POST'larız; birkaç saniye sonra ödeme sayfası müşteriyi url_success adresinize geri gönderir.
5. Para bakiyenize yatırılır; satıcı panelinden kendi cüzdanınıza çekersiniz.

Fatura durumu

is_final true olduğunda durum bir daha değişmez (geç ödemeler hariç).

Ödeme bağlantıları (kodsuz)

Satıcı paneli → “Ödemeler › Ödeme bağlantıları” → açıklama ve tutar girin (bir ağı sabitleyin ya da müşteri seçsin) → oluşturun. Her bağlantının bir URL'si ve bir QR kodu vardır.

• Biri bağlantıyı her açtığında yeni bir fatura oluşturulur, yani tek bağlantı tekrar tekrar kullanılabilir (örn. “Üyelik $99”).
• Her ödeme “Ödemeler › İşlemler” altında görünür; “Fonlar › Bakiye ve çekim” bölümünden cüzdanınıza çekin.
• “Geliştiriciler › Entegrasyon ve anahtarlar” altında kimlik bilgileri ve webhook URL'si oluşturduysanız, bağlantılarla yapılan ödemeler de aşağıdaki biçimde bildirilir.
• Kabulü durdurmak için “Devre dışı bırak”a tıklayın; bağlantı hemen çalışmayı bırakır.

API entegrasyonu

1. Kimlik bilgileri ve imzalama

Satıcı paneli → “Geliştiriciler › Entegrasyon ve anahtarlar” → bir merchant (UUID) ve bir API key oluşturun. Canlı için bir, Test için bir takım vardır: Canlı gerçek para alır, Test testnet'lerde çalışır. Ayrıca web sitesi alan adlarınızı ekleyin: url_callback, url_return ve url_success bu alan adlarında olmalıdır. API key yalnızca bir kez gösterilir — güvenle saklayın ve yalnızca sunucunuzda tutun.

Temel URL https://blockwallets.io. Her endpoint POST + JSON'dur ve şu başlıkları taşır:

• merchant: merchant UUID'niz (Canlı mı Test mi olduğunu bu belirler)
• sign: md5(base64(istek gövdesi) + API key); gövde, gönderdiğiniz JSON dizesinin birebir kendisidir

Başarıda {"state": 0, "result": {…}} döner; hatada {"state": 1, "message": "…"} (bkz. Hatalar).

Aşağıdaki başlıca endpoint'lerde bir “Dene” paneli vardır: Test merchant'ınızı ve API key'inizi girin; sayfa isteği tarayıcınızda imzalar, endpoint'i çağırır ve isteğin ile yanıtın tamamını gösterir (kimlik bilgileri sayfanın belleğinde kalır). İmza uyuşmadığında imza denetleyici ile adım adım karşılaştırın.

import crypto from "node:crypto";

async function call(path, data) {
  const body = JSON.stringify(data);
  const sign = crypto.createHash("md5").update(Buffer.from(body).toString("base64") + process.env.BW_API_KEY).digest("hex");
  const res = await fetch("https://blockwallets.io" + path, {
    method: "POST",
    headers: { merchant: process.env.BW_MERCHANT, sign, "Content-Type": "application/json" },
    body,
  });
  return res.json();
}

function bw_call(string $path, array $data): array {
    $body = json_encode($data, JSON_UNESCAPED_UNICODE);
    $sign = md5(base64_encode($body) . getenv('BW_API_KEY'));
    $ch = curl_init('https://blockwallets.io' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['merchant: ' . getenv('BW_MERCHANT'), 'sign: ' . $sign, 'Content-Type: application/json'],
    ]);
    return json_decode(curl_exec($ch), true);
}

import base64, hashlib, json, os, requests

def bw_call(path: str, data: dict) -> dict:
    body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
    sign = hashlib.md5((base64.b64encode(body.encode()).decode() + os.environ["BW_API_KEY"]).encode()).hexdigest()
    headers = {"merchant": os.environ["BW_MERCHANT"], "sign": sign, "Content-Type": "application/json"}
    return requests.post("https://blockwallets.io" + path, data=body.encode(), headers=headers).json()

2. Fatura oluşturma POST /v1/payment

Müşteri sipariş verdiğinde ya da bakiye yükleme sayfanızda bir tutar girdiğinde https://blockwallets.io/v1/payment çağırın ve müşteriyi dönen result.url adresine yönlendirin.

{
  "amount": "42.00",
  "currency": "USD",
  "order_id": "order_1042",
  "url_callback": "https://shop.example/webhooks/crypto",
  "url_return": "https://shop.example/cart",
  "url_success": "https://shop.example/thanks?order=1042"
}

{
  "state": 0,
  "result": {
    "uuid": "6f1c2a7e-…",
    "order_id": "order_1042",
    "amount": "42.00",
    "currency": "USD",
    "network": null,
    "address": null,
    "payer_amount": null,
    "payment_amount": null,
    "url": "https://blockwallets.io/pay/inv_01J8…",
    "expired_at": 1760965200,
    "status": "check",
    "is_final": false
  }
}

network, address ve payer_amount, müşteri bir ağ seçtiğinde doldurulur.

3. Faturaları sorgulama

• POST /v1/payment/info {"order_id": "…"} veya {"uuid": "…"}: tek bir faturayı alır ve bu sırada zinciri kontrol eder (10 saniyede en fazla bir kez).
• POST /v1/payment/list: liste, sayfa başına 15; isteğe bağlı date_from / date_to; sonraki sayfa dönen paginate.nextCursor ile (?cursor=…).
• POST /v1/payment/services: kullanılabilir ağlar ve her ağın asgari tutarı.
• POST /v1/payment/resend {"order_id": "…"}: ödenmiş / eksik ödenmiş bir faturanın webhook'unu yeniden gönderir.

Webhook'lar asıl kanaldır; sorgular yedektir (örneğin sunucunuz kapalıydı ve bir webhook'u kaçırdıysa).

4. Statik cüzdanlar POST /v1/wallet

Tek bir müşteri için tek bir ağda kalıcı bir adres açar. Aynı order_id (genelde kullanıcı kimliğiniz) + ağ her zaman aynı adresi verir; tüm EVM zincirleri (BNB Chain, Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, X Layer) tek adresi paylaşır, TRON, BTC, LTC, DOGE, BCH, Solana ve TON'un ise her birinin kendi adresi vardır. Müşterinin gönderdiği her şey yatırılır ve her transfer için bir webhook gelir; BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON transferleri görüldükleri andaki kurla ABD dolarına çevrilir (payment_amount_usd).

{
  "order_id": "user_42",
  "currency": "USDT",
  "network": "tron",
  "url_callback": "https://shop.example/webhooks/crypto"
}

{
  "state": 0,
  "result": {
    "wallet_uuid": "0b9d…",
    "uuid": "5e2f…",
    "order_id": "user_42",
    "currency": "USDT",
    "network": "tron",
    "address": "TXy4…8kQ2",
    "url": "https://blockwallets.io/deposit/dac_01J8…"
  }
}

result.url, müşteriye verebileceğiniz barındırılan bir yükleme sayfasıdır (adres + QR kodu + son yüklemeler). Ağın minimumunun altındaki transferler (genellikle $1, BTC $5) otomatik yatırılmaz; yatırılması için bize ulaşın. Adresleri engelleme (/v1/wallet/block-address) henüz desteklenmiyor.

Webhook'lar

Bir faturanın durumu değiştiğinde (paid, paid_over, wrong_amount_waiting, wrong_amount, cancel) ve bir statik cüzdana gelen her transferde url_callback adresine JSON POST'larız. 2xx yanıt teslim edildi sayılır; aksi halde 1 dakika, 5 dakika, 30 dakika, 2 saat, 12 saat, 24 saat ve 24 saat sonra yeniden deneriz. Panelden ya da /v1/payment/resend ile de yeniden gönderebilirsiniz.

{
  "type": "payment",
  "uuid": "6f1c2a7e-…",
  "order_id": "order_1042",
  "amount": "42.00",
  "payment_amount": "42",
  "payment_amount_usd": "42.00",
  "merchant_amount": "41.58",
  "commission": "0.42",
  "is_final": true,
  "status": "paid",
  "from": "TQ8m…",
  "wallet_address_uuid": null,
  "network": "tron",
  "currency": "USD",
  "payer_currency": "USDT",
  "payer_amount": "42",
  "payer_amount_exchange_rate": "1",
  "additional_data": null,
  "txid": "9c1e…",
  "sign": "5f0c9b…"
}

İmzayı doğrulayın (zorunlu)

İmza, webhook gövdesindeki sign alanıdır: sign'ı çıkarın, geri kalanı PHP json_encode gibi yeniden kodlayın (sıkıştırılmış, / karakteri \/ olarak kaçırılmış, ASCII dışı karakterler kaçırılmamış) ve md5(base64(kodlanmış) + API key) değeri sign ile eşit olmalıdır. Aynı moddaki API key'i kullanın. Aynı webhook birden fazla kez gelebilir — uuid + status ile tekilleştirin.

Doğrulama başarısız olursa ham webhook gövdesini imza denetleyiciye yapıştırın: her adımın sonucunu gösterir ve sizinkinin nerede farklılaştığını işaretler (hepsi tarayıcınızda çalışır; API key hiçbir yere yüklenmez). Panelin “Geliştiriciler › Webhook günlüğü”ndeki her webhook tek tıkla denetleyicide açılır.

import crypto from "node:crypto";

function verify(rawBody, apiKey) {
  const { sign, ...data } = JSON.parse(rawBody);
  const json = JSON.stringify(data).replaceAll("/", "\\/");
  const expected = crypto.createHash("md5").update(Buffer.from(json).toString("base64") + apiKey).digest("hex");
  return typeof sign === "string" && sign.length === expected.length && crypto.timingSafeEqual(Buffer.from(sign), Buffer.from(expected));
}

$data = json_decode(file_get_contents('php://input'), true);
$sign = $data['sign'] ?? '';
unset($data['sign']);
$expected = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiKey);
if (!hash_equals($expected, $sign)) {
    http_response_code(401); exit;
}

import base64, hashlib, hmac, json

def verify(raw_body: bytes, api_key: str) -> bool:
    data = json.loads(raw_body)
    sign = data.pop("sign", "")
    encoded = json.dumps(data, separators=(",", ":"), ensure_ascii=False).replace("/", "\\/")
    expected = hashlib.md5((base64.b64encode(encoded.encode()).decode() + api_key).encode()).hexdigest()
    return hmac.compare_digest(expected, sign)

Test modu

Test merchant'ı ve API key ile oluşturulan faturalar testnet'lerde çalışır, gerçek para söz konusu değildir. Ödeme sayfasında bir “Ödemeyi simüle et” düğmesi (tam / yarım / fazla ödeme) bulunur; böylece testnet coin'i edinmeden durum değişikliklerini ve webhook'ları görebilirsiniz.

• POST /v1/test-webhook/payment, /v1/test-webhook/wallet: doğrulama kodunuzda hata ayıklamak için url_callback adresine imzalı bir örnek webhook gönderir (kayıtlı alan adlarınızdan birinde olması gereken zorunlu url_callback ile birlikte currency, network ve isteğe bağlı olarak status, order_id iletin).
• Panel “Geliştiriciler › Entegrasyon ve anahtarlar” → “Test bildirimi gönder”: webhook URL'nize bir örnek gönderir.
• Panel “Geliştiriciler › Webhook günlüğü”: her teslim denemesi; zamanı, hedef URL, HTTP durumu, süresi, istek gövdesi ve sunucunuzun yanıtı (ilk 4 KB) ile; siparişe veya duruma göre filtreleyin ve tek tıkla yeniden gönderin. 30 gün saklanır.

Cryptomus'tan geçiş

1. Panel “Geliştiriciler › Entegrasyon ve anahtarlar” → bir merchant ve API key oluşturun.
2. Kodunuzdaki https://api.cryptomus.com adresini https://blockwallets.io ile değiştirin ve yeni merchant ile API key'i kullanın.
3. Alan adlarınızı “Web sitesi alan adları” altına ekleyin (url_callback / url_return / url_success yalnızca bunları kabul eder).

Desteklenenler: /v1/payment, /v1/payment/info, /v1/payment/list, /v1/payment/services, /v1/payment/resend, /v1/wallet, /v1/test-webhook/payment, /v1/test-webhook/wallet. Farklar: faturalar yalnızca USD / USDT / USDC cinsinden fiyatlanır (hepsi 1:1, kur farkı yok); commission bizim platform ücretimizdir (alınan tutar × faturanın oluşturulduğu andaki satıcı oranı — standart 1%, hacme göre 0.5%'e kadar düşer; müşterinin karşıladığı kısımdan iki kez ücret alınmaz) ve merchant_amount = alınan − commission; müşteri BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON ile ödediğinde birkaç borsanın medyan fiyatını veririz, 30 dakika sabitlenir — payer_amount gönderilecek coin miktarı, payer_amount_exchange_rate bir coin'in USD değeridir ve ödeme sabitlenen kurla payment_amount_usd'ye çevrilir (coin'ler bizde kalır, takas yapılmaz); ağlar tron / bsc / eth / base / polygon / arbitrum / optimism / avalanche / xlayer / btc / ltc / doge / bch / sol / ton; asgari fatura ömrü 10 dakika; is_refresh yok ve statik cüzdanlarda engelleme yok; webhook'lar varsayılan olarak değişen IP'lerden gelir; IP'ye göre izin listesi kullanıyorsanız panelde “Geliştiriciler › Entegrasyon ve anahtarlar” altındaki “Sabit IP webhook” ayarını açın; webhook'lar yalnızca 18.163.145.41 adresinden gelir — izin listesi ek bir katmandır, sign doğrulamaya devam edin.

NOWPayments veya Coinbase Commerce'ten mi geliyorsunuz? İkisi için de uyumlu API'lerimiz var — temel URL'yi ve anahtarları değiştirin; bkz. geçiş rehberi.

Ağlar ve tutarlar

ERC-20 ücretleri yüksektir, bu yüzden asgari $5; Bitcoin ücretleri de düşük değildir, asgari $5; geri kalan her şey $1. Müşteriler ödeme sayfasında gösterilen ağdan göndermelidir — başka bir ağdan gönderilen para otomatik yatırılmaz. BTC / LTC / DOGE / BCH mempool'a girer girmez “algılandı” görünür ve yeterli onaya ulaştığında sayılır; değiştirilen (RBF) veya düşen işlemler sayılmaz. Ağların kendi coin'leri (TRX, BNB, ETH, POL, AVAX, OKB, SOL, TON) sabitlenen kurla fiyatlanır ve BTC / LTC / DOGE / BCH gibi ABD doları olarak yatırılır; hem ağı hem coin'i belirtin: faturalar network: "bsc", to_currency: "BNB", statik cüzdanlar network: "bsc", currency: "BNB". Yalnızca ağ belirtilirse o zincirde varsayılan USDT'dir (Base'de USDC). Kontratların yaptığı transferler de (multisig, toplu ödemeler) alınır; bazı zincirlerde işlem hash'i bulunmaz ve webhook'taki txid null olur.

Hatalar

{ "state": 1, "message": "amount must be a number like 10.28" }

İmza yanlış olduğunda (Invalid Sign.) yanıtta bir debug nesnesi bulunur: body_base64 aldığımız istek gövdesinin base64'üdür (sizin kendi içeriğiniz, asla API key değil) ve body_bytes uzunluğudur. İmzaladığınız base64 ile karşılaştırın: farklıysa gönderdiğiniz gövde imzaladığınız dize değildir (framework'ünüz yeniden serileştirdi, bir proxy kodlamayı değiştirdi, sonda yeni satır var); aynıysa API key yanlıştır. İlk farkı görmek için imza denetleyiciye yapıştırın.

{
  "state": 1,
  "message": "Invalid Sign.",
  "debug": {
    "body_base64": "eyJhbW91bnQiOiI0Mi4wMCIsImN1cnJlbmN5IjoiVVNEIiwi…",
    "body_bytes": 158,
    "sign_formula": "md5(body_base64 + API key)"
  }
}

SSS

Müşteriler istedikleri tutarı yüklüyor — hangi mod?

Faturalar. Müşteri bakiye yükleme sayfanızda bir tutar girsin, o tutar için bir fatura oluşturun ve geldiğinde payment_amount_usd kadar yükleyin. Statik cüzdanları yalnızca müşteriler tek bir adresi kaydedip tekrar tekrar göndermeliyse kullanın.

Müşteri eksik öderse ne olur?

Süre dolmadan müşteri farkı ödeme sayfasından gönderebilir (sayfa ne kadarının hâlâ ödenmesi gerektiğini gösterir; durum wrong_amount_waiting, ilk eksik ödemede 30 dakikadan az kalmışsa son süre 30 dakika sonraya kayar). Süre dolduğunda hâlâ eksikse fatura wrong_amount olur ve webhook'taki payment_amount_usd alınan tutardır; bakiye yükleme işleri bunu olduğu gibi yükleyebilir.

Müşteri geç öderse ya da iki kez öderse?

Süre dolduktan sonra gelen para yine yatırılır ve bildirilir; fatura tamamen ödendikten sonra gelen para da kaydedilir ve panelde görünür.

Müşteri yanlış ağdan gönderirse?

Örneğin fatura TRON'da ve müşteri BNB Chain'den gönderdi: otomatik yatırılmaz — bizimle iletişime geçin, elle çözeriz.

Ne kadar tutar?

Alınan her ödemenin 1%'i; geçen ayın hacmine göre otomatik düşer ($50,000 üzeri 0.9%, $100,000 üzeri 0.8%, $250,000 üzeri 0.7%, $500,000 üzeri 0.6% ve $1,000,000 üzeri 0.5%); aylık veya kurulum ücreti yok. Ağ ücretini müşteri gönderirken öder; ücreti müşteriye yansıtmak için fatura oluştururken subtract gönderin ya da panelde varsayılan olarak ayarlayın. Çekimlerde ek ücret yoktur. Bkz. fiyatlar.

Para bana ne zaman ulaşır?

Ödeme onaylanır onaylanmaz bakiyenize yatırılır. “Fonlar › Bakiye ve çekim” altından kendi cüzdanınıza çekim talep edin; biz onaylayınca ödeme yaparız ve zincir üstü işlem çekim geçmişinizde görünür.

Otomatik çekimi de açabilirsiniz: kullanılabilir bakiyeniz belirlediğiniz tutara ulaşınca ya da günde bir kez 00:00 UTC'de kullanılabilir bakiyenin tamamı çekilir. Otomatik çekimler de aynı şekilde incelenir ve her ayar değişikliği e-postanıza bildirim gönderir.