Skip to main content
Non-3D ödeme en basit ödeme akışıdır. Tek bir API isteğiyle ödeme tamamlanır — kart bilgileri Payven’e iletilir, akıllı yönlendirme motoru uygun bankayı seçer, banka onayı alınır ve sonuç dönülür.
Risk: Non-3D işlemlerde kart sahibi doğrulaması yapılmadığı için chargeback (ters ibraz) sorumluluğu sizdedir. Tüketici ödemelerinde 3D Secure önerilir. Non-3D, kapalı devre B2B akışları, abonelik yenilemeleri (CIT/MIT) veya düşük risk segmentleri için uygundur.

​
Endpoint

POST /api/v1/payments

​
Akış

​
İstek

curl -X POST https://vpos.payven.com.tr/api/v1/payments \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: order-1001-payment" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id":    "ORDER-1001",
    "basket_id":      "BASKET-2026-001",
    "amount":         { "amount": 15000, "currency": "TRY" },
    "installment":    1,
    "operation_type": "sale",
    "card": {
      "holder_name":  "Test Kullanici",
      "number":       "4546711234567894",
      "expire_month": "12",
      "expire_year":  "2030",
      "cvv":          "000"
    },
    "buyer": {
      "id":         "cust-001",
      "name":       "Test",
      "surname":    "Kullanici",
      "email":      "musteri@example.com",
      "phone":      "+905551112233",
      "ip_address": "85.105.10.10"
    },
    "billing_address": {
      "contact_name": "Test Kullanici",
      "city":         "Istanbul",
      "country":      "TR",
      "address":      "Maslak Mh. ...",
      "postal_code":  "34485"
    },
    "description": "Sipariş ödemesi"
  }'

const response = await fetch("https://vpos.payven.com.tr/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Idempotency-Key": `order-${order.id}-payment`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: order.id,
    amount: { amount: 15000, currency: "TRY" },
    installment: 1,
    operation_type: "sale",
    card: {
      holder_name:  "Test Kullanici",
      number:       "4546711234567894",
      expire_month: "12",
      expire_year:  "2030",
      cvv:          "000",
    },
    buyer: {
      id:         order.customerId,
      email:      order.email,
      ip_address: req.ip,
    },
  }),
});
const result = await response.json();

​
İstek alanları

AlanTipZorunlulukAçıklama
external_idstringÖnerilirSizin sisteminizdeki sipariş kimliği. İdeal olarak Idempotency-Key ile aynı seed’den üretin.
basket_idstringOpsiyonelSepet kimliği (raporlama için)
amount.amountint (kuruş)ZorunluTutar — kuruş cinsinden tam sayı
amount.currencyenumZorunluŞu an yalnız "TRY" kabul edilir. Yabancı kart için DCC akışında çevrim yanıtta döner — bkz. Tutarlar
installmentintZorunluTaksit sayısı (1 = peşin). Banka & BIN desteği gerekir.
operation_typeenumOpsiyonelsale (varsayılan, anında çekim) veya pre_auth (ön provizyon — sonradan /capture gerekir)
card.holder_namestringZorunluKart üzerindeki isim
card.numberstringZorunlu13-19 haneli kart numarası (boşluksuz, Luhn checksum geçerli)
card.expire_monthstringZorunluİki hane (01–12)
card.expire_yearstringZorunluDört hane (2030)
card.cvvstringZorunlu3 hane (Amex için 4)
buyer.idstringÖnerilirMüşteri kimliğiniz (fraud sinyalleri için)
buyer.name, surname, email, phonestringÖnerilirMüşteri bilgileri (banka risk skoru için)
buyer.ip_addressstringÖnerilirMüşterinin IP adresi (fraud için kritik)
buyer.identity_numberstringOpsiyonelTC kimlik no (yüksek tutarlı işlemlerde bazı bankalar zorunlu kılar)
billing_address, shipping_addressobjectOpsiyonelAdres alanları — bazı bankalar/3DS senaryoları için risk skoruna girer
basket_items[]arrayOpsiyonelSepet kalemleri (name, price, quantity)
descriptionstringOpsiyonelİşlem açıklaması (banka ekstresi açıklamasına yansıyabilir)
extra_propertiesobjectOpsiyonelKonnektör-spesifik özel alanlar (advanced)
İlgili headers — bu istek için zorunlu olanlar:
  • Authorization: Bearer <token> (Identity’den alınan access token)
  • Idempotency-Key (önerilir — yeniden gönderim koruması için bkz. Idempotency)
  • Content-Type: application/json

​
Başarılı response

HTTP/1.1 200 OK
Content-Type: application/json
X-Correlation-Id: 9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8

{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status":         "completed",
  "extra_properties": {
    "processed_at":            "2026-05-03T12:34:58.123+00:00",
    "receipt_id":              "RCPT-20260503-0001",
    "external_id":             "ORDER-1001",
    "provider_transaction_id": "9f3d2b8e-...",
    "auth_code":               "123456",
    "host_reference":          "PAYVEN-REF-789"
  }
}
HTTP 200 + status: "completed" → ödeme başarıyla tamamlandı. Detaylı alan referansı: Payment Objesi.

​
Banka tarafından red

Banka reddinde response 422 Unprocessable Entity + application/problem+json döner; code: "bank_declined" ile birlikte bankanın orijinal kodu provider_error_code alanında taşınır. Tam payload yapısı: Hata Yönetimi. Banka kodları: Banka Yanıt Kodları. Sonradan GET /api/v1/payments/{id} ile sorgulandığında failed ödeme 200 OK döner; error_code ve provider_error_code response body’sinde yer alır.

​
Validasyon hatası

Eksik veya geçersiz alanlar 422 Unprocessable Entity ile RFC 9457 problem+json döner: 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type":   "https://docs.payven.com.tr/errors/validation_failed",
  "title":  "Validasyon hatası",
  "status": 422,
  "code":   "validation_failed",
  "detail": "1 alan geçersiz",
  "errors": [
    { "field": "card.number", "code": "invalid_card", "message": "Kart numarası Luhn checksum'ı geçmiyor." }
  ]
}
Detay: Hata Yönetimi.

​
Sonraki adımlar

3D Secure'a geçin

Tüketici işlemlerinde chargeback riskini azaltın.

İade işlemi

Tam veya kısmi iade nasıl yapılır?

Webhook entegre edin

Asenkron sonuçları gerçek zamanlı alın.

Akıllı yönlendirme

Birden fazla bankaya nasıl yönlendirilir?