Entegrasyon Kılavuzu

Bu API ile web sitenize veya uygulamanıza TRON ağı üzerinden USDT (TRC20) ve TRX ödeme yöntemi ekleyebilirsiniz. Müşteri ödeme sayfamızda QR kodu okutarak ödeme yapar; sistem transferi blockchain üzerinde otomatik algılar, onaylar ve sunucunuza webhook ile bildirir.

Ödeme akışı

1. Müşteri sitenizde "Kripto ile öde" seçer.
2. Sunucunuz POST /payments çağırır, yanıttaki payment_url adresine müşteriyi yönlendirir.
3. Her ödeme için yeni ve tek kullanımlık bir yatırma adresi oluşturulur. Müşteri gösterilen tutarı bu adrese gönderir. Birden fazla transferle ödenirse (kısmi ödeme) tutarlar toplanır ve kalan tutar ödeme sayfasında gösterilir.
4. Transfer algılanınca payment.detected, blockchain'de kesinleşince (~1 dk) payment.confirmed webhook'u gelir.
5. payment.confirmed aldığınızda siparişi ödendi olarak işaretleyin. Ödeme sayfası onaydan 5 saniye sonra müşteriyi otomatik olarak success_url adresine döndürür; adrese ?payment_id=…&order_id=…&status=confirmed eklenir.
6. Müşteri ödemeden vazgeçerse veya süre dolarsa "Mağazaya dön" butonu return_url adresine (status=canceled) götürür.

Kimlik doğrulama

Merchant panelinde API anahtarları sayfasından anahtar oluşturun ve her isteğe ekleyin:

Authorization: Bearer wx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Anahtarı sadece sunucu tarafında saklayın; tarayıcı JavaScript'ine veya mobil uygulamaya koymayın. Limit: anahtar başına dakikada 120 istek.

POST/payments

Yeni ödeme talebi (fatura) oluşturur.

curl -X POST https://weoxpay.com/api/v1/payments \
  -H "Authorization: Bearer wx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "USDT",
    "network": "TRON",
    "order_id": "ORDER-10001",
    "callback_url": "https://magazam.com/webhook/crypto",
    "success_url": "https://magazam.com/siparis/10001/tesekkurler",
    "return_url": "https://magazam.com/sepet"
  }'

Yanıt 201 Created (mevcut ödeme dönerse 200):

{
  "payment_id": "PAY-7KQ2M9XH4TZD",
  "order_id": "ORDER-10001",
  "status": "pending",
  "currency": "USDT",
  "network": "TRON",
  "amount": "100.00",
  "amount_due": "100.000000",
  "amount_paid": "0.000000",
  "fee": "0.000000",
  "net_amount": "0.000000",
  "payment_address": "TN4x…(bu ödemeye özel adres)",
  "payment_url": "https://weoxpay.com/pay/PAY-7KQ2M9XH4TZD",
  "tx_hash": null,
  "expires_at": "2026-11-04T22:00:00.000Z",
  "created_at": "2026-11-04T21:00:00.000Z",
  ...
}

Müşteriyi payment_url adresine yönlendirin. Kendi ödeme ekranınızı yapmak isterseniz amount_due ve payment_address bilgilerini gösterin — müşteri amount_due tutarını göndermelidir.

GET/payments/{payment_id veya order_id}

curl https://weoxpay.com/api/v1/payments/PAY-7KQ2M9XH4TZD -H "Authorization: Bearer wx_live_..."

Yanıt, oluşturma yanıtı ile aynı yapıdadır.

GET/payments?status=confirmed&limit=20&offset=0

Ödemelerinizi yeniden eskiye listeler: { "data": [ ... ], "limit": 20, "offset": 0 }

GET/balance

{ "USDT": { "available": "1250.400000", "pending_withdrawal": "0.000000" },
  "TRX":  { "available": "0.000000",    "pending_withdrawal": "0.000000" } }

Ödeme durumları

Webhook

Durum her değiştiğinde callback_url (yoksa paneldeki webhook URL) adresine POST gönderilir. Olaylar: payment.detected, payment.confirmed, payment.overpaid, payment.underpaid, payment.expired, payment.late, payment.refunded, payment.canceled, test.

POST /webhook/crypto
Content-Type: application/json
X-Webhook-Id: WH-3HQ8...
X-Webhook-Event: payment.confirmed
X-Webhook-Timestamp: 1793833200
X-Webhook-Signature: sha256=5f0c1b...

{
  "id": "WH-3HQ8...",
  "event": "payment.confirmed",
  "created_at": "2026-11-04T21:04:12.000Z",
  "data": {
    "payment_id": "PAY-7KQ2M9XH4TZD",
    "order_id": "ORDER-10001",
    "status": "confirmed",
    "currency": "USDT",
    "network": "TRON",
    "amount": "100.00",
    "amount_due": "100.000000",
    "amount_paid": "100.000000",
    "fee": "2.000000",
    "net_amount": "98.000000",
    "tx_hash": "a3f1...",
    ...
  }
}

• Sunucunuz 2xx dönmelidir (10 sn içinde). Aksi halde 1 dk, 5 dk, 15 dk, 1 sa, 3 sa, 6 sa, 12 sa, 24 sa aralıklarla tekrar denenir.
• Aynı olay birden fazla gelebilir — idempotent işleyin (X-Webhook-Id veya payment_id + status ile).
• Panelden geçmiş bildirimleri görebilir ve tekrar gönderebilirsiniz.

İmza doğrulama

İmza: HMAC-SHA256(webhook_secret, X-Webhook-Timestamp + "." + ham_gövde), hex. webhook_secret panelde Webhook sayfasındadır. Ham gövdeyi (JSON parse etmeden önce) kullanın ve 5 dakikadan eski zaman damgalarını reddedin.

PHP örneği

1) Ödeme oluşturma (checkout):

<?php
$apiKey = getenv('CRYPTO_API_KEY');
$payload = [
    'amount'       => number_format($order->total, 2, '.', ''),
    'currency'     => 'USDT',
    'order_id'     => 'ORDER-' . $order->id,
    'callback_url' => 'https://magazam.com/crypto-webhook.php',
    'success_url'  => 'https://magazam.com/tesekkurler?order=' . $order->id,
];
$ch = curl_init('https://weoxpay.com/api/v1/payments');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey", 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$res = json_decode(curl_exec($ch), true);
header('Location: ' . $res['payment_url']);

2) Webhook (crypto-webhook.php):

<?php
$secret = getenv('CRYPTO_WEBHOOK_SECRET');
$body   = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($expected, $sig) || abs(time() - (int)$ts) > 300) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);
$p = $event['data'];
if (in_array($event['event'], ['payment.confirmed', 'payment.overpaid'])) {
    // $p['order_id'] siparişini "ödendi" yap (zaten ödendiyse tekrar işleme)
}
http_response_code(200);

Node.js örneği

// Ödeme oluştur
const r = await fetch('https://weoxpay.com/api/v1/payments', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CRYPTO_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: '49.90', currency: 'USDT', order_id: 'ORDER-10001' }),
});
const payment = await r.json();
res.redirect(payment.payment_url);

// Webhook (Express) — ham gövde gerekir
const crypto = require('crypto');
app.post('/webhook/crypto', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Webhook-Timestamp');
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.CRYPTO_WEBHOOK_SECRET)
    .update(`${ts}.${req.body}`).digest('hex');
  const sig = req.get('X-Webhook-Signature') || '';
  if (sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
      || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  if (event.event === 'payment.confirmed') {
    // event.data.order_id siparişini ödendi yap
  }
  res.sendStatus(200);
});

Hata kodları

{ "error": { "code": "invalid_amount", "message": "..." } }

Canlıya geçiş kontrol listesi

• API anahtarı sunucu ortam değişkeninde, kod deposunda değil.
• Webhook imzası ve zaman damgası doğrulanıyor.
• Webhook işleme idempotent (aynı olay iki kez gelirse sipariş iki kez işlenmiyor).
• Sipariş sadece confirmed/overpaid durumunda onaylanıyor.
• Müşteriye "tam tutarı TRC20 ağından gönderin" uyarısı gösteriliyor (ödeme sayfamız bunu zaten yapar).
• Panelden Test bildirimi gönder ile webhook uç noktanız test edildi.