Parazum Ödeme API v2.0

Bayi e-ticaret entegrasyonu. Kart bilgisi yalnızca Parazum'un barındırdığı ödeme formunda girilir; sisteminiz kart verisi görmez.

Genel bakış

• Tüm uçlar POST ve application/json. Yanıtta responseCode "00" başarıdır.
• Tutarlar TL'dir (currency yalnızca TRY), en fazla 2 ondalık.
• Tahsil edilen tutar, oturumdaki amount'tır (brüt). Taksit seçimi müşteri tutarını değiştirmez; komisyon ve size kalan net tutar, sizin için onaylanan oranlara göre hesaplanır.
• Ödemeyi Payinall bayinizin IBAN'ına öder. Parazum ödemeyi kayıt altına alır; cüzdana yazmaz.
• 3D Secure zorunludur.

Adresler

API anahtarı ve modlar

• Anahtarı merchant panelinde Geliştirici API sayfasından siz oluşturursunuz. Yeni anahtar her zaman sandbox modundadır.
• API gizli anahtarı ve webhook imza anahtarı yalnızca oluşturulduğunda bir kez gösterilir. Kaybederseniz panelden yenileyin; eski anahtar hemen geçersiz olur.
• Canlı mod: hesabınız tahsilata hazır olduğunda (başvuru ve KYB onaylı, sanal POS aktif, oranlar onaylı) panelden talep edersiniz; anahtar, Parazum yöneticisinin onayından sonra çalışır. Onaysız canlı anahtar 403 alır.
• Webhook adresinizi panelde kayıtlı tutmanızı öneririz; kayıtlı adres, oturumdaki callbackUrl'den önceliklidir.

İstek imzası

Her API isteği aşağıdaki başlıkları taşır. İmza; yöntemi, yolu, zamanı, tek kullanımlık değeri ve gövdenin tamamını kapsar.

Kanonik metin (satır sonu \n):

METHOD            ör. POST
PATH              ör. /v2/create  (sorgu dizesi hariç)
TIMESTAMP         X-Request-Timestamp ile aynı
NONCE             X-Nonce ile aynı
SHA256(BODY)      gönderdiğiniz ham gövdenin küçük harf hex SHA-256 özeti

$body = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$ts = (string) time();
$nonce = bin2hex(random_bytes(16));
$canonical = "POST\n/v2/create\n{$ts}\n{$nonce}\n".hash('sha256', $body);
$signature = hash_hmac('sha256', $canonical, $clientSecret);

$headers = [
    'Content-Type: application/json',
    'X-Api-Key: '.$clientId,
    'X-Merchant-Id: '.$merchantId,
    'X-Request-Timestamp: '.$ts,
    'X-Nonce: '.$nonce,
    'X-Signature: '.$signature,
];
// Gövdeyi imzaladığınız $body ile BİREBİR aynı gönderin.

İmzalı isteklerde sorgu dizesi (query string) kullanılamaz; tüm parametreleri imzalı JSON gövdesinde gönderin. Sorgu dizesi içeren istek 400 alır.

Hız sınırları: IP ve anahtar başına dakikada 120 istek; dakikada 60 hatalı kimlik denemesinden sonra IP bir dakika engellenir (429).

Ödeme akışı

1. POST /v2/create ile oturum açın (tutar, sipariş no). Hesabınız tahsilata hazır değilse burada 403 / 16 alırsınız.
2. POST /v2/form ile ödeme formu adresini alın ve müşteriye iframe ya da tam sayfa olarak gösterin.
3. Müşteri kartını girer, taksidi seçer; banka 3D sayfasına yönlenir.
4. 3D sonucu Parazum'a gelir; Parazum sonucu Payinall'dan sunucu tarafında doğrular.
5. Müşteri returnUrl'inize döner; siz de imzalı webhook alırsınız. Siparişi yalnızca webhook ya da /v2/verify sonucuna göre onaylayın.

POST https://api-payment.parazum.com/v2/create

{"responseCode":"00","responseMsg":"Başarılı!","sessionToken":"…","orderId":"ORD-1001","sandbox":false}

POST https://api-payment.parazum.com/v2/form

Gövde: {"sessionToken":"…"}. Oturum 30 dakika geçerlidir.

{"responseCode":"00","responseMsg":"Başarılı!","iframeUrl":"https://payment.parazum.com/v2/view-form/…","iframeData":"<iframe …></iframe>"}

Kart formu ve 3D

Form Parazum tarafından barındırılır (https://payment.parazum.com/v2/view-form/{token}). Formda yalnızca sizin için fiyatlanabilen taksitler gösterilir. Aynı oturum için ikinci kez gönderim yapılamaz: süren bir ödeme varken 409 / 15 döner, böylece müşteri iki kez 3D'ye gönderilmez.

3D dönüşü

Banka sonucu POST https://payment.parazum.com/v2/callback/3d/{transactionId} adresine gelir (yalnızca POST). Sonuç sunucu tarafında Payinall'dan sorgulanarak doğrulanır. returnUrl verdiyseniz müşteri şu adrese yönlenir (HTTP 303):

{returnUrl}?orderId=ORD-1001&transactionId=…&status=SUCCESS|FAILED|PENDING

POST https://api-payment.parazum.com/v2/verify  ·  /query

Gövde: {"orderId":"ORD-1001"}. Yalnızca kendi siparişlerinizi görürsünüz.

{"responseCode":"00","orderDetail":{"orderId":"ORD-1001","transactionId":"…","orderStatus":"Sale",
 "orderDate":"2026-10-15 14:03:11","orderCurrency":"TRY","orderPrice":100.0,"orderEarn":97.0,
 "orderCommission":3.0,"installment":1,"sandbox":false}}

orderStatus: Sale, Pending, Review, Fail, Cancelled, Refunded (sandbox'ta ayrıca RefundRequested).

POST https://api-payment.parazum.com/v2/installments

Gövde: {"binCode":"415565","amount":1000.00}. Yanıt, sizin için onaylanmış oranlarla hesaplanır; banka/Payinall'ın ham BIN yanıtı dönmez.

{"responseCode":"00","data":{"binCode":"415565","cardType":"Credit","cardBrand":"visa","amount":1000.0,"currency":"TRY",
 "installments":[{"installment":1,"totalAmount":1000.0,"installmentAmount":1000.0,"commissionRate":3.0,"commissionAmount":30.0,"netAmount":970.0},
                 {"installment":3,"totalAmount":1000.0,"installmentAmount":333.33,"commissionRate":6.0,"commissionAmount":60.0,"netAmount":940.0}]}}

POST https://api-payment.parazum.com/v2/void  ·  /refund

İptal ve iade talep olarak alınır; Parazum ekibi Payinall kurallarına göre uygular: ödeme ile aynı gün iptal (void), sonraki günlerde iade (refund). Payinall yalnızca tam tutarlı iade/iptal destekler.

Gövde: {"orderId":"ORD-1001","amount":100.00,"reason":"Müşteri siparişi iptal etti"} (/void'de amount yoktur; reason isteğe bağlı).

HTTP 202
{"responseCode":"00","responseMsg":"İade/iptal talebiniz alındı. …","status":"requested","refundRequestId":42,"orderId":"ORD-1001","amount":100.0}

Kısmi tutar 422 / 12 "Yalnızca tam tutarlı iade yapılabilir." döner. Aynı sipariş için ikinci talep 409 / 14. Talep açıldığında refund.requested webhook'u gönderilir.

Webhook

Kesin sonuç, kayıtlı webhook adresinize (yoksa oturumdaki callbackUrl'e) POST edilir. Ödeme sonucu ilk anda doğrulanamazsa (PENDING), sonuç netleştiğinde ayrıca bildirilir.

İmza anahtarı, API gizli anahtarından ayrı olan webhook imza anahtarıdır (panelde bir kez gösterilir).

{"eventId":"7f0c…","eventType":"payment.succeeded","orderId":"ORD-1001","transactionId":"…","status":"SUCCESS",
 "amount":100.0,"netAmount":97.0,"currency":"TRY","installment":1,"sandbox":false,
 "responseCode":"00","responseMsg":"Başarılı","timestamp":1760536991}

eventType: payment.succeeded, payment.failed, payment.pending, refund.requested.

$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_PARAZUM_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_PARAZUM_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $ts.'.'.$raw, $webhookSecret);

if (! hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(403); exit;
}
$event = json_decode($raw, true);
if (already_processed($event['eventId'])) { http_response_code(200); exit; }
// … siparişi güncelleyin …
http_response_code(200);

2xx dışındaki yanıtlar 30 ve 120 saniye sonra yeniden denenir (en fazla 3 deneme). Yönlendirmeler izlenmez; adres yalnızca herkese açık https olabilir.

Sandbox

Sandbox modundaki anahtarlar hiçbir zaman Payinall'a gitmez ve karttan çekim yapmaz. Akış, yanıtlar ve imzalı webhook'lar canlı ile aynıdır; gövdede "sandbox": true bulunur. 3D adımında bir test doğrulama sayfası açılır.

Son kullanma tarihi gelecekte herhangi bir ay, CVV herhangi 3 hane. Diğer kartlar 422 / 18 alır. Sandbox taksit oranları: 1: %2,49 · 2: %4,19 · 3: %5,29 · 6: %8,99 · 9: %12,49 · 12: %15,99. Sandbox kayıtları raporlara, komisyona ve mutabakata girmez.

Hata kodları

Kimlik doğrulama hataları {"message":{"code":401,"error":["…"]},"type":"error"} biçimindedir: 401 geçersiz anahtar/imza, 403 IP izni, tekrar (replay), onaysız canlı anahtar, 429 hız sınırı.

Değişiklikler (v2.0)

• İstek imzası method, yol, zaman, nonce ve gövdeyi kapsar (X-Signature).
• Webhook imzasına zaman damgası ve olay kimliği eklendi; webhook ayrı anahtarla imzalanır.
• İptal/iade talep olarak alınır (202), yalnızca tam tutar.
• Taksit seçenekleri bayiye onaylı oranlarla hesaplanır.
• Sandbox modu eklendi; ayrı test sunucusu yoktur.