Skip to main content
Alıcı (recipient), düzenli transfer ettiğiniz kişilerin / kurumların kayıtlı master data’sıdır. Alıcı kaydedince her transferde IBAN ve kimlik bilgilerini tekrar girmeniz gerekmez; recipient_id referans verirsiniz, Payven kalan bilgileri çeker.

​
Ne zaman kullanılır?

SenaryoSaklı alıcıAd-hoc IBAN
Maaş bordrosu (her ay aynı çalışanlar)—
Tedarikçi ödemesi (sürekli iş yapılan firmalar)—
Tek seferlik müşteri iadesi—
Marketplace satıcıya ödeme (kayıtlı satıcı)—

​
Endpoint’ler

POST   /api/v1/recipients                       # Yeni alıcı
GET    /api/v1/recipients                       # Liste (sayfalı)
GET    /api/v1/recipients/by-bank/{bank_id}     # Banka bazlı liste
PUT    /api/v1/recipients/{id}                  # Güncelleme
DELETE /api/v1/recipients/{id}                  # Silme
Yetki: Listeleme için transfer-viewer yeterli; CRUD operasyonları transfer-admin gerektirir.

​
Alıcı oluşturma

curl -X POST https://transfer.payven.com.tr/api/v1/recipients \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Idempotency-Key: recipient-ahmet-yilmaz-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "holder_name":    "Ahmet Yılmaz",
    "tax_id":         "12345678901",
    "tax_id_type":    "tckn",
    "email":          "ahmet@example.com",
    "phone":          "+905551112233",
    "label":          "Mayıs maaş listesi — Yazılım Ekibi",
    "external_id":    "EMP-001"
  }'
AlanTipZorunlulukAçıklama
holder_namestringZorunluAlıcının adı (max 100 karakter)
tax_idstringZorunluTC kimlik no (gerçek kişi) veya vergi numarası (tüzel kişi)
tax_id_typeenumZorunlutckn (gerçek kişi) veya vkn (tüzel kişi)
emailstringOpsiyonelBilgilendirme e-postası gönderilecek adres (raporlama için)
phonestringOpsiyonelİletişim numarası
labelstringOpsiyonelOperatör için etiket (örn. “Maaş listesi 2026 Mayıs”)
external_idstringÖnerilirSizin sisteminizdeki kayıt kimliği
Alıcı = master kayıt, alıcı hesabı = IBAN. Bir alıcının birden fazla IBAN’ı olabilir (örn. farklı bankalardaki hesapları). IBAN’lar Alıcı Hesapları ile ayrı yönetilir.

​
Yanıt

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id":            "abc-12345-6789-...",
  "holder_name":   "Ahmet Yılmaz",
  "tax_id":        "12345678901",
  "tax_id_type":   "tckn",
  "email":         "ahmet@example.com",
  "phone":         "+905551112233",
  "label":         "Mayıs maaş listesi — Yazılım Ekibi",
  "external_id":   "EMP-001",
  "is_active":     true,
  "created":       "2026-05-03T12:00:00.123+00:00"
}
id değerini saklayın — transfer oluştururken recipient_id olarak kullanılacak.

​
Listeleme

curl "https://transfer.payven.com.tr/api/v1/recipients?page_size=50&search_term=Yılmaz" \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
Standart sayfalı liste yapısı döner.
Sorgu parametresiAçıklama
search_termholder_name, tax_id, external_id, label üzerinde arama
is_activetrue (varsayılan) veya false (silinmişler dahil)
tax_id_typetckn veya vkn filtresi

​
Banka bazlı liste

Belirli bir bankadaki hesaplara ait alıcıları döndürür: 
curl https://transfer.payven.com.tr/api/v1/recipients/by-bank/$BANK_ID \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
bank_id Identity’deki banka kataloğundan gelir.

​
Güncelleme

curl -X PUT https://transfer.payven.com.tr/api/v1/recipients/abc-12345-... \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ahmet.yilmaz@yenisirket.com",
    "label": "Maaş — Yazılım Ekibi (yeni iletişim)"
  }'
Yalnızca değiştirmek istediğiniz alanları gönderin. tax_id değiştirilemez (yeni alıcı oluşturmanız gerekir).

​
Silme

curl -X DELETE https://transfer.payven.com.tr/api/v1/recipients/abc-12345-... \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
Soft delete uygulanır — kayıt veritabanında kalır ama listelemelerde görünmez. Bu alıcıya ait geçmiş transferler etkilenmez.

​
Alıcıya transfer

Saklı alıcıya transfer oluştururken: 
{
  "recipient": {
    "recipient_id": "abc-12345-..."
  }
}
holder_name, iban, tax_id otomatik olarak alıcı master data’sından çekilir. IBAN’ın hangi hesap olduğunu da belirtmek isterseniz receiver_account_id ile birlikte gönderin (bkz. Alıcı Hesapları).

​
Hata response’ları

HTTPcodeAnlam
400validation_failedEksik / format hatalı alan
403forbiddentransfer-admin rolü yok
404recipient_not_foundid bulunamadı
422invalid_tax_idTC kimlik / vergi no checksum’ı geçmiyor
409duplicate_external_idAynı external_id ile başka alıcı zaten var

​
Sonraki adım

Alıcı Hesapları

Bir alıcının IBAN’larını ve banka hesaplarını yönetin.