API

Kart saklama ve tekrarlayan ödeme

Müşterinizin kartını ilk ödemede güvenle kaydedin; sonraki ödemelerde yalnızca kart kimliğini gönderin ya da belirli aralıklarla otomatik tahsil eden bir plan kurun.

Nasıl çalışır?

Kart numarası AES-256-GCM ile şifrelenerek saklanır; CVV hiçbir zaman saklanmaz. API ve panel yalnızca BIN, son 4 hane ve son kullanma tarihini gösterir.
Kart her zaman sizin hesabınıza, bir ortama (test/canlı) ve sizin verdiğiniz müşteri kimliğine (customerRef) bağlıdır. Başka hesap veya ortamda kullanılamaz.
Ödemeyle kaydedilen kart, ödeme onaylanınca etkinleşir; reddedilen ödemenin kartı kaydedilmez. Aynı müşteri için aynı kart tekrar kaydedilirse mevcut kayıt döner.

Müşteri onayı sizin sorumluluğunuzdadır

Kart saklamadan önce müşterinizden açık onay alın ve hangi durumlarda otomatik çekim yapacağınızı bildirin. Hazır ödeme sayfası, saveCard seçiliyken müşteriye kart kaydını ayrıca gösterir.

1. Ödemeyle kartı kaydetme

POST /v1/payments isteğine saveCard ve customerRef ekleyin. Ödeme 3D Secure ile yapılabilir; kart, 3D doğrulaması ve tahsilat tamamlanınca kaydedilir. Yanıttaki cardId alanını saklayın.

İstek

{
  "amount": 14990,
  "card": { "number": "4242424242424242", "expMonth": "12", "expYear": "2030", "cvv": "123" },
  "saveCard": true,
  "customerRef": "musteri-1042"
}

Kart bilgisini hiç almak istemiyorsanız hazır ödeme sayfası oturumunda "saveCard": true, "customerRef": "..." gönderin. Panelde Ödeme Linkleri ekranında da "Kartı kaydet" seçeneği vardır.

2. Kayıtlı kartla ödeme

card yerine cardId gönderin. CVV isteğe bağlıdır. Müşteri oturumdaysa 3D Secure (varsayılan) kullanın.

İstek

{ "amount": 9990, "cardId": "card_01J..." }

Kart uçları

Uç	Açıklama
`POST /v1/cards`	Ödemesiz kart kaydı: card + customerRef. Kart ilk tahsilatta doğrulanır; mümkünse ödemeyle kaydetmeyi tercih edin.
`GET /v1/cards?customerRef=`	Müşterinin kayıtlı kartları.
`GET /v1/cards/{id}`	Kart özeti (numara içermez).
`DELETE /v1/cards/{id}`	Kartı siler; şifreli numara kalıcı olarak temizlenir.

3. Tekrarlayan ödeme planı

Plan kurduğunuzda tahsilatları biz yaparız: vadesi gelen dönemde kayıtlı karttan 3D Secure'suz (üye işyeri başlatımlı) çekim yapılır, sonuç webhook ile bildirilir.

POST/v1/recurring

Aylık plan

curl https://api.paymentgateway.com.tr/v1/recurring \
  -H "Authorization: Bearer pgw_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "card_01J...",
    "amount": 14990,
    "description": "Pro üyelik",
    "interval": "month",
    "intervalCount": 1,
    "startAt": "2026-10-01T09:00:00+03:00",
    "maxRuns": 12,
    "maxRetries": 3,
    "retryHours": 24
  }'

Alan	Açıklama
`interval, intervalCount`	day \| week \| month \| year ve çarpanı (ör. 3 + month = üç ayda bir). Aylık planlarda gün korunur; 31'inde başlayan plan kısa aylarda ayın son günü çekilir.
`startAt`	İlk tahsilat zamanı; boşsa hemen (1 dakika içinde).
`maxRuns`	Toplam tahsilat sayısı; boşsa iptal edilene kadar sürer. Ulaşıldığında plan completed olur.
`maxRetries, retryHours`	Başarısız dönemde yeniden deneme sayısı ve aralığı (varsayılan 3 kez, 24 saat). Bitince plan past_due olur.

Uç	Açıklama
`GET /v1/recurring`	Liste (?status=, customerRef=, cardId=).
`GET /v1/recurring/{id}`	Plan, kart ve son denemeler (runs).
`PATCH /v1/recurring/{id}`	Tutar, açıklama, kart (cardId) veya maxRuns güncelle; sonraki tahsilattan geçerli.
`POST /v1/recurring/{id}/pause`	Duraklat.
`POST /v1/recurring/{id}/resume`	Sürdür; past_due plan hemen yeniden denenir.
`POST /v1/recurring/{id}/cancel`	Kalıcı iptal.

Çifte çekim olmaz

Her deneme kendine özgü bir idempotency anahtarıyla yapılır. Sonucu belirsiz kalan (zaman aşımı) tahsilat yeniden çekilmez; mutabakatla kesinleşmesi beklenir.

Webhook olayları

recurring.payment_succeeded, recurring.payment_failed, recurring.past_due ve recurring.completed olaylarında data planı, paymentId ve varsa error alanını içerir. Tahsilatın kendisi için ayrıca payment.captured / payment.failed olayları da gönderilir (metadata.recurringId ile).

← ÖncekiHazır ödeme sayfası Sonraki →Webhook'lar