Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt

Use this file to discover all available pages before exploring further.

Bu rehber, Payven Sanal POS API’sine yapılan ilk başarılı ödeme için gereken minimum adımları gösterir. Tüm kod örnekleri test ortamı içindir.
Ön koşul: Konsol üzerinden bir hesabınız ve aktif bir merchant tanımınız olmalıdır.

​
1. API anahtarı oluşturun

Konsola giriş yaptıktan sonra Ayarlar → API Anahtarları → Yeni Anahtar Oluştur adımıyla bir anahtar üretin. Üretilen değerleri güvenli bir yerde saklayın:
BilgiAçıklama
apiKeyPublic tanımlayıcı (pvk- ile başlar).
apiSecretGizli imza anahtarı. Yalnızca oluşturma anında bir kez gösterilir.
merchantIdÖdemeyi gerçekleştirecek merchant’ın kimliği.
apiSecret değerini hiçbir zaman istemci tarafı (tarayıcı, mobil uygulama) kodlarına gömmeyin. Tüm Payven API çağrıları yalnızca sunucu tarafından yapılmalıdır.

​
2. İlk isteğinizi atın

Aşağıdaki örnek, Non-3D bir test ödemesi başlatır. Tutar kuruş cinsindendir — 15000 değeri 150,00 ₺‘ye karşılık gelir. 
curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/payments \
  -H "X-API-Key: pvk-test-XXXX" \
  -H "X-API-Secret: YOUR_SECRET" \
  -H "X-Merchant-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ORDER-1001",
    "amount": 15000,
    "currency": "TRY",
    "installment": 1,
    "card": {
      "holderName": "Test Kullanici",
      "number": "4546711234567894",
      "expireMonth": "12",
      "expireYear": "2030",
      "cvv": "000"
    }
  }'

​
3. Yanıtı yorumlayın

Başarılı bir Non-3D ödemenin yanıtı şu yapıdadır: 
{
  "isSuccess": true,
  "message": "Başarılı.",
  "code": "200",
  "data": {
    "id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
    "externalId": "ORDER-1001",
    "status": "Success",
    "amount": 15000,
    "currency": "TRY",
    "installment": 1,
    "authCode": "123456",
    "hostReference": "PAYVEN-REF-789",
    "connector": {
      "code": "GarantiVPOS",
      "responseCode": "00",
      "responseMessage": "Onaylandı"
    },
    "createdAt": "2026-05-03T12:34:56Z"
  }
}
İstediğiniz alanın anlamı için API Yanıt Formatı sayfasına bakın.

​
4. Webhook ile sonucu doğrulayın

Asenkron işlem sonuçlarını (3D Secure, capture, iade, mutabakat olayları) yakalamak için bir webhook endpoint’i kaydedin. Detay: Webhook Genel Bakış. 
curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/webhooks \
  -H "X-API-Key: pvk-test-XXXX" \
  -H "X-API-Secret: YOUR_SECRET" \
  -H "X-Merchant-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/payven",
    "events": ["payment.succeeded", "payment.failed", "refund.succeeded"]
  }'
Yanıttaki secret değerini saklayın — bu değerle gelen webhook isteklerinin imzasını doğrulayacaksınız.

​
Sonraki adımlar

3D Secure ödeme

Müşteriyi banka doğrulama sayfasına yönlendiren tam akış.

Test kartları

Sandbox ortamında kullanılabilir tüm test kartlarının listesi.

Hata yönetimi

Hata kodları, retry stratejisi ve idempotency kullanımı.

Production geçişi

Canlıya geçmeden önce tamamlanması gereken kontrol listesi.