İç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ıç
- Hesabınıza ödeme altyapısı yetkisi tanımlandığında botun ana menüsünde Ödeme Al butonu görünür.
- Ödeme Al → API Anahtarları → Yeni Anahtar: anahtar yalnızca bir kez gösterilir, güvenli bir yerde saklayın.
- Ödeme Al → Webhook: bildirim adresinizi girin ve imza anahtarınızı (
whsec_…) alın. - Sunucunuzdan fatura oluşturun, müşteriyi
payment_urladresine yönlendirin veinvoice.paidbildirimiyle 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
| Alan | Tip | Açıklama |
|---|---|---|
amount | string | ZorunluTutar, ör. "25.00" |
asset | string | ZorunluUSDT veya TRX |
external_id | string | Sizin sipariş numaranız (≤128). Aynı değerle açık bir fatura varsa yenisi oluşturulmaz, mevcut olan döner. |
description | string | Müşteriye ödeme sayfasında gösterilir (≤200) |
callback_url | string | Bu faturaya özel webhook adresi (yoksa hesap webhook'u kullanılır) |
return_url | string | Ödeme tamamlanınca “Mağazaya dön” butonunun gideceği adres |
metadata | object | Size geri dönecek serbest veri (≤4 KB) |
expires_in_minutes | number | 5–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 -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
{
"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
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
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
Yalnızca hiç ödeme almamış ve pending durumundaki faturalar iptal edilebilir.
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
| Durum | Anlamı |
|---|---|
| pending | Ödeme bekleniyor |
| confirming | Transfer zincirde görüldü; iki kaynak + geri alınamaz onay bekleniyor (~1 dk) |
| partially_paid | Onaylı tutar eksik; süre dolana kadar kalan tutar aynı adrese gönderilebilir |
| paid | Tam ödendi (en fazla %0.5 yuvarlama farkı tolere edilir). Siparişi bu durumda tamamlayın. |
| underpaid | Süre doldu, onaylı tutar eksik kaldı (gelen kısım yine bakiyenize yazıldı) |
| expired | Sü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.
| Olay | Ne zaman |
|---|---|
invoice.confirming | İlk transfer zincirde görüldü |
invoice.partially_paid | Onaylı tutar eksik |
invoice.paid | Fatura tamamen ödendi |
invoice.payment_received | Her onaylı transfer bakiyenize yazıldığında (transaction alanıyla; geç ve fazla ödemeler dahil) |
invoice.underpaid | Süre doldu, eksik ödendi |
invoice.expired | Süre doldu, ödeme yok |
invoice.cancelled | İptal edildi |
ping | Panelden veya bottan gönderilen test |
Örnek istek
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;
}<?php
function verifyAhbapSignature(string $rawBody, string $header, string $secret): bool {
$p = [];
foreach (explode(',', $header) as $kv) {
[$k, $v] = array_pad(explode('=', $kv, 2), 2, '');
$p[trim($k)] = trim($v);
}
if (empty($p['t']) || empty($p['v1'])) return false;
$expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $p['v1']) && abs(time() - (int)$p['t']) < 300;
}
$raw = file_get_contents('php://input');
if (!verifyAhbapSignature($raw, $_SERVER['HTTP_X_AHBAP_SIGNATURE'] ?? '', 'whsec_...')) {
http_response_code(400); exit;
}
$event = json_decode($raw, true);
http_response_code(200);import hmac, hashlib, time
def verify_ahbap_signature(raw_body: bytes, header: str, secret: str) -> bool:
p = dict(kv.split("=", 1) for kv in header.split(",") if "=" in kv)
if "t" not in p or "v1" not in p:
return False
msg = (p["t"] + ".").encode() + raw_body
expected = hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, p["v1"]) and abs(time.time() - int(p["t"])) < 300Ö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ı
| HTTP | Kod | Açıklama |
|---|---|---|
| 400 | VALIDATION_ERROR | Eksik veya hatalı alan |
| 400 | AMOUNT_TOO_LOW · AMOUNT_TOO_HIGH | Limit dışı tutar |
| 400 | INVALID_ASSET | USDT veya TRX dışında bir varlık |
| 400 | INVALID_CALLBACK_URL | Yalnızca herkese açık http(s) adresleri kabul edilir |
| 401 | INVALID_API_KEY | Anahtar yok, geçersiz veya iptal edilmiş |
| 403 | MERCHANT_SUSPENDED · MERCHANT_REVOKED | Hesap askıda veya yetki kaldırılmış |
| 403 | INSUFFICIENT_SCOPE | Anahtarın bu işlem için yetkisi yok |
| 404 | INVOICE_NOT_FOUND | Fatura yok veya size ait değil |
| 429 | RATE_LIMIT_EXCEEDED · TOO_MANY_OPEN_INVOICES | Hız sınırı veya açık fatura limiti (300) |
| 503 | GATEWAY_DISABLED | Sistem geçici olarak kapalı |
En iyi uygulamalar
- Siparişi yalnızca
invoice.paid(veya API'destatus = paid) ile tamamlayın; webhook'a ek olarakGET /payments/:idile teyit etmek en güvenlisidir. - Her sipariş için
external_id+Idempotency-Keykullanın; yeniden denemeler çift fatura üretmez. - Webhook işleyiciniz hızlıca
200dönsün; ağır işleri kuyruğa alın. underpaidve geç ödemeler için müşteriyle iletişim akışınız olsun (tutarlar zaten bakiyenizdedir).
Teknik destek
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.