Fatura & Fatura Ödeme

Bu uçları kim çağırır?Portal / SDK

Taban yol: /api/portal/v1/wallet/me
Kimlik: Publishable key (pk_live_…) → OTP → müşteri oturumu. Oturum son kullanıcıya aittir, merchant'a değil; yalnız o kullanıcının kendi verisine erişir.
Yetki: Oturumun kendisi yetkidir; kullanıcı yalnız kendi kaydına erişir.Step-up: para çıkaran işlemlerde oturum tek başına yetmez; OTP kodu ya da güvenilir aksiyon token'ı istenir.
Çapraz yüzey: s2s API'de fatura veya fatura ödeme ucu YOKTUR. Ödeme akışı portalda, fatura KESME ve iptal panelde (POST invoices, POST invoices/:id/cancel — wallet:invoice:manage), izleme yine panelde (GET invoices, GET bill-payments — wallet:operation:read).

Birbirine benzeyen ama farklı iki yetenek vardır:

Yetenek	Ne	Kime ödenir
Fatura (invoice)	Program içindeki bir işletmenin, bir kullanıcıya kestiği fatura	Program içindeki işletmeye
Fatura ödeme (bill pay)	Elektrik, su, telekom gibi bir kurum faturasının ödenmesi	Dış kuruma

Cüzdan içi fatura

Yakında

Fatura kesme, listeleme ve cüzdandan ödeme sözleşmesi tamamlanmıştır. Yayına alınması bekleyen bir yetenektir; bu uçlar bugün istek kabul etmez. Durum: Yol Haritası.

Fatura kesin

POST /api/panel/v1/wallet/invoices

Alan	Tip	Zorunlu	Açıklama
`issuerAccountId`	string	✅	Faturayı kesen işletme hesabı
`currency`	string	✅
`lines`	array	✅	Kalemler: `description`, `quantity`, `unitAmount`
`totalAmount`	string	—	Verilmezse kalemlerden hesaplanır
`payerWalletNo`	string	⚠️	Ödeyecek cüzdan numarası
`payerPhone`	string	⚠️	Ödeyecek kişinin telefonu
`externalInvoiceNo`	string	—	Sizin fatura numaranız
`dueAtIso`	string	—	Vade
`notes`	string	—

⚠️ payerWalletNo veya payerPhone'dan biri gerekir.

totalAmount göndermezseniz kalemlerden hesaplanır. İkisini birden gönderirseniz tutarlı olmalıdırlar — yuvarlama farkı bırakmayın; minor-unit tam sayı aritmetiği kullanın.

Kullanıcı görür ve öder

GET  /api/portal/v1/wallet/me/invoices
GET  /api/portal/v1/wallet/me/invoices/{id}
POST /api/portal/v1/wallet/me/invoices/{id}/pay

Ödeme, cüzdan bakiyesinden yapılır ve OTP/step-up isteyebilir.

Webhook'lar

Olay	Ne zaman
`wallet.invoice.issued`	Fatura kesildi
`wallet.invoice.paid`	Fatura ödendi
`wallet.invoice.cancelled`	Fatura iptal edildi

Kurum faturası ödeme

Yakında — fatura kurumu entegrasyonu gerektirir

Sorgulama, ödeme, durum takibi ve mutabakat akışı hazırdır. Üretimde çalışması için bir fatura kurumu (biller) entegrasyonu bağlanmalıdır: kurum kodları ve borç sorgulama o entegrasyondan gelir. Bağlı entegrasyon yokken bu uçlar istek kabul etmez. Durum: Yol Haritası.

Borcu sorgulayın

POST /api/portal/v1/wallet/me/bills/inquire

Alan	Zorunlu	Açıklama
`billerCode`	✅	Kurum kodu
`subscriberNo`	✅	Abone numarası

Sorgulama borç tutarını ve varsa son ödeme tarihini döner.

Ödeyin

POST /api/portal/v1/wallet/me/bills/pay

Alan	Zorunlu	Açıklama
`billerCode`, `subscriberNo`	✅	Sorgulamadaki değerler
`sourceWalletAccountId`	✅	Ödeme yapılacak hesap
`amount`, `currency`	✅
`billRef`	—	Sorgulamadan dönen borç referansı
`billerCategory`	—
`idempotencyKey`	✅	Çift ödeme koruması
`trustedActionToken`	—	Step-up

Takip edin

GET /api/portal/v1/wallet/me/bills

Durumlar ve mutabakat

Fatura ödeme, dış kuruma bağlı olduğu için asenkron ilerler:

Olay	Ne demek
`wallet.billpay.dispatched`	Talimat kuruma iletildi
`wallet.billpay.confirmed`	Kurum ödemeyi onayladı
`wallet.billpay.failed`	Kurum reddetti; tutar iade edildi
`wallet.billpay.awaiting_recon`	Sonuç belirsiz, mutabakata alındı
`wallet.billpay.reversed`	Onaylanmış ödeme ters kaydedildi

⚠️

dispatched, "fatura ödendi" demek değildir. Kullanıcıya "gönderildi" deyin; "ödendi" ifadesini yalnız confirmed olayında kullanın. Aksi hâlde kurum reddettiğinde kullanıcı ödediğini sanır.

⚠️

awaiting_recon durumundaki bir fatura ödemesini yeniden denemeyin — kurum tarafında iki kez ödenmiş olabilir. Mutabakat sonucunu bekleyin.

Yaygın hatalar

Durum	Sebep	Çözüm
Sorgulama boş dönüyor	Abone numarası veya kurum kodu hatalı	Kullanıcıya kurum bazlı format ipucu gösterin
Ödeme `awaiting_recon`'da	Kurum yanıtı belirsiz	Bekleyin, tekrar ödemeyin
Fatura tutarı ile ödeme tutarı farklı	Kısmi ödeme denendi	Kurumun kısmi ödemeye izin verip vermediği entegrasyona bağlıdır

Toplu Ödeme Limitler