API

Ödeme oluşturma

Tek uç nokta; satış, ön provizyon, 3D'li/3D'siz ve puanlı ödemelerin hepsini başlatır. Hangi POS'un kullanılacağına yönlendirme motoru karar verir.

POST/v1/paymentsIdempotency-Key desteklenir

curl https://api.paymentgateway.com.tr/v1/payments \
  -H "Authorization: Bearer pgw_test_xxxxxxxx" \
  -H "Idempotency-Key: siparis-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15990,
    "currency": "TRY",
    "installment": 3,
    "card": {
      "number": "4111111111111111",
      "expMonth": "12",
      "expYear": "2030",
      "cvv": "123",
      "holder": "ALI VELI"
    },
    "merchantOrderId": "1001",
    "description": "Siparis #1001",
    "customer": { "email": "ali@example.com", "ip": "203.0.113.7" },
    "returnUrl": "https://magaza.example/odeme/sonuc"
  }'

İstek alanları

Alan	Tür	Açıklama
`amount`	integer	Zorunlu. Kuruş cinsinden tutar (`15990` = 159,90). Sıfırdan büyük olmalı.
`currency`	string	`TRY` (varsayılan), `USD`, `EUR`, `GBP`.
`installment`	integer	1–12. Varsayılan 1 (tek çekim). Seçilen POS hesabında o taksit açık olmalı.
`kind`	string	`sale` (varsayılan) ya da `preauth` (ön provizyon; sonradan kapatılır).
`secure`	boolean	Varsayılan `true` (3D Secure). `false` ise 3D'siz (nonsecure) satış; hesabınızın politikası buna izin vermelidir.
`card`	object	`number`, `expMonth` (01–12), `expYear` (2 veya 4 hane), `cvv`, `holder`. Luhn ve son kullanma tarihi doğrulanır.
`merchantOrderId`	string	Sizin sipariş numaranız (en fazla 64 karakter). Listelemede aranabilir.
`description`	string	Serbest açıklama.
`customer`	object	`email`, `name`, `phone`, `ip`. Müşteri IP'sini iletmeniz önerilir (bazı bankalar zorunlu tutar); verilmezse istek yapan IP kullanılır.
`returnUrl`	string	3D sonrası müşterinin döneceği https adresi (test modunda http de olur).
`points`	object	`{ amount }`: kuruş karşılığı puan kullanımı. Yalnızca puan satışı destekleyen sağlayıcılarda.
`metadata`	object	Ödemeye iliştirilen serbest JSON; webhook ve yanıtlarda geri döner.
`accountId`	string	Verilirse yönlendirme atlanır ve doğrudan bu POS hesabı kullanılır.

Yanıt

Başarılı oluşturma 201 döner; ödemenin durumu status alanındadır.

Tahsil edilmiş ödeme (3D'siz)

{
  "id": "pay_01J8X...",
  "object": "payment",
  "mode": "test",
  "status": "captured",
  "kind": "sale",
  "amount": 15990,
  "currency": "TRY",
  "installment": 3,
  "capturedAmount": 15990,
  "refundedAmount": 0,
  "secure": false,
  "merchantOrderId": "1001",
  "provider": { "code": "garanti", "accountId": "acc_..." },
  "authCode": "123456",
  "rrn": "412345678901",
  "card": { "bin": "411111", "last4": "1111", "brand": "visa", "type": "credit", "issuer": "garanti", "origin": "domestic" },
  "commission": { "rate": 2.49, "amount": 398, "net": 15592 },
  "createdAt": "2026-03-02T09:14:22Z",
  "completedAt": "2026-03-02T09:14:23Z"
}

HTTP	Durum	Anlamı
201	`captured / authorized / requires_action / pending`	Ödeme oluşturuldu; durum alanına bakın.
402	`declined / failed`	Banka reddetti veya uygun POS bulunamadı. `error` alanı nedeni içerir.
422	`validation_failed`	Alan doğrulaması: `error.details` alan → mesaj haritasıdır.

Yanıtı belirsiz kalan ödemeler

Bankadan yanıt alınamazsa (zaman aşımı gibi) ödeme pending kalır ve başka bir POS'a asla yönlendirilmez: sistem önce bankada ödemeyi sorgular; sonuç bulunursa kesinleştirir, bulunamazsa reddedilmiş sayar. Kesinleşene kadar webhook'u bekleyin ya da sorgu ucunu kullanın. Aynı siparişi kendiniz yeniden göndermeyin — Idempotency-Key kullanın.

Ödemeleri listeleme ve okuma

GET/v1/payments/{id}ödeme + denemeler + işlem hareketleri

GET/v1/paymentsfiltreli liste

Sorgu parametresi	Açıklama
`status`	captured, declined, refunded ...
`provider`	Sağlayıcı kodu (ör. garanti)
`issuer`	Kartı çıkaran banka anahtarı
`q`	Sipariş no, ödeme no, son 4 hane vb. arama
`from`	`to`: `YYYY-MM-DD` ya da RFC3339; `to` tarih ise gün sonu dahildir
`minAmount`	`maxAmount` (kuruş)
`limit`	`offset` ile sayfalama. Yanıt: `{ data: [...], total }`

Ödeme detayında her POS denemesi (attempts) ve her banka hareketi (transactions) görünür; failover ve mutabakat kararlarını buradan izleyebilirsiniz.

← ÖncekiKimlik doğrulama Sonraki →3D Secure akışı