AhbapPayAPI Referansı
Destekv2
Geliştirici Dokümantasyonu

Ahbap Pay API

Sitenizde veya uygulamanızda USDT (TRC20) ve TRX ile ödeme alın. Her fatura için müşteriye özel, tek kullanımlık bir TRON adresi üretilir. Ödeme zincirde iki bağımsız kaynaktan doğrulandığında tutar (komisyon düşülerek) bakiyenize anında yatar ve sunucunuza imzalı bildirim gönderilir.

Taban adres
https://pay.ahbapwallet.org/api/v1
Desteklenen varlıklar
USDT (TRC20) · TRX
Tutar aralığı
USDT1 – ∞TRX10 – ∞
Varsayılan fatura süresi
30 dakika
İçindekiler

Genel bakış

  • Taban adres: https://pay.ahbapwallet.org/api/v1
  • Biçim: JSON · tutarlar string olarak gönderilir (en fazla 6 ondalık)
  • Desteklenen: USDT (min 1 · maks limitsiz) · TRX (min 10 · maks limitsiz)
  • Varsayılan fatura süresi: 30 dakika (5–1440 arası ayarlanabilir)

Hızlı başlangıç

  1. Hesabınıza ödeme altyapısı yetkisi tanımlandığında botun ana menüsünde Ödeme Al butonu görünür.
  2. Ödeme Al → API Anahtarları → Yeni Anahtar: anahtar yalnızca bir kez gösterilir, güvenli bir yerde saklayın.
  3. Ödeme Al → Webhook: bildirim adresinizi girin ve imza anahtarınızı (whsec_…) alın.
  4. Sunucunuzdan fatura oluşturun, müşteriyi payment_url adresine yönlendirin ve invoice.paid bildirimiyle siparişi tamamlayın.

Kimlik doğrulama

Her isteğe X-API-Key başlığı ekleyin (alternatif: Authorization: Bearer <anahtar>). Anahtarı yalnızca sunucu tarafında kullanın; tarayıcıya veya mobil uygulamaya gömmeyin.

Hız sınırı: anahtar başına dakikada 120, IP başına dakikada 300 istek. Aşılırsa 429 RATE_LIMIT_EXCEEDED döner.

Fatura oluştur

POST/api/v1/payments
AlanTipAçıklama
amountstringZorunluTutar, ör. "25.00"
assetstringZorunluUSDT veya TRX
external_idstringSizin sipariş numaranız (≤128). Aynı değerle açık bir fatura varsa yenisi oluşturulmaz, mevcut olan döner.
descriptionstringMüşteriye ödeme sayfasında gösterilir (≤200)
callback_urlstringBu faturaya özel webhook adresi (yoksa hesap webhook'u kullanılır)
return_urlstringÖdeme tamamlanınca “Mağazaya dön” butonunun gideceği adres
metadataobjectSize geri dönecek serbest veri (≤4 KB)
expires_in_minutesnumber5–1440 (varsayılan 30)

Idempotency: Idempotency-Key başlığı gönderirseniz aynı anahtarla tekrar eden istekler aynı faturayı döndürür; ağ kopmasında güvenle tekrar deneyebilirsiniz. Yeni fatura 201, mevcut fatura 200 + "reused": true döner.

İstek

cURL
curl -X POST https://pay.ahbapwallet.org/api/v1/payments \
  -H "X-API-Key: ahb_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": "25.00",
    "asset": "USDT",
    "external_id": "order-1042",
    "description": "Sipariş #1042",
    "return_url": "https://magazam.com/tesekkurler",
    "metadata": { "customer_id": 881 }
  }'

Yanıt

JSON
{
  "success": true,
  "reused": false,
  "data": {
    "id": "AHBAP-7K2Q9-XWMR4-TDH8P-N3FZ6",
    "object": "invoice",
    "status": "pending",
    "asset": "USDT",
    "network": "TRON",
    "token_standard": "TRC20",
    "amount": "25",
    "amount_paid": "0",
    "amount_pending": "0",
    "amount_due": "25",
    "fee_percent": 1,
    "net_credited": "0",
    "deposit_address": "TQ7bW1yYk...9xZ",
    "payment_url": "https://pay.ahbapwallet.org/pay/AHBAP-7K2Q9-XWMR4-TDH8P-N3FZ6",
    "qr_code_url": "https://pay.ahbapwallet.org/pay/AHBAP-7K2Q9-XWMR4-TDH8P-N3FZ6/qr.svg",
    "external_id": "order-1042",
    "expires_at": "2026-10-06T12:30:00.000Z",
    "transactions": []
  }
}

Fatura sorgula

GET/api/v1/payments/:id
cURL
curl https://pay.ahbapwallet.org/api/v1/payments/AHBAP-7K2Q9-XWMR4-TDH8P-N3FZ6 \
  -H "X-API-Key: ahb_live_XXXXXXXX"

Yanıttaki transactions dizisi gelen her transferi gösterir: confirming (zincirde görüldü, onay bekleniyor) → confirmed (iki kaynakla doğrulandı, bakiyenize yazıldı).

Faturaları listele

GET/api/v1/payments
cURL
curl "https://pay.ahbapwallet.org/api/v1/payments?status=paid&limit=20&offset=0" \
  -H "X-API-Key: ahb_live_XXXXXXXX"

Parametreler: status (virgülle birden fazla; open = açık olanlar), limit (1–100), offset. Yanıttaki has_more sonraki sayfanın olduğunu belirtir.

Fatura iptal

POST/api/v1/payments/:id/cancel

Yalnızca hiç ödeme almamış ve pending durumundaki faturalar iptal edilebilir.

cURL
curl -X POST https://pay.ahbapwallet.org/api/v1/payments/AHBAP-7K2Q9-XWMR4-TDH8P-N3FZ6/cancel \
  -H "X-API-Key: ahb_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Müşteri vazgeçti"}'

Durumlar

DurumAnlamı
pendingÖdeme bekleniyor
confirmingTransfer zincirde görüldü; iki kaynak + geri alınamaz onay bekleniyor (~1 dk)
partially_paidOnaylı tutar eksik; süre dolana kadar kalan tutar aynı adrese gönderilebilir
paidTam ödendi (en fazla %0.5 yuvarlama farkı tolere edilir). Siparişi bu durumda tamamlayın.
underpaidSüre doldu, onaylı tutar eksik kaldı (gelen kısım yine bakiyenize yazıldı)
expiredSüre doldu, ödeme gelmedi
cancelledİptal edildi

Geç ödeme: fatura kapandıktan sonra (72 saate kadar) aynı adrese gelen ödemeler de doğrulanıp bakiyenize yazılır; süresi dolmuş bir fatura bu durumda paid durumuna geçebilir (paid_late: true).

Webhook'lar

Durum değişikliklerinde webhook adresinize POST gönderilir. 2xx dönmezseniz 1 dk, 5 dk, 15 dk, 1 sa, 3 sa, 6 sa, 12 sa ve 24 sa aralıklarla yeniden denenir. Aynı olay birden fazla gelebilir; X-Ahbap-Delivery veya olay id'si ile tekilleştirin.

OlayNe zaman
invoice.confirmingİlk transfer zincirde görüldü
invoice.partially_paidOnaylı tutar eksik
invoice.paidFatura tamamen ödendi
invoice.payment_receivedHer onaylı transfer bakiyenize yazıldığında (transaction alanıyla; geç ve fazla ödemeler dahil)
invoice.underpaidSüre doldu, eksik ödendi
invoice.expiredSüre doldu, ödeme yok
invoice.cancelledİptal edildi
pingPanelden veya bottan gönderilen test

Örnek istek

HTTP
POST https://magazam.com/webhook
X-Ahbap-Event: invoice.paid
X-Ahbap-Delivery: evt_9c1d0e2f3a4b5c6d7e8f9a0b
X-Ahbap-Timestamp: 1791300000
X-Ahbap-Signature: t=1791300000,v1=5d41402abc4b2a76b9719d911017c592...

{
  "id": "evt_9c1d0e2f3a4b5c6d7e8f9a0b",
  "object": "event",
  "type": "invoice.paid",
  "created_at": "2026-10-06T12:04:11.000Z",
  "data": {
    "invoice": { "id": "AHBAP-7K2Q9-XWMR4-TDH8P-N3FZ6", "status": "paid", "amount": "25", "amount_paid": "25", "external_id": "order-1042", "...": "..." }
  }
}

İmza doğrulama

X-Ahbap-Signature: t=<unix>,v1=<hex> — v1 = HMAC_SHA256(webhook_secret, t + "." + ham_gövde). Gövdeyi JSON'a çevirmeden ham haliyle doğrulayın ve 5 dakikadan eski zaman damgalarını reddedin.

const crypto = require('crypto');

// rawBody: isteğin HAM gövdesi (JSON.parse ÖNCESİ string/Buffer)
function verifyAhbapSignature(rawBody, header, secret) {
  const p = {};
  String(header || '').split(',').forEach(function (kv) {
    const i = kv.indexOf('=');
    if (i > 0) p[kv.slice(0, i).trim()] = kv.slice(i + 1).trim();
  });
  if (!p.t || !p.v1) return false;
  const expected = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(p.v1);
  const sigOk = a.length === b.length && crypto.timingSafeEqual(a, b);
  const fresh = Math.abs(Date.now() / 1000 - Number(p.t)) < 300; // 5 dk tekrar-oynatma koruması
  return sigOk && fresh;
}

Ödeme sayfası

payment_url müşteriye hazır, mobil uyumlu bir ödeme sayfası açar: tutar, ağ, adres (kopyala), QR kod, geri sayım ve canlı durum takibi. Sayfa açık/koyu temayı ve Türkçe/İngilizce dili otomatik seçer (?lang=tr / ?lang=en ile zorlanabilir). Kendi arayüzünüzü yapacaksanız deposit_address ve qr_code_url (SVG) alanlarını kullanın.

Hata kodları

HTTPKodAçıklama
400VALIDATION_ERROREksik veya hatalı alan
400AMOUNT_TOO_LOW · AMOUNT_TOO_HIGHLimit dışı tutar
400INVALID_ASSETUSDT veya TRX dışında bir varlık
400INVALID_CALLBACK_URLYalnızca herkese açık http(s) adresleri kabul edilir
401INVALID_API_KEYAnahtar yok, geçersiz veya iptal edilmiş
403MERCHANT_SUSPENDED · MERCHANT_REVOKEDHesap askıda veya yetki kaldırılmış
403INSUFFICIENT_SCOPEAnahtarın bu işlem için yetkisi yok
404INVOICE_NOT_FOUNDFatura yok veya size ait değil
429RATE_LIMIT_EXCEEDED · TOO_MANY_OPEN_INVOICESHız sınırı veya açık fatura limiti (300)
503GATEWAY_DISABLEDSistem geçici olarak kapalı

En iyi uygulamalar

  • Siparişi yalnızca invoice.paid (veya API'de status = paid) ile tamamlayın; webhook'a ek olarak GET /payments/:id ile teyit etmek en güvenlisidir.
  • Her sipariş için external_id + Idempotency-Key kullanın; yeniden denemeler çift fatura üretmez.
  • Webhook işleyiciniz hızlıca 200 dönsün; ağır işleri kuyruğa alın.
  • underpaid ve geç ödemeler için müşteriyle iletişim akışınız olsun (tutarlar zaten bakiyenizdedir).

Teknik destek

Entegrasyonda yardıma mı ihtiyacınız var?

API, webhook veya ödeme akışıyla ilgili sorularınız için destek ekibimize ulaşın. Hızlı yardım için mesajınıza fatura numarasını (AHBAP-…) ve isteğin zaman damgasını ekleyin.