3. Adım — Bankaya Gönder - Payven Developer Portal

Send, 4-eyes akışının son adımıdır. approved durumdaki transferler bankaya gönderilir, işlem başlatılır. Bu adımdan sonra para hesaplarınızdan çekilir.

Endpoint

POST /api/v1/transfers/bulk/send

Yetki: transfer-admin rolü gerektirir.

Bu adım geri alınamaz. Bankaya gönderim başladıktan sonra processing aşamasına geçen transfer ancak banka tarafında reddedilirse failed olur. Hesaplarınızdan para çekilir.

İstek

curl -X POST https://transfer.payven.com.tr/api/v1/transfers/bulk/send \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Idempotency-Key: payroll-2026-05-01-send" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_ids": [
      "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
      "9f3d2b8e-..."
    ]
  }'

Alan	Tip	Zorunluluk	Açıklama
`transfer_ids[]`	UUID array	Zorunlu	Gönderilecek transfer kimlikleri (max 1000 / istek)

Yanıt

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "sent": [
    {
      "id":           "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
      "status":       "processing",
      "sent_date":    "2026-05-03T12:34:58.000+00:00"
    },
    {
      "id":           "9f3d2b8e-...",
      "status":       "completed",
      "sent_date":    "2026-05-03T12:34:58.500+00:00",
      "processed_date":"2026-05-03T12:34:59.234+00:00",
      "receipt_no":   "TRF-20260503-0001"
    }
  ],
  "skipped": [],
  "total_sent": 2
}

202 Accepted — istek alındı, banka çağrıları yapıldı. Yanıttaki status’lar:

Status	Anlam	Sonraki adım
`processing`	Bankaya gönderildi, yanıt bekleniyor	Webhook bekleyin veya `GET /transfers/{id}` ile sorgulayın
`completed`	Banka senkron onayladı (genellikle remittance, küçük tutarlar)	İşlem tamam
`delivered`	Banka FAST kanalında kabul etti, hesap geçişi asenkron	Sonradan `completed` olur, webhook gelir
`failed`	Banka reddi (yetersiz bakiye, blok vb.)	`error_code` inceleyin

Asenkron sonuç

FAST ve EFT işlemleri çoğu zaman asenkron tamamlanır. processing veya delivered döndüğünde nihai sonucu webhook ile yakalayın:

Webhook olayı	Tetikleyici
`transfer.succeeded`	Transfer başarıyla tamamlandı (`completed`)
`transfer.failed`	Banka reddi veya teknik hata

Detay: Webhook Olayları. Webhook gelmemişse GET /api/v1/transfers/{id} ile son durumu sorgulayabilirsiniz — bkz. Transfer Detayı.

Banka tarafından red

Banka tarafı red veya bakiye yetersizliği gibi durumlarda response 422 Unprocessable Entity + application/problem+json döner; code programatik karar için, provider_error_code bankanın orijinal kodunu taşır. Tam payload yapısı: Hata Yönetimi. Sonradan GET /api/v1/transfers/{id} ile sorgulandığında failed transfer için error_code ve provider_error_code response body’sinde yer alır.

Akıllı yönlendirme ve fallback

Sender hesabınız birden fazla banka konnektörüne bağlıysa, Payven uygun olanı seçer. Birinci konnektör hata verirse otomatik fallback’e düşer (success_sender_account_id yanıtta gerçek kullanılan hesabı taşır). Bu sırada retry_count artar.

Hata response’ları

HTTP	`code`	Anlam
`403`	`forbidden`	`transfer-admin` rolü yok
`404`	`transfer_not_found`	Tüm verilen ID’ler bulunamadı
`422`	`invalid_state_transition`	Transfer `approved` durumunda değil
`422`	`insufficient_balance`	Kaynak hesapta yeterli bakiye yok
`422`	`bank_declined`	Banka reddetti — `provider_error_code` daha spesifik bilgi taşır
`422`	`recipient_blocked`	Alıcı blacklist’te
`422`	`iban_not_eligible`	IBAN seçilen transfer tipinde işlenemez (örn. yurtdışı IBAN’a FAST)
`503`	`connector_unavailable`	Banka konnektörü geçici olarak devre dışı
`409`	`idempotency_key_in_use`	Aynı `Idempotency-Key` farklı body için kullanılmış

Hata yanıtı RFC 9457 problem+json. Detay: Hata Yönetimi.

Sonraki adımlar

Webhook entegrasyonu

Asenkron sonuçları gerçek zamanlı yakalayın.

Transfer detayı

Tek bir transferin son durumunu sorgulayın.

Dekont indirme

Tamamlanmış transferin makbuz PDF’i.

Tekrarlayan transfer

Periyodik (maaş, kira, abonelik) transferler.

Genel Bakış

Transfer Akışı (4-Eyes)

Tekrarlayan Transferler

Sorgulamalar & Dekont

Alıcılar

Validasyon

Raporlama & İzleme

Webhook'lar

Hata Kodları

3. Adım — Bankaya Gönder

Endpoint

İstek

Yanıt

Asenkron sonuç

Banka tarafından red

Akıllı yönlendirme ve fallback

Hata response’ları

Sonraki adımlar

Webhook entegrasyonu

Transfer detayı

Dekont indirme

Tekrarlayan transfer

​Endpoint

​İstek

​Yanıt

​Asenkron sonuç

​Banka tarafından red

​Akıllı yönlendirme ve fallback

​Hata response’ları

​Sonraki adımlar

Webhook entegrasyonu

Transfer detayı

Dekont indirme

Tekrarlayan transfer

Endpoint

İstek

Yanıt

Asenkron sonuç

Banka tarafından red

Akıllı yönlendirme ve fallback

Hata response’ları

Sonraki adımlar