> ## 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. # Hızlı Başlangıç > Beş dakikada Payven üzerinden ilk test ödemesini başlatın. 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](https://dashboard.payven.com.tr) ü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: ```bash cURL theme={null} 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" }' ``` ```javascript Node.js theme={null} 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(); ``` ```python Python theme={null} 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: ```json theme={null} { "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](/documentation/concepts/authentication#kod-ornekleri-auto-refresh). `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. ```bash cURL theme={null} 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" } }' ``` ```javascript Node.js theme={null} 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); ``` ```python Python theme={null} 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"]) ``` ```csharp C# theme={null} 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(); ``` Başarılı yanıt (`HTTP 200`): ```json theme={null} { "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](/documentation/concepts/errors). **API Referansı'nda Deneme paneli** ile bu isteği tarayıcınızdan canlı olarak deneyebilirsiniz: [POST /payments](/api-reference/sanal-pos). ## 3. İşlemi sorgulayın ```bash theme={null} 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](/sanal-pos/payment-object). ## 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: ```bash theme={null} 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](/sanal-pos/webhooks/signature). Lokal geliştirmede [ngrok](https://ngrok.com) veya [Cloudflare Tunnel](https://www.cloudflare.com/products/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ı](https://dashboard.payven.com.tr/test-cards) Detay: [Test Kartları](/sanal-pos/test/test-cards) ve [Sandbox Ortamı](/sanal-pos/test/sandbox#banka-cagri-modu). ## Sonraki adımlar Tüketici işlemlerinde sorumluluğu bankaya taşıyın. Kart girişini Payven sayfasında yapın; PCI-DSS denetim kapsamınız en küçük forma (SAQ A) iner. Asenkron sonuçları gerçek zamanlı yakalayın; idempotent handler yazın. 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](/resources/support) iletin — log zincirini saniyeler içinde bulabiliriz.