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

# Toplu transfer paketi oluştur

> Birden fazla transferi tek pakette oluşturur (paket başına en fazla 1000). Paket `pending_approval` durumunda başlar; ikinci kullanıcı onaylayana kadar bankaya gönderilmez. Bkz. [4-Eyes Transfer reçetesi](/recipes/four-eyes-transfer).



## OpenAPI

````yaml /api-reference/transfer/openapi.json post /api/v1/transfers/bulk/create
openapi: 3.0.4
info:
  title: Payven Para Transferi API
  description: >-
    Payven Para Transferi — çoklu banka EFT, FAST, havale ve banka hesabı
    transferi 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://transfer-sandbox.payven.com.tr
    description: Sandbox
  - url: https://transfer.payven.com.tr
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Accounts
    x-displayName: Hesaplar
  - name: ApiRequestLogs
    x-displayName: API İstek Kayıtları
  - name: BankBins
    x-displayName: Banka BIN'leri
  - name: Banks
    x-displayName: Bankalar
  - name: ConnectorAccounts
    x-displayName: Konnektör Hesapları
  - name: ConnectorAccountTransferRules
    x-displayName: Konnektör Hesap Transfer Kuralları
  - name: ConnectorConfigurations
    x-displayName: Konnektör Konfigürasyonları
  - name: Connectors
    x-displayName: Konnektörler
  - name: Dashboard
    x-displayName: Dashboard
  - name: Me
    x-displayName: Oturum
  - name: ReceiverAccounts
    x-displayName: Alıcı Hesapları
  - name: Recipients
    x-displayName: Alıcılar
  - name: RecurringTransfers
    x-displayName: Tekrarlayan Transferler
  - name: Settings
    x-displayName: Ayarlar
  - name: Transfers
    x-displayName: Transferler
  - name: Validation
    x-displayName: Validasyon
  - name: Webhooks
    x-displayName: Webhook'lar
paths:
  /api/v1/transfers/bulk/create:
    post:
      tags:
        - Transfers
      summary: Toplu transfer paketi oluştur
      description: >-
        Birden fazla transferi tek pakette oluşturur (paket başına en fazla
        1000). Paket `pending_approval` durumunda başlar; ikinci kullanıcı
        onaylayana kadar bankaya gönderilmez. Bkz. [4-Eyes Transfer
        reçetesi](/recipes/four-eyes-transfer).
      operationId: bulkCreateTransfers
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CreateTransfersCommand'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTransferModelListApiResponseDto'
        '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://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/create
            \
              -H "Authorization: Bearer $PAYVEN_TOKEN" \
              -H "Idempotency-Key: order-1001" \
              -d '{ ...payload... }'
        - lang: javascript
          label: Node.js
          source: |-
            const res = await fetch(
              "https://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/create",
              {
                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://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/create",
                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://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/create");

            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://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/create",
            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://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/create");

            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:
    CreateTransfersCommand:
      type: object
      properties:
        items:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/CreateTransferModel'
              - $ref: '#/components/schemas/CreateTransferResponseModel'
          nullable: true
      additionalProperties: false
    CreateTransferModelListApiResponseDto:
      type: object
      properties:
        message:
          type: string
          nullable: true
        is_success:
          type: boolean
        code:
          type: string
          nullable: true
        data:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/CreateTransferModel'
              - $ref: '#/components/schemas/CreateTransferResponseModel'
          nullable: true
      additionalProperties: false
    CreateTransferModel:
      type: object
      properties:
        source_account_id:
          type: string
          format: uuid
        external_id:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        transfer_type:
          allOf:
            - $ref: '#/components/schemas/TransferType'
        recipient:
          allOf:
            - $ref: '#/components/schemas/MoneyTransferRecipientDto'
          nullable: true
        amount:
          allOf:
            - $ref: '#/components/schemas/AmountDto'
          nullable: true
      additionalProperties: false
    CreateTransferResponseModel:
      allOf:
        - $ref: '#/components/schemas/CreateTransferModel'
        - type: object
          properties:
            transfer_id:
              type: string
              format: uuid
          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: {}
    TransferType:
      enum:
        - EFT
        - Fast
        - Remittance
        - CreditCard
      type: string
    MoneyTransferRecipientDto:
      required:
        - holder_name
      type: object
      properties:
        recipient_id:
          type: string
          format: uuid
          nullable: true
        holder_name:
          type: string
          nullable: true
        iban:
          type: string
          nullable: true
        account_number:
          type: string
          nullable: true
        card_details:
          allOf:
            - $ref: '#/components/schemas/CardDetailsDto'
          nullable: true
      additionalProperties: false
    AmountDto:
      type: object
      properties:
        value:
          type: integer
          format: int64
        currency_code:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
      additionalProperties: false
    CardDetailsDto:
      type: object
      properties:
        card_token:
          type: string
          nullable: true
        card_number:
          type: string
          nullable: true
      additionalProperties: false
    CurrencyCode:
      enum:
        - TRY
        - USD
        - EUR
      type: string
  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

````