> ## 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. # Pay-by-link oluştur > Kart bilgisi almadan, müşteriye SMS / e-posta / WhatsApp ile paylaşılabilen bir ödeme linki üretir. Müşteri Payven Hosted Checkout sayfasında kart bilgisini girer (PCI-DSS SAQ A kapsamına uygun). Sonuç webhook ile gelir: `payment.completed` / `payment.failed`. ## OpenAPI ````yaml /api-reference/sanal-pos/openapi.json post /api/v1/payments/order-link openapi: 3.0.4 info: title: Payven Sanal POS API description: >- Payven Sanal POS — çoklu banka kart ödemeleri, 3D Secure, akıllı yönlendirme, mutabakat ve webhook altyapısı. termsOfService: https://payven.com.tr/sozlesmeler contact: name: Payven Developer Support url: https://docs.payven.com.tr email: destek@payven.com.tr license: name: Payven API License url: https://payven.com.tr/sozlesmeler/api-lisansi version: '1.0' servers: - url: https://vpos-sandbox.payven.com.tr description: Sandbox - url: https://vpos.payven.com.tr description: Production security: - bearerAuth: [] tags: - name: ApiRequestLogs x-displayName: API İstek Kayıtları - name: CancellationRequests x-displayName: İptal Talepleri - name: Chargebacks x-displayName: Chargeback - name: CheckoutSessions x-displayName: Hosted Checkout - name: ConnectorConfigurations x-displayName: Konnektör Konfigürasyonları - name: ConnectorErrorCodes x-displayName: Konnektör Hata Kodları - name: Connectors x-displayName: Konnektörler - name: Dashboard x-displayName: Dashboard - name: Health x-displayName: Sağlık - name: MerchantBankProfiles x-displayName: Bayi Banka Profilleri - name: Payments x-displayName: Ödemeler - name: Reconciliations x-displayName: Mutabakat - name: Refunds x-displayName: İadeler - name: RoutingRules x-displayName: Yönlendirme Kuralları - name: Settings x-displayName: Ayarlar - name: Settlements x-displayName: Settlement - name: SimpleRoutingRules x-displayName: Basit Yönlendirme Kuralları - name: TestCards x-displayName: Test Kartları - name: Trace x-displayName: Trace - name: Transactions x-displayName: İşlemler - name: Webhooks x-displayName: Webhook'lar paths: /api/v1/payments/order-link: post: tags: - Payments summary: Pay-by-link oluştur description: >- Kart bilgisi almadan, müşteriye SMS / e-posta / WhatsApp ile paylaşılabilen bir ödeme linki üretir. Müşteri Payven Hosted Checkout sayfasında kart bilgisini girer (PCI-DSS SAQ A kapsamına uygun). Sonuç webhook ile gelir: `payment.completed` / `payment.failed`. operationId: createOrderLink requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateOrderLinkRequest' responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/PaymentOperationResultDto' - $ref: '#/components/schemas/PaymentStatusDto' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' x-codeSamples: - lang: curl label: cURL source: >- curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/payments/order-link \ -H "Authorization: Bearer $PAYVEN_TOKEN" \ -H "Idempotency-Key: order-1001" \ -d '{ ...payload... }' - lang: javascript label: Node.js source: |- const res = await fetch( "https://vpos-sandbox.payven.com.tr/api/v1/payments/order-link", { method: "POST", headers: { Authorization: `Bearer ${accessToken}`, "Idempotency-Key": "order-1001", "Content-Type": "application/json", }, body: JSON.stringify({ /* payload */ }), }, ); const data = await res.json(); - lang: python label: Python source: |- import httpx res = httpx.post( "https://vpos-sandbox.payven.com.tr/api/v1/payments/order-link", headers={ "Authorization": f"Bearer {access_token}", "Idempotency-Key": "order-1001", }, json={ ... }, ) data = res.json() - lang: csharp label: C# source: >- var req = new HttpRequestMessage(HttpMethod.Post, "https://vpos-sandbox.payven.com.tr/api/v1/payments/order-link"); req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken); req.Headers.Add("Idempotency-Key", "order-1001"); // Content = JsonContent.Create(payload); var resp = await http.SendAsync(req); - lang: go label: Go source: >- req, _ := http.NewRequest("POST", "https://vpos-sandbox.payven.com.tr/api/v1/payments/order-link", nil) req.Header.Set("Authorization", "Bearer "+accessToken) req.Header.Set("Idempotency-Key", "order-1001") // req.Body = bytes.NewReader(payloadJSON) resp, _ := http.DefaultClient.Do(req) - lang: php label: PHP source: >- $ch = curl_init("https://vpos-sandbox.payven.com.tr/api/v1/payments/order-link"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer $accessToken", "Idempotency-Key: order-1001", ], CURLOPT_POSTFIELDS => json_encode(\$payload), ]); $data = json_decode(curl_exec($ch), true); components: schemas: CreateOrderLinkRequest: type: object properties: amount: type: integer format: int64 description: Tutar — kuruş cinsinden. example: 15000 currency: type: string nullable: true description: ISO 4217 para birimi. example: TRY installment: type: integer format: int32 description: İzin verilen maksimum taksit. example: 6 callback_url: type: string nullable: true description: Ödeme tamamlandığında server-to-server callback için HTTPS URL'iniz. return_url: type: string nullable: true description: Müşterinin ödeme sonrası yönlendirileceği sayfa. description: type: string nullable: true description: Linkte gösterilecek açıklama. example: 'Sipariş #1001' external_id: type: string nullable: true description: Sizin sipariş kimliğiniz. example: ORDER-1001 customer_email: type: string nullable: true description: Müşteri e-postası. example: musteri@example.com customer_phone: type: string nullable: true extra_properties: type: object additionalProperties: type: string nullable: true additionalProperties: false description: >- Pay-by-link oluşturma isteği. SMS/e-posta ile paylaşılan ödeme linki üretir. required: - amount - currency PaymentOperationResultDto: type: object properties: transaction_id: type: string format: uuid description: >- Payven tarafından atanan benzersiz işlem kimliği. Sorgulama / aksiyon endpoint'lerinde URL parametresi olarak kullanılır. example: 8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6 status: type: string nullable: true description: >- İşlemin mevcut durumu: `pending`, `pending_3ds`, `authorized`, `completed`, `failed`, `voided`, `refunded`, `partially_refunded`. example: completed is_success: type: boolean description: >- Operasyon başarılı mı? **Geçiş döneminde tutuluyor — yeni kodlarda HTTP status kodunu konuşturun** (2xx başarı, 4xx/5xx hata). example: true message: type: string nullable: true description: İnsan-okur durum mesajı. example: İşlem başarıyla tamamlandı error_code: type: string nullable: true description: Yalnızca başarısız işlemlerde dolar — Payven canonical hata kodu. example: bank_declined provider_error_code: type: string nullable: true description: Yalnızca başarısız işlemlerde dolar — bankanın orijinal yanıt kodu. example: '51' extra_properties: type: object additionalProperties: type: string nullable: true description: >- Banka-spesifik ek alanlar: `auth_code`, `host_reference`, `provider_transaction_id`, `processed_at` vb. additionalProperties: false description: >- Yazma operasyonlarından (`POST /payments`, `/refund`, `/void`, `/capture`) dönen sonuç. required: - transaction_id PaymentStatusDto: allOf: - $ref: '#/components/schemas/PaymentOperationResultDto' - type: object properties: amount: type: integer format: int64 currency: type: string nullable: true is3_d_secure: type: boolean created: type: string format: date-time basket_id: type: string nullable: true additionalProperties: false ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} responses: BadRequest: description: Geçersiz istek (eksik alan, bozuk JSON). content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.payven.com.tr/errors/bad_request title: Geçersiz istek status: 400 code: bad_request detail: amount.amount alanı zorunlu. correlation_id: 9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8 Unauthorized: description: '`Authorization` header eksik, geçersiz veya süresi dolmuş.' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.payven.com.tr/errors/invalid_token title: Geçersiz token status: 401 code: invalid_token detail: Access token geçersiz veya süresi dolmuş — refresh edin. Forbidden: description: Yetki yok, lisans yok veya merchant pasif. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.payven.com.tr/errors/forbidden title: Yetki yok status: 403 code: forbidden detail: Bu rol bu kaynağı göremez. Conflict: description: Idempotency çakışması veya geçersiz durum geçişi. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.payven.com.tr/errors/idempotency_key_in_use title: Idempotency-Key çakışması status: 409 code: idempotency_key_in_use detail: >- Bu Idempotency-Key daha önce farklı bir istek gövdesi ile kullanıldı. UnprocessableEntity: description: >- Validasyon veya iş kuralı ihlali (`bank_declined`, `validation_failed`, `fraud_blocked` vb.). content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.payven.com.tr/errors/bank_declined title: Banka işlemi reddetti status: 422 code: bank_declined detail: 'Yetersiz bakiye (banka kodu: 51)' provider_error_code: '51' TooManyRequests: description: Rate limit aşıldı. `Retry-After` header'ına uyun. headers: Retry-After: description: Yeniden denemeden önce beklemeniz gereken saniye sayısı. schema: type: integer content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.payven.com.tr/errors/rate_limit_exceeded title: İstek limiti aşıldı status: 429 code: rate_limit_exceeded ServerError: description: >- Sunucu hatası. Exponential backoff ile tekrar deneyin (Idempotency-Key ile). content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.payven.com.tr/errors/internal_server_error title: Sunucu hatası status: 500 code: internal_server_error ServiceUnavailable: description: >- Hedef konnektör geçici olarak devre dışı (circuit breaker açık) veya bağımlılık servisi erişilemez. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.payven.com.tr/errors/connector_unavailable title: Konnektör erişilemez status: 503 code: connector_unavailable securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Identity servisinden alinan Keycloak JWT. Format: `Authorization: Bearer `. Token alma: POST /api/v1/auth/{slug}/token ````