openapi: 3.0.3
info:
  title: Pay-in Extra Merchant API
  description: Pay-in Extra Merchant Integration Specification
  version: 1.1.1
servers:
  - url: https://payinextra.com/api/v1
    description: Production Server
  - url: https://pinextrapi.online/api/v1
    description: Sandbox / Integration Server
paths:
  /payments/deposits:
    post:
      summary: Para yatırma talebi oluşturma
      description: Geçerli IBAN veya güvenli ödeme sayfası üretilebildiğinde talebi kabul eder (201 Created).
      parameters:
        - in: header
          name: X-API-Key
          required: true
          schema:
            type: string
        - in: header
          name: X-Merchant-Id
          required: true
          schema:
            type: string
            format: uuid
        - in: header
          name: X-Idempotency-Key
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - paymentMethod
                - merchantReference
              properties:
                amount:
                  type: integer
                  description: Kuruş bazında tutar (Örn. 12550 = 125.50 TRY)
                currency:
                  type: string
                  example: TRY
                paymentMethod:
                  type: string
                  example: bank_transfer
                merchantReference:
                  type: string
                  example: order-2026-000045
                customer:
                  type: object
                  properties:
                    name:
                      type: string
                    reference:
                      type: string
                    email:
                      type: string
                metadata:
                  type: object
      responses:
        '201':
          description: Yatırım talebi kabul edildi.
        '400':
          description: Idempotency anahtarı eksik veya hatalı istek.
        '409':
          description: Tekrarlanan anahtar veya mükerrer referans.
  /payments/withdrawals:
    post:
      summary: Para çekme talebi oluşturma
      description: Kesin sağlayıcı kabulünde 201, sonucu mutabakat bekleyen sahiplenilmiş talepte 202 döndürür.
      responses:
        '201':
          description: Sağlayıcı işlemi kabul etti.
        '202':
          description: Sahiplenildi, sonuç ve mutabakat bekleniyor.
  /payments/{paymentId}:
    get:
      summary: İşlem durumu sorgulama
      responses:
        '200':
          description: İşlemin güncel durumu.
  /payment-requests/{merchantReference}:
    get:
      summary: İşyeri referansı ile sorgulama
      responses:
        '200':
          description: İlk kabul kararı ve durum.
  /get-balance:
    get:
      summary: Bakiye bilgisi sorgulama
      responses:
        '200':
          description: Kullanılabilir, blokeli ve çekilebilir bakiye.