Hızlı Başlangıç

Bu rehber, Payven Sanal POS API’sine yapılan ilk başarılı test ödemesi için gereken minimum adımları gösterir. Tüm örnekler sandbox ortamı içindir; gerçek para işlemi yapılmaz.

Ön koşul: Konsol üzerinde bir tenant’ınız ve client_id / client_secret çiftiniz olmalıdır. Onboarding için satış ekibimize ulaşın.

1. Access token alın

Payven Identity servisinden OAuth 2.0 client_credentials akışıyla token alın. URL’deki payven yerine onboarding sırasında size verilen tenant slug’ı kullanın:

curl https://identity-sandbox.payven.com.tr/api/v1/auth/payven/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":     "pvk_test_xxxxxxxxxxxxxxxxxxxx",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

const tokenRes = await fetch(
  "https://identity-sandbox.payven.com.tr/api/v1/auth/payven/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: process.env.PAYVEN_CLIENT_ID,
      client_secret: process.env.PAYVEN_CLIENT_SECRET,
    }),
  },
);
const { access_token } = await tokenRes.json();

import httpx, os

token_res = httpx.post(
    "https://identity-sandbox.payven.com.tr/api/v1/auth/payven/token",
    json={
        "client_id":     os.environ["PAYVEN_CLIENT_ID"],
        "client_secret": os.environ["PAYVEN_CLIENT_SECRET"],
    },
)
access_token = token_res.json()["access_token"]

Yanıt:

{
  "access_token":       "eyJhbGciOiJSUzI1NiI...",
  "refresh_token":      "eyJhbGciOiJIUzI1NiI...",
  "expires_in":         300,
  "refresh_expires_in": 0,
  "token_type":         "Bearer",
  "scope":              "openid profile email"
}

Access token 5 dakika geçerlidir. Production’da bunu cache’leyip auto-refresh ile yönetin — Node, Python, C#, Go ve PHP için hazır implementasyonlar: Kimlik Doğrulama → Kod örnekleri.

client_secret değerini hiçbir zaman istemci tarafı (tarayıcı, mobil uygulama, public repo) koduna gömmeyin. Tüm Payven API çağrıları yalnızca sunucu tarafından yapılmalıdır.

2. İlk ödemeyi gerçekleştirin

Aşağıdaki örnek, sandbox’ta bir Non-3D test ödemesi başlatır. Tutar kuruş cinsindendir. 15000 değeri 150,00 ₺‘dir.

curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: order-1001-payment" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id":    "ORDER-1001",
    "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"
    }
  }'

const res = await fetch(
  "https://vpos-sandbox.payven.com.tr/api/v1/payments",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Idempotency-Key": "order-1001-payment",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_id: "ORDER-1001",
      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",
      },
    }),
  },
);
const payment = await res.json();
console.log(payment.transaction_id, payment.status);

res = httpx.post(
    "https://vpos-sandbox.payven.com.tr/api/v1/payments",
    headers={
        "Authorization":   f"Bearer {access_token}",
        "Idempotency-Key": "order-1001-payment",
    },
    json={
        "external_id":    "ORDER-1001",
        "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",
        },
    },
)
payment = res.json()
print(payment["transaction_id"], payment["status"])

var payload = new
{
    external_id    = "ORDER-1001",
    amount         = new { amount = 15000L, currency = "TRY" },
    installment    = 1,
    operation_type = "sale",
    card = new
    {
        holder_name  = "Test Kullanici",
        number       = "4546711234567894",
        expire_month = "12",
        expire_year  = "2030",
        cvv          = "000"
    }
};

var request = new HttpRequestMessage(HttpMethod.Post,
    "https://vpos-sandbox.payven.com.tr/api/v1/payments")
{
    Content = JsonContent.Create(payload)
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
request.Headers.Add("Idempotency-Key", "order-1001-payment");

var response = await http.SendAsync(request);
var payment  = await response.Content.ReadFromJsonAsync<Payment>();

Başarılı yanıt (HTTP 200):

{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status":         "completed",
  "extra_properties": {
    "processed_at":            "2026-05-03T12:34:58.123+00:00",
    "auth_code":               "123456",
    "host_reference":          "PAYVEN-REF-789",
    "provider_transaction_id": "9f3d2b8e-..."
  }
}

HTTP 200 + status: "completed" → ödeme başarıyla tamamlandı. transaction_id değerini saklayın — sonraki adımlarda iade, sorgulama veya webhook eşleştirmesinde kullanacaksınız. Hata durumunda yanıt application/problem+json formatında döner (RFC 9457). Detaylar: Hata Yönetimi.

API Referansı’nda Deneme paneli ile bu isteği tarayıcınızdan canlı olarak deneyebilirsiniz: POST /payments.

3. İşlemi sorgulayın

curl https://vpos-sandbox.payven.com.tr/api/v1/payments/8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6 \
  -H "Authorization: Bearer $TOKEN"

Detaylı yanıt yapısı: Payment Objesi.

4. Webhook ile asenkron yakalayın

Tarayıcı tabanlı akışlarda (3DS, hosted checkout) müşteri tarayıcıyı kapatabilir — sonucu kaçırmamak için webhook kurun:

curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://your-domain.com/webhooks/payven",
    "events": ["payment.completed", "payment.failed", "refund.completed"]
  }'

Webhook isteklerini doğrularken HMAC-SHA256 imzasını kontrol edin — bkz. İmza Doğrulama. Lokal geliştirmede ngrok veya Cloudflare Tunnel ile localhost’unuzu internete açabilirsiniz.

Test kart numaraları

Sandbox test kartları organizasyonunuzun aktif konnektör konfigürasyonuna göre değişir (mock konnektör vs banka test ortamı). Güncel listeye konsoldan erişebilirsiniz: → Konsol → Test Kartları Detay: Test Kartları ve Sandbox Ortamı.

Sonraki adımlar

3D Secure ile chargeback'i azalt

Tüketici işlemlerinde sorumluluğu bankaya taşıyın.

Hosted Checkout ile PCI yükünü düşür

Kart girişini Payven sayfasında yapın; PCI-DSS denetim kapsamınız en küçük forma (SAQ A) iner.

Webhook entegrasyonu

Asenkron sonuçları gerçek zamanlı yakalayın; idempotent handler yazın.

İade ve iptal

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

Yardım

Bir adımda takılırsanız: response header’ındaki X-Correlation-Id değerini (veya hata yanıtlarında response body’sindeki correlation_id alanını) destek ekibine iletin — log zincirini saniyeler içinde bulabiliriz.

Tanışın

Temel Kavramlar

Güvenlik

Geçiş Rehberi

Reçeteler

1. Access token alın

2. İlk ödemeyi gerçekleştirin

3. İşlemi sorgulayın

4. Webhook ile asenkron yakalayın

Test kart numaraları

Sonraki adımlar

3D Secure ile chargeback'i azalt

Hosted Checkout ile PCI yükünü düşür

Webhook entegrasyonu

İade ve iptal

Yardım

​1. Access token alın

​2. İlk ödemeyi gerçekleştirin

​3. İşlemi sorgulayın

​4. Webhook ile asenkron yakalayın

​Test kart numaraları

​Sonraki adımlar

3D Secure ile chargeback'i azalt

Hosted Checkout ile PCI yükünü düşür

Webhook entegrasyonu

İade ve iptal

​Yardım

1. Access token alın

2. İlk ödemeyi gerçekleştirin

3. İşlemi sorgulayın

4. Webhook ile asenkron yakalayın

Test kart numaraları

Sonraki adımlar

Yardım