API

İşlemler

Ödeme oluşturulduktan sonra yapılabilen işlemler. Hepsi ödemenin bağlı olduğu POS hesabı üzerinden bankaya iletilir; POS'un desteklemediği işlem açık bir hata döner.

Ön provizyon kapama

POST/v1/payments/{id}/capture

Yalnızca authorized durumundaki ödemeler kapatılır. amount verilmezse tam tutar, verilirse (kuruş) ön provizyon tutarını aşmayan kısmi tutar tahsil edilir.

curl -X POST https://api.paymentgateway.com.tr/v1/payments/pay_01J.../capture \
  -H "Authorization: Bearer pgw_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 12000 }'

İptal

POST/v1/payments/{id}/cancel

Tahsil edilmiş ya da ön provizyonu alınmış ödemeyi bankada geri alır. Bankalar iptali genellikle aynı gün kabul eder; gün sonu kesildikten sonra iade kullanın. Kısmen iade edilmiş ödemeler iptal edilemez.

İade

POST/v1/payments/{id}/refund

captured ya da partially_refunded ödemelerde çalışır. amount verilmezse kalan tüm tutar iade edilir; verilirse iade edilebilir tutarı aşmamalıdır. Puanla yapılmış satışlarda puan iadesi bankada gerçekleşir.

Örnek yanıt (200)

{
  "payment": { "id": "pay_01J...", "status": "partially_refunded", "capturedAmount": 15990, "refundedAmount": 5000 },
  "transaction": { "id": "txn_...", "type": "refund", "amount": 5000, "status": "approved", "rrn": "412345678902" }
}

Banka reddi

Banka işlemi reddederse 422 ve provider_declined (ya da teknik hatada provider_error) döner; error.details içinde güncel payment ve transaction bulunur. Reddedilen iade ödemenin durumunu değiştirmez.

Bankada sorgulama

POST/v1/payments/{id}/query

Ödemeyi POS hesabının bankasında canlı sorgular; kayıtlı durum ile bankadaki durumu birlikte döndürür. Bekleyen (pending) bir ödeme burada kesinleştirilir.

Yanıt

{
  "payment": { "id": "pay_01J...", "status": "captured" },
  "bank": { "found": true, "state": "approved", "amount": 15990, "code": "00", "authCode": "123456", "rrn": "412345678901" }
}

bank.state	Anlamı
`approved`	Bankada onaylı satış var.
`preauth`	Ön provizyon açık, kapanmamış.
`cancelled / refunded / partially_refunded`	Banka tarafında iptal/iade edilmiş.
`declined`	Bankada reddedilmiş kayıt.
`unknown`	`found: false` ise bankada kayıt yok; aksi halde sorgu yapılamadı (teknik hata).

Puan sorgulama

POST/v1/payments/points/inquiry

Kartın puan bakiyesini (Bonus, World, Maximum, …) sorgular; yalnızca puan sorgulamayı belgeleyen sağlayıcılarda çalışır (bkz. sağlayıcı matrisi). accountId verilmezse kart bankasına göre uygun hesap seçilir.

İstek

{ "card": { "number": "4506349043524136", "expMonth": "12", "expYear": "2030", "cvv": "123", "holder": "ALI VELI" }, "currency": "TRY" }

Yanıt

{ "accountId": "acc_...", "providerCode": "garanti", "ok": true, "balances": [{ "name": "BNS", "value": "125.50", "amountMinor": 12550 }], "totalAmount": 12550 }

Hangi durumda hangi işlem?

Ödeme durumu	capture	cancel	refund
`authorized`	✓	✓	—
`captured`	—	✓ (iade yoksa)	✓
`partially_refunded`	—	—	✓ (kalan tutar kadar)
`refunded / cancelled / declined / failed`	—	—	—

Geçersiz durumda işlem denenirse 409 ve invalid_state döner.

← Önceki3D Secure akışı Sonraki →Hazır ödeme sayfası