Geliştiriciler İçin Kripto Ödeme API'si

Kimlik Doğrulama

Sunucunuzdan gelen her istek HTTP Basic auth kullanır: kullanıcı adı olarak proje kimliğiniz, parola olarak proje secret'ınız. Secret'ı sunucunuzda saklayın; webhook'larınızı da o imzalar.

https://payments.rubysoft.io/api

HTTP

Authorization: Basic base64(PROJECT_ID:PROJECT_SECRET)

Fatura Oluşturun

Müşteri tek bir sipariş için ödeme yaptığında fatura kullanın. payload olarak kendi 24 karakterlik sipariş kimliğinizi, USD fiyatı, tutarın ne kadar eksik kalabileceğini (%0 ile %5 arası), son geçerlilik zamanını ve bu faturanın webhook'larını alacak URL'yi gönderin.

payloadSipariş kimliğiniz, 24 onaltılık karakter (MongoDB ObjectId kullanılabilir)

meta[price]USD cinsinden fiyat

meta[tolerancePercent]İzin verilen eksik ödeme, 0 ile 5 arası

meta[expiresAt]Son geçerlilik zamanı, ISO 8601, gelecekte bir tarih

meta[webhookUrl]Bu faturanın olaylarının gönderileceği adres

curl -G https://payments.rubysoft.io/api/invoice/load \
  -u "$PROJECT_ID:$PROJECT_SECRET" \
  --data-urlencode "payload=65f2c1a9e4b0d3f7a2c91e04" \
  --data-urlencode "meta[price]=120" \
  --data-urlencode "meta[tolerancePercent]=1" \
  --data-urlencode "meta[expiresAt]=2026-12-01T12:00:00Z" \
  --data-urlencode "meta[webhookUrl]=https://shop.example/webhooks/rubynex"

Yanıt, ağa göre anahtarlanmış bir addresses nesnesi içerir. Müşterinize sunmak istediğiniz ağları gösterin.

200 OK

{
  "id": "0b6f3c1e-8a52-4d7e-9c41-2f6a8d0e5b17",
  "payload": "65f2c1a9e4b0d3f7a2c91e04",
  "meta": {
    "type": "invoice",
    "status": "pending",
    "price": "120",
    "paid": "0",
    "expiresAt": "2026-12-01T12:00:00.000Z"
  },
  "addresses": {
    "tron": "T…",
    "ethereum": "0x…",
    "bsc": "0x…",
    "bitcoin": "bc1q…"
  }
}

Kalıcı Yatırım Adresleri

Yüklemeler için kalıcı adresleri kullanın: cüzdanlar, oyunlar, borsalar, abonelikler. payload olarak müşterinizin 24 karakterlik kimliğini gönderin ve her seferinde aynı adresleri alın.

cURL

curl -G https://payments.rubysoft.io/api/charge/load \
  -u "$PROJECT_ID:$PROJECT_SECRET" \
  --data-urlencode "payload=66a0b7d2c5e8f1a3b6d904c7"

# the same customer ID always returns the same addresses

Fatura Durumları

pendingÖdeme bekleniyor

paidTutarın tamamı geldi

underpaidFiyattan daha az tutar geldi

overpaidFiyatın %1'inden fazla üzerinde tutar geldi

expiredSon geçerlilik zamanından önce ödeme gelmedi

Webhook'lar

Her olay, JSON gövdeli ve X-Webhook-Signature başlıklı bir POST isteğidir: ham gövdenin, hex'ten çözülmüş proje secret'ınızla anahtarlanan ve hex olarak yazılan HMAC-SHA256 değeri. Herhangi bir 2xx durum koduyla yanıt verin. Diğer her yanıtta yeniden denenir: fatura olayları iletilene kadar her 15 saniyede bir, ödeme olayları her 10 dakikada bir, en fazla 150 kez.

Olaylar

invoice:<status>Bir faturanın durumu değişti

pending-paymentBir ödeme görüldü ve onay bekliyor

confirmed-paymentBir ödeme onaylandı ve hesaba geçti

failed-paymentBir ödeme işlenemedi

Webhook

POST /webhooks/rubynex
Content-Type: application/json
X-Webhook-Signature: 9c1fd2…e07a

{
  "id": "4e1a…c93f",
  "message": {
    "event": "invoice:paid",
    "data": { "id": "0b6f3c1e-…", "payload": "65f2c1a9e4b0d3f7a2c91e04" }
  },
  "attempt": 0,
  "timestamp": 1764590400
}

İmzayı Doğrulayın

import crypto from 'node:crypto';
import express from 'express';

const secret = Buffer.from(process.env.RUBYNEX_SECRET, 'hex');

// keep the raw body: the signature covers its exact bytes
app.post('/webhooks/rubynex', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  const given = req.get('X-Webhook-Signature') ?? '';
  if (given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { message } = JSON.parse(req.body);
  if (message.event === 'invoice:paid') markOrderPaid(message.data.payload);
  res.sendStatus(200);
});

Ağa Göre Onaylar

Ağ	Coinler	Onaylar	Hesaba Geçiş Süresi
TRON	TRXUSDT	1	yaklaşık 3 sn
Ethereum	ETHUSDTUSDCDAI	5	yaklaşık 1 dk
BNB Smart Chain	BNBUSDTUSDCDAI	10	yaklaşık 8 sn
Polygon	POLUSDTUSDCDAI	20	yaklaşık 40 sn
Base	ETHUSDTUSDC	10	yaklaşık 20 sn
Bitcoin	BTC	1	yaklaşık 10 dk
XRP Ledger	XRP	1	yaklaşık 4 sn
Dogecoin	DOGE	3	yaklaşık 3 dk

Bilinmesi Gereken Limitler

$1 veya daha düşük ödemeler dust olarak yok sayılır
Fatura eksik ödeme toleransı: %5'e kadar
Fiyatının %1'inden fazla üzerinde tutar geldiğinde fatura fazla ödenmiş sayılır
Bir projenin secret'ı 5 dakikada bir yenilenebilir

Anahtarlarınızı Almaya Hazır mısınız?

Projenizi oluşturur, kimliğini ve secret'ını size iletiriz.

API Anahtarı Alın

Kripto Ödeme API'si: On Dakikada Okuyabileceğiniz Kadar Sade