Ödeme Sonucu
Ödeme sayfası, müşteri açtıktan sonra 30 dakika geçerlidir. Bu sürede ödemeye başlanmazsa işlem kaydı oluşmaz ve webhook gönderilmez. Link açık kalır; müşteri linki yeniden açarak ödemeye devam edebilir.
Yönlendirme
success_url / cancel_url verildiyse müşteri ödeme sonrası bu adreslere yönlendirilir. Yönlendirme yalnız kullanıcı deneyimi içindir; siparişi onaylamak için webhook'u kullanın.
Webhook
Webhook adresinizi Merchant Portal'da Ayarlar → Webhook'lar → Yeni Webhook ekranından tanımlarsınız:
- Gövde biçimi:
Olay zarfı (önerilen)seçin. Aşağıdaki gövde bu biçimdedir. - Olaylar: aşağıdaki tablodaki olayları seçin. Hiçbir olay seçilmezse adres tüm olayları alır.
- Tanımlama sırasında gösterilen imza anahtarını (
whsec_...) saklayın.
Olaylar
| Olay | Ne zaman |
|---|---|
sanalpos.payment.completed | Ödeme başarılı |
sanalpos.payment.failed | Ödeme reddedildi |
sanalpos.payment.not_completed | Müşteri 3D Secure adımına geçti ama 5 dakika içinde tamamlamadı. Olay birkaç dakika gecikmeyle gelir |
sanalpos.three_ds.completed | 3D doğrulama başarılı |
sanalpos.three_ds.failed | 3D doğrulama başarısız |
Başlıklar
| Başlık | Açıklama |
|---|---|
X-Odeal-Event | Olay tipi |
X-Odeal-Event-Id | Olayın tekil kimliği. Olayın tekrar gelme ihtimaline karşı bu değerle tekilleştirin |
X-Odeal-Delivery-Id | Teslim denemesinin kimliği |
X-Odeal-Timestamp | Gönderim zamanı, Unix saniyesi (ör. 1794900513) |
X-Odeal-Signature | sha256=<imza> |
Gövde
Kısaltılmış örnek:
{
"id": "evt_0dc30e82895f455a93a9b4f34125e4a4",
"object": "event",
"type": "sanalpos.payment.completed",
"created": "2026-11-17T10:28:32.816+03:00",
"livemode": true,
"api_version": "2026-09-24",
"resource_id": "9173d292-44b7-445e-93b8-abd4ae2c314c",
"data": {
"object": {
"transaction_id": "9173d292-44b7-445e-93b8-abd4ae2c314c",
"event_type": "sanalpos.payment.completed",
"occurred_at": "2026-11-17T10:28:32.816+03:00",
"status": "completed",
"operation_type": "sale",
"amount": 20000,
"currency": "TRY",
"installment_count": 1,
"masked_card_number": "543081******5470",
"external_id": "SIP-2026-0001-8dc017964bb440488299559bc684f310",
"basket_id": "SEPET-778",
"error_code": null,
"error_message": null,
"metadata": {
"payment_link_id": "c50320cc-03c1-496e-8754-4a5f6e90c846",
"payment_link_slug": "0ry3l3f4fi",
"magaza.external_id": "SIP-2026-0001",
"magaza.basket_id": "SEPET-778",
"magaza.product_type": "physical",
"pv_order": "{\"lines\":[{\"product_id\":\"...\",\"name\":\"...\",\"unit_price\":10000,\"quantity\":2,\"line_total\":20000,...}],\"total\":20000,\"shipping_address\":{...},\"billing_address\":{...}}"
}
}
}
}data.object içinde kullanmanız gereken alanlar:
| Alan | Açıklama |
|---|---|
transaction_id | İşlem kimliği. İşlem sorgulamada kullanılır |
status | completed, failed, not_completed |
amount | Tahsil edilen tutar, kuruş |
installment_count | Taksit sayısı |
external_id | <magaza.external_id>-<oturum-id> (bkz. Mutabakat) |
basket_id | Linkte verdiğiniz magaza.basket_id |
error_code / error_message | Başarısız işlemde ret bilgisi |
metadata.payment_link_id | İşlemin geldiği link |
metadata.pv_order | Sipariş ayrıntısı; JSON metni olarak gelir, ayrıca çözülmelidir. Ürün satırları ve adetleri (lines[].quantity), toplam, teslimat ve fatura adresi içerir |
İmza Doğrulama
İmza, imza anahtarının tamamı (whsec_ dahil) ile "<X-Odeal-Timestamp>.<ham gövde>" metninin HMAC-SHA256 değeridir (hex). Zaman damgasını başlıktan, gövdeyi de JSON olarak çözüp yeniden üretmeden, geldiği gibi kullanın.
import hmac, hashlib
def imza_gecerli_mi(ham_govde: bytes, timestamp: str, imza_basligi: str, secret: str) -> bool:
mesaj = timestamp.encode() + b"." + ham_govde
beklenen = "sha256=" + hmac.new(secret.encode(), mesaj, hashlib.sha256).hexdigest()
return hmac.compare_digest(beklenen, imza_basligi)İmzası geçersiz istekleri reddedin. Webhook'u aldığınızda hızlıca 2xx dönün, işlemeyi sonra yapın. Başarısız teslimatlar yaklaşık 2,5 gün boyunca tekrar denenir.
Mutabakat
Fiziksel/Dijital linkte magaza.external_id verildiyse işlemin harici referansı <external_id>-<oturum-id> olur (ör. SIP-2026-0001-8dc017964bb440488299559bc684f310). Başarısız ve tamamlanmamış denemelerde de doldurulur. Siparişinizi metadata."magaza.external_id" ya da basket_id ile eşleştirin; aynı siparişe ait birden fazla deneme olabileceğini hesaba katın.
İşlem Sorgulama
Webhook'u kaçırdığınızda ya da mutabakat için işlemleri sorgulayabilirsiniz.
curl "$API_URL/api/v1/transactions?payment_link_id={id}&page=1&page_size=20" \
-H "Authorization: Bearer $TOKEN" \
-H "X-External-Merchant-Id: $MERCHANT_NO"| Filtre | Açıklama |
|---|---|
payment_link_id | Linkin id değeri |
basket_id | Linkte verdiğiniz magaza.basket_id |
status | completed, failed, not_completed |
start_date / end_date | Saat dilimiyle tam zaman (2026-11-17T00:00:00+03:00, URL'de + → %2B) |
Cevap sayfalıdır; kayıtlar items dizisindedir:
{
"items": [
{
"id": "9173d292-44b7-445e-93b8-abd4ae2c314c",
"status": "completed",
"amount": 20000,
"currency": "TRY",
"installment_count": 1,
"external_id": "SIP-2026-0001-8dc017964bb440488299559bc684f310",
"basket_id": "SEPET-778",
"masked_card_number": "543081******5470",
"created": "2026-11-17T10:28:18.478+03:00",
"completed_at": "2026-11-17T10:28:32.813+03:00"
}
],
"page": 1,
"total_pages": 1,
"total_count": 1,
"has_previous_page": false,
"has_next_page": false
}Tek işlem: GET /api/v1/transactions/{transaction_id}.
Hata Kodları
Hata cevabı örneği:
{
"status": 422,
"code": "validation_failed",
"title": "Validation failed",
"detail": "Bir veya daha fazla alan geçersiz.",
"errors": [
{ "field": "title", "code": "invalid_value", "message": "'title' boş olmamalı." },
{ "field": "fixed_amount", "code": "invalid_value", "message": "Sabit tutar 0'dan büyük olmalı." }
]
}| Kod | HTTP | Neden |
|---|---|---|
client_unauthorized | 401 | client_id / client_secret hatalı ya da anahtar pasif |
unauthorized | 401 | Token yok ya da süresi dolmuş |
merchant_context_mismatch | 403 | X-External-Merchant-Id değeri API anahtarının üye işyeriyle uyuşmuyor |
resource_not_found | 404 | Link ya da ürün yok veya silinmiş |
PV_PRODUCT_IN_USE_BY_PAYMENT_LINK | 409 | Ürün bir linkte kullanılıyor; önce linki silin |
PV_MAGAZA_DISABLED | 409 | Mağaza özelliği üye işyeri için açık değil |
idempotency_key_in_use | 409 | Aynı Idempotency-Key daha önce farklı bir istek gövdesiyle kullanılmış |
validation_failed | 422 | Alan hatası; ayrıntı errors[] içinde |
PV_INVALID_PRODUCT_IMAGE | 422 | Görsel 2 MB'tan büyük ya da PNG/JPG/WebP değil |
rate_limit_exceeded | 429 | Çok sık token isteği; 60 saniye sonra tekrar deneyin |

