İçeriğe geç
Paytalya Paytalya Gateway

Hızlı Başlangıç

Bu rehber, ilk ödemenizi oluşturmaktan sonucu doğrulamaya kadar olan akışı gösterir. Önce bir API anahtarınız ve size tanımlı bir terminalId olduğundan emin olun.

1. Ödeme isteği oluşturma

Bölüm başlığı “1. Ödeme isteği oluşturma”

Sunucunuzdan POST /v1/payments çağırın. Bu istek yalnızca tutarı, terminali ve returnUrl’ü gönderir; gövdesi kart içermez. Tutarı kuruş cinsinden tamsayı olarak verin (1.250,50 TL → 125050).

Terminal window
curl -X POST https://gateway.paytalya.com/v1/payments \
  -H "Authorization: Bearer ptk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 125050,
    "partnerTxCode": "ORD-2026-8841",
    "terminalId": "trm_3Kd9x",
    "installment": 1,
    "description": "Sipariş #8841",
    "returnUrl": "https://magazan.example/odeme/sonuc"
  }'

Yanıt (201 Created) kart/banka 3D form verisi içermez; bir paymentRef ve bir handoffUrl döner:

{
  "paymentCode": "pay_7Hq2bL",
  "status": "initiated",
  "paymentRef": "pr_3Kd9xQ1w2E",
  "handoffUrl": "https://pay.paytalya.example/checkout"
}

2. Alıcıyı handoff sayfasına yönlendirme

Bölüm başlığı “2. Alıcıyı handoff sayfasına yönlendirme”

Kendi checkout’unuzda topladığınız kartı ve paymentRef’i, alıcının tarayıcısından handoffUrl’e form-POST ile gönderirsiniz (mobilde bir WebView ile). Handoff sayfası banka 3D devrini kendisi yürütür; banka 3D formunu siz kurmazsınız. Web ve mobil örnekleri: Kart Handoff.

3D tamamlandıktan sonra handoff sayfası alıcıyı 303 ile returnUrl’ine yönlendirir. returnUrl ile taşınan veriler istemci (tarayıcı) üzerinden geldiği için nihai/güvenilir sonuç olarak kabul edilmemelidir; ödemeyi tamamlanmış saymadan önce kesin sonucu sunucu tarafında (webhook ya da sorgulama endpoint’i) doğrulamanız gerekir.

3. Sonucu öğrenme

Bölüm başlığı “3. Sonucu öğrenme”

İki yol var; ikisi de aynı sonuca götürür, ama webhook anlıktır:

Webhook (önerilen): Durum değiştiğinde Paytalya sizin uç noktanıza bir bildirim gönderir. Bkz. Webhooks.

{
  "id": "whd_a1b2c3",
  "type": "payment.captured",
  "paymentCode": "pay_7Hq2bL",
  "occurredAt": "2026-06-14T12:05:11Z"
}

Sorgu (doğrulama): Webhook bildirimi geldiğinde ya da returnUrl dönüşünde, kesin durumu sorgulayın:

Terminal window
curl https://gateway.paytalya.com/v1/payments/pay_7Hq2bL \
  -H "Authorization: Bearer ptk_live_xxxxxxxxxxxxxxxxxxxx"

Sonraki adımlar

Bölüm başlığı “Sonraki adımlar”