> ## 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.

# 3D Secure ödemeyi başlat

> 3DS akışını başlatır. Yanıtta gelen `redirect_url` ile müşteriyi bankanın 3DS sayfasına yönlendirin. Doğrulama sonrasında banka, başvuruda verdiğiniz `callback_url` adresine kullanıcıyı geri yönlendirir.

Akış tamamlandıktan sonra otorizasyonu kesinleştirmek için [3D Secure tamamla](#complete-3ds) uç noktası çağrılır (otomatik veya manuel).



## OpenAPI

````yaml /api-reference/sanal-pos/openapi.json post /api/v1/payments/3d/init
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/3d/init:
    post:
      tags:
        - Payments
      summary: 3D Secure ödemeyi başlat
      description: >-
        3DS akışını başlatır. Yanıtta gelen `redirect_url` ile müşteriyi
        bankanın 3DS sayfasına yönlendirin. Doğrulama sonrasında banka,
        başvuruda verdiğiniz `callback_url` adresine kullanıcıyı geri
        yönlendirir.


        Akış tamamlandıktan sonra otorizasyonu kesinleştirmek için [3D Secure
        tamamla](#complete-3ds) uç noktası çağrılır (otomatik veya manuel).
      operationId: initThreeDsPayment
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Init3DRequest'
      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/3d/init \
              -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/3d/init",
              {
                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/3d/init",
                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/3d/init");

            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/3d/init", 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/3d/init");

            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:
    Init3DRequest:
      type: object
      properties:
        external_id:
          type: string
          nullable: true
          description: Sizin sipariş kimliğiniz.
          example: ORDER-1001
        basket_id:
          type: string
          nullable: true
          description: Sepet kimliği.
          example: BASKET-2026-001
        amount:
          allOf:
            - $ref: '#/components/schemas/PaymentAmountRequestDto'
          nullable: true
          description: İşlem tutarı (kuruş + currency).
        installment:
          type: integer
          format: int32
          description: Taksit sayısı. `1` = peşin.
          example: 1
        card:
          allOf:
            - $ref: '#/components/schemas/PaymentCardInfoRequestDto'
          nullable: true
          description: Kart bilgileri.
        description:
          type: string
          nullable: true
        buyer:
          allOf:
            - $ref: '#/components/schemas/PaymentBuyerRequestDto'
          nullable: true
        billing_address:
          allOf:
            - $ref: '#/components/schemas/PaymentAddressRequestDto'
          nullable: true
        shipping_address:
          allOf:
            - $ref: '#/components/schemas/PaymentAddressRequestDto'
          nullable: true
        basket_items:
          type: array
          items:
            $ref: '#/components/schemas/PaymentBasketItemRequestDto'
          nullable: true
        callback_url:
          type: string
          nullable: true
          description: >-
            **Zorunlu**. 3DS doğrulaması sonrası bankanın kullanıcıyı geri
            yönlendireceği HTTPS URL'iniz. Buradan gelen `transaction_id` ile
            [`/payments/3d/complete`](#complete-3ds) çağrılır.
          example: https://example.com/3ds/return
        cancel_url:
          type: string
          nullable: true
          description: Müşteri 3DS akışını iptal ederse yönlendirileceği URL.
          example: https://example.com/checkout/cancel
        return_url:
          type: string
          nullable: true
          description: >-
            Sonuç sayfasına yönlendirme için (success/fail unified).
            `callback_url` farklı sebeple kullanılır.
        operation_type:
          allOf:
            - $ref: '#/components/schemas/OperationType'
          description: '`sale` (varsayılan) veya `pre_auth`.'
          example: sale
        extra_properties:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Konnektör-spesifik özel alanlar.
      additionalProperties: false
      description: >-
        3D Secure ödeme başlatma isteği. CreatePaymentRequest ile aynı alanlara
        ek olarak callback/return/cancel URL'leri taşır.
      required:
        - amount
        - card
        - installment
        - callback_url
    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
    PaymentAmountRequestDto:
      type: object
      properties:
        amount:
          type: integer
          format: int64
          description: >-
            Tutar — **kuruş cinsinden tam sayı**. 1,00 ₺ → 100, 150,00 ₺ →
            15000.
          example: 15000
        currency:
          type: string
          nullable: true
          description: ISO 4217 para birimi kodu. Şu an yalnızca `TRY` desteklenir.
          example: TRY
      additionalProperties: false
      description: Tutar nesnesi — kuruş cinsinden tam sayı + ISO 4217 para birimi.
      required:
        - amount
        - currency
    PaymentCardInfoRequestDto:
      type: object
      properties:
        holder_name:
          type: string
          nullable: true
        number:
          type: string
          nullable: true
        expire_month:
          type: string
          nullable: true
        expire_year:
          type: string
          nullable: true
        cvv:
          type: string
          nullable: true
      additionalProperties: false
    PaymentBuyerRequestDto:
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: >-
            Müşteri kimliğiniz. Aynı kimliğin tekrarlayan ödemeleri fraud
            kurallarında kullanılır.
          example: cust-001
        name:
          type: string
          nullable: true
          description: Müşteri adı.
          example: Ahmet
        surname:
          type: string
          nullable: true
          description: Müşteri soyadı.
          example: Yılmaz
        email:
          type: string
          nullable: true
          description: Müşteri e-posta adresi. Bazı bankaların 3DS mesajlarında zorunludur.
          example: musteri@example.com
        phone:
          type: string
          nullable: true
          description: Müşteri telefon numarası (E.164 formatında önerilir).
          example: '+905551112233'
        ip_address:
          type: string
          nullable: true
          description: >-
            Müşterinin **gerçek** IP'si. Reverse proxy arkasındaysanız
            `X-Forwarded-For` header'dan alın. Fraud için kritik.
          example: 85.105.10.10
        identity_number:
          type: string
          nullable: true
          description: >-
            TC kimlik numarası. Yüksek tutarlı işlemlerde bazı bankalar zorunlu
            kılar.
          example: '12345678901'
      additionalProperties: false
      description: Müşteri bilgileri — fraud sinyalleri ve banka risk skoru için.
    PaymentAddressRequestDto:
      type: object
      properties:
        contact_name:
          type: string
          nullable: true
          description: Adresteki kişinin adı.
          example: Ahmet Yılmaz
        city:
          type: string
          nullable: true
          description: Şehir adı.
          example: İstanbul
        country:
          type: string
          nullable: true
          description: ISO 3166-1 alpha-2 ülke kodu.
          example: TR
        address:
          type: string
          nullable: true
          description: Sokak ve bina detayı.
          example: Maslak Mh. ...
        postal_code:
          type: string
          nullable: true
          description: Posta kodu.
          example: '34485'
      additionalProperties: false
      description: Adres bilgisi (fatura veya teslimat).
    PaymentBasketItemRequestDto:
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: Kaleminizin kimliği.
          example: SKU-001
        name:
          type: string
          nullable: true
          description: Kalem adı.
          example: Kablosuz kulaklık
        price:
          type: number
          format: double
          description: Kalem birim fiyatı — kuruş cinsinden.
          example: 7500
        quantity:
          type: integer
          format: int32
          description: Adet.
          example: 2
      additionalProperties: false
      description: Sepet kalemi.
      required:
        - name
        - price
        - quantity
    OperationType:
      enum:
        - Sale
        - PreAuth
        - PostAuth
        - Void
        - Refund
        - Recurring
      type: string
    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>`. Token alma: POST /api/v1/auth/{slug}/token

````