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

# Para Transferi

> Çoklu banka EFT, FAST, havale ve banka hesabı transferi altyapısı.

Payven Para Transferi modülü; lisanslı ödeme kuruluşları ve büyük platformlar için **çoklu banka transfer altyapısı** sunar. EFT, FAST ve havale işlemlerini tek API üzerinden çoklu banka konnektörü üzerinden yürütür; toplu işlem desteği, otomatik mutabakat ve transfer iade yönetimi içerir.

## Temel özellikler

<CardGroup cols={2}>
  <Card title="Çoklu Banka Konnektörleri" icon="building-columns">
    Kuveyt Türk, Fibabanka, İş Bankası, Akbank, HalkBank ve diğerleri — banka entegrasyonlarının teknik farklarını Payven soyutlar; sizin payload'unuz tüm bankalarda aynıdır.
  </Card>

  <Card title="EFT + FAST + Havale" icon="arrow-right-arrow-left">
    Tek API ile üç transfer tipi. Bankaya göre otomatik FAST / EFT seçimi.
  </Card>

  <Card title="Bulk İşlem" icon="layer-group">
    Onlarca-yüzlerce transferi tek istekte gönderin; banka batch API'leri otomatik kullanılır.
  </Card>

  <Card title="Otomatik Resilience" icon="arrows-rotate">
    Geçici hatalarda exponential backoff retry, eşik aşımında devre kesici, token tazeleme — hepsi otomatik.
  </Card>

  <Card title="Webhook + Realtime Dashboard" icon="bell">
    Transfer durum değişimleri webhook ile teslim edilir; konsol gerçek zamanlı güncellenir.
  </Card>

  <Card title="Tenant İzolasyonu" icon="shield-keyhole">
    Her organizasyonun verisi diğer organizasyonlardan tamamen yalıtılmıştır.
  </Card>
</CardGroup>

## Base URL

| Ortam      | URL                                      |
| ---------- | ---------------------------------------- |
| Sandbox    | `https://transfer-sandbox.payven.com.tr` |
| Production | `https://transfer.payven.com.tr`         |

## Transfer yaşam döngüsü

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending: POST /transfers/bulk/create
    pending --> approved: POST /transfers/bulk/approve
    approved --> processing: POST /transfers/bulk/send
    processing --> completed: Banka onayı (sync)
    processing --> delivered: Banka kabul (async, FAST)
    processing --> failed: Banka reddi
    delivered --> completed: Webhook ile
    completed --> [*]
    failed --> [*]
    pending --> rejected: POST /transfers/bulk/reject
    rejected --> [*]
```

| Durum        | Anlam                                                  |
| ------------ | ------------------------------------------------------ |
| `pending`    | Transfer oluşturuldu, onay bekliyor (4-eyes principle) |
| `approved`   | Onaylandı, banka gönderimine hazır                     |
| `processing` | Bankaya gönderildi, yanıt bekleniyor                   |
| `completed`  | Banka tarafından onaylandı (senkron başarı)            |
| `delivered`  | Banka kabul etti, hesap geçişi asenkron (FAST modeli)  |
| `failed`     | Banka reddetti veya teknik hata                        |
| `rejected`   | İç onay sürecinde reddedildi                           |

## Endpoint kategorileri

| Kategori               | Endpoint örnekleri                                            |
| ---------------------- | ------------------------------------------------------------- |
| Transfer yaşam döngüsü | `POST /transfers/bulk/create`, `/approve`, `/reject`, `/send` |
| Sorgulama              | `GET /transfers`, `GET /transfers/{id}`                       |
| Dekont                 | `GET /transfers/{id}/receipt/download`, `/base-64`            |
| Hesaplar               | `GET /accounts`, `/accounts/transactions`                     |
| Alıcılar               | `POST /recipients`, `GET /receiveraccounts`                   |
| Tekrarlayan            | `POST /recurringtransfers`                                    |
| Validasyon             | `POST /validation/iban`                                       |

## Hızlı başlangıç

```bash theme={null}
# 1. Bulk transfer oluştur (4-eyes: önce create)
curl -X POST https://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/create \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: payroll-2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{
    "transfers": [
      {
        "external_id":      "PAYROLL-001",
        "amount":           { "amount": 1500000, "currency": "TRY" },
        "transfer_type":    "fast",
        "sender_account_id": "3fa85f64-...",
        "receiver_account": {
          "iban":           "TR000006100000000000000001",
          "owner_name":     "Ahmet Yilmaz",
          "owner_tax_id":   "12345678901"
        },
        "description":      "Mayıs maaş ödemesi"
      }
    ]
  }'

# 2. Onayla (yetkilendirilmiş kullanıcı tarafından)
curl -X POST https://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/approve \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "transfer_ids": ["8e3f5c12-..."] }'

# 3. Bankaya gönder
curl -X POST https://transfer-sandbox.payven.com.tr/api/v1/transfers/bulk/send \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "transfer_ids": ["8e3f5c12-..."] }'
```

## Konnektör kapasitesi

| Konnektör   | EFT        | FAST       | Havale     | Kart Transferi | Dekont PDF | Bulk |
| ----------- | ---------- | ---------- | ---------- | -------------- | ---------- | ---- |
| Kuveyt Türk |            | Evet       |            | Evet           |            | Evet |
| Fibabanka   | —          | —          | —          |                | —          |      |
| İş Bankası  |            | Evet       |            | Evet           |            | Evet |
| Akbank      |            | Evet       |            | Evet           |            | Evet |
| HalkBank    |            | Evet       |            | —              |            | Evet |
| Intertech   | 🔧 Yakında | 🔧 Yakında | 🔧 Yakında | 🔧 Yakında     | —          | —    |

<Note>
  İstek payload'unuz tüm bankalarda aynıdır. Hangi banka konnektörünün kullanılacağı
  konsoldan tanımlanan **konnektör konfigürasyonuna** göre seçilir.
</Note>

## Webhook olayları

| Olay                 | Tetikleyici                         |
| -------------------- | ----------------------------------- |
| `transfer.created`   | Yeni transfer oluşturuldu (pending) |
| `transfer.approved`  | Onaylandı                           |
| `transfer.rejected`  | İç onayda reddedildi                |
| `transfer.completed` | Banka senkron onay verdi            |
| `transfer.delivered` | Banka asenkron kabul etti (FAST)    |
| `transfer.failed`    | Banka reddi veya teknik hata        |

Webhook delivery: HMAC-SHA256 imzalı, 5 retry deneme (1m / 5m / 30m / 2h / 24h, ±%20 jitter), 15sn timeout. Tüm denemeler başarısız olursa olay konsoldan manuel olarak yeniden tetiklenebilir.

## Sorumlu kullanım

<Warning>
  Para transferi modülü **iyi yapılandırılmış AML/KYC süreçlerinizle birlikte**
  çalışır. IBAN doğrulama (`/validation/iban`) ve alıcı doğrulama
  (`recipients` master) ile birlikte sahte transfer riskini düşürün.
</Warning>

## Yol haritası

Para transferi referans dokümanı genişlemeye devam ediyor. Yakında:

* **Transfer Object** — tüm alanların referansı
* **Transfer akışları** — create/approve/send adımlarının ayrı detay sayfaları
* **Recurring Transfers** — periyodik transfer kurulumu
* **Hesap & Alıcı yönetimi** — master data yapıları

API referansı için: [Para Transferi OpenAPI](/api-reference/transfer).