Ana içeriğe atla
E-Pos, firmanızın kendi banka veya ödeme kuruluşu sanal POS hesaplarını kullanır. İşlemler /apps/bankpos altında, muhasip:epos:read ve muhasip:epos:write izinleriyle yapılır. Muhasip POS tahsilatının /apps/pos kaynakları ayrı hesap ve işlemlerdir.

​
1. Erişimi ve sağlayıcı desteğini okuyun

HTTP Basic kimlik bilgilerinizi sunucu tarafında kullanın. Firma, API anahtarından belirlenir. Genel erişim veya yönetici yetkisi E-Pos izninin yerine geçmez; write tek başına read sağlamaz. Firma paketi ücretli ve süresi aktif olmalıdır; Enterprise paketinde süre koşulu uygulanmaz. Hoppa kodu esnekpos değeridir. integrationStatus=planned sağlayıcılar için yalnız taslak hesap yönetimi yapılır. Ödeme, bağlantı ve oran sorgusu yeteneklerini katalogdan kontrol edin. Hesabın ortamı firmanın test bilgisine bağlıdır; istekle test/canlı ortam seçilmez.

​
2. Hesabı hazırlayın

  1. Hesap oluşturun. İş niyetine ait kalıcı Idempotency-Key, hesap adı, sağlayıcı ve taksit/satış tarifelerini gönderin. Başlangıç durumu draft olur.
  2. Bağlantı bilgilerini kaydedin. Hoppa için identity.merchant işyeri kodu, credentials.merchantKey gizli anahtardır. Anahtar yanıttan geri okunamaz. Gerçek değeri sunucu ortamınızdan alın; örnek veya loglara koymayın.
  3. Bağlantıyı kontrol edin. connectionCheck.status=passed sonucu hesabı kendiliğinden etkinleştirmez.
  4. Hesabı etkinleştirin: Güncel revision ile status=active gönderin. Para birimi/taksit desteği ve bağlantı koşulları ayrıca doğrulanır.
Her hesap yazımında cevapta dönen revision değerini saklayın. Yanıt kaybında önce hesap ayrıntısını okuyun. Eski sürüm 409 BANKPOS_REVISION_CONFLICT üretir. If-Match yerine bu kaynaklarda gövdedeki revision kullanılır. Hesap oluşturma kendi tekrar anahtarıyla aynı hesabı döndürür; genel işlem makbuzu üretmez. Hesap güncelleme, bağlantı kaydı/kontrolü ve varsayılan seçiminde de genel operation makbuzu yoktur; güncel sürümle ilerleyin.

​
3. Genel ve kart ailesi satış tarifelerini tanımlayın

Hesaptaki installmentRates dizisi her tek çekim/taksitin aktifliğini ve genel satış oranını içerir. familySaleRates kart ailesi ve taksit bazındaki özel satışları içerir. Oranlar yüzde sayısıdır; örneğin 1.49, %1,49 demektir. En fazla dört ondalık kullanın.
Bu tarifede tek çekim komisyonsuzdur; 3 taksitte genel satış oranı %1, Paraf için %0’dır.
  • Özel aile satırı yoksa genel satış oranı kullanılır. Açık 0 eksik değer değildir.
  • Hesap güncellemesinde gönderilen oran dizisi bütün olarak değiştirilir. Genel taksit satırlarını ve korumak istediğiniz aile satırlarını birlikte değerlendirin; atlanan dizi mevcut hâliyle kalır, familySaleRates: [] aile tarifelerini kaldırır.
  • En az bir taksit aktif olmalıdır. Aile/taksit çifti tekrarlanamaz; aile tarifesinin taksiti hesapta tanımlı olmalıdır.
  • Alış oranlarını okuyun. Hoppa alışları aile/taksit bazında gelir; katalog güncel ödeme maliyetinin kesin hesabı değildir. Ödeme, müşterinin kartı ve çekim toplamıyla yeniden fiyatlanır.
Alışı satışa birebir yansıtmak için katalogdaki ilgili purchaseRate değerini satış tarifesine yazın. Puan eklemek istiyorsanız örneğin %4,8 + 0,1 puan = %4,9 olarak hesaplayın; %4,8’in yüzde 0,1’i değildir. Geçerli değerleri tek hesap güncellemesinde gönderin. Alışı bulunmayan aile/taksiti sıfır maliyet saymayın; genel tarifeyi ayrıca belirleyin. family=null, sağlayıcının aile belirtmediği alış satırıdır. Aile kodu olarak null ile satış tanımlanmaz; bu kartlarda genel satış tarifesi kullanılır.

​
4. Ödeme talebi oluşturun

Ödeme talebi oluşturma için aktif/doğrulanmış hesap, güncel accountRevision, aynı firmaya ait arşivlenmemiş cari ve en az bir aktif taksit gerekir. Yeni Hoppa talebinde seçenekler 1–12 aralığındadır. Talep para birimi TRY’dir; tutar kuruş cinsinden tamsayıdır.
  • amountMinor verilmez veya null olursa müşteri ödeme sayfasında tutarı girer. 10000, 100 TL’dir; sabit tutar müşteri tarafından değiştirilemez. Verilen tutar 1–1.000.000.000 kuruş olmalıdır.
  • Birden fazla taksit sunabilirsiniz; müşteri kartının desteklediği izinli seçeneklerden birini seçer. installment=1 tek çekimdir.
  • Seçenekte saleRate verilmezse hesabın o taksite ait genel satışı alınır. familySaleRates verilmezse hesabın ilgili taksit aile tarifeleri alınır; açık [], bu talepte genel tarifeyi kullanır.
  • Talepte verilen oranlar yalnız o talebe aittir. Hesap tarifesi değişmez; talep, oluşturulduğu tarifeleri korur.
  • Cari adı/tam ünvanı en az iki kelime olmalıdır. E-posta, telefon, il, ilçe ve adresin geçerli olanları cari kartından kullanılır; yalnız eksik/geçersiz olanlar ödeme sayfasında müşteriden alınır. Bu alanları talep gövdesine eklemeyin.
Talep oluşturmak karttan çekim başlatmaz. Cevaptaki _id, reference, expiresAt, url ve varsa operation.operationId değerlerini saklayın. Ödeme bağlantısı 30 dakika geçerlidir; url alanındaki adresi doğrudan kullanın ve günlüklemeyin. Kart/PAN/CVV alanlarını bu API’ye göndermeyin. Hesap ayarı veya bağlantı bilgisi değiştirilirse eski hesap sürümüne bağlı henüz başlatılmamış talepler kullanılamayabilir. Aynı hesapta yeni talep oluşturmak veya başka bir ödeme tamamlamak, hesap ayarı değişikliği değildir.

​
5. Ödemeyi ve komisyonları doğrulayın

Müşteri ödeme bağlantısında eksik bilgilerini, gerekiyorsa tutarı ve kartını girer; sunulan seçenekten bir taksit seçer ve 3D adımını tamamlar. Satış komisyonu çekim toplamına eklenir. Satış oranı 0 olsa da sağlayıcının alış komisyonu bulunabilir. Örnek: 100 TL ana tutar, %0 satış ve %4,8 alış maliyetinde müşteri toplamı 100 TL, satış komisyonu 0, tahmini alış komisyonu 4,80 TL ve tahmini net 95,20 TL’dir. Üç taksit dağılımı kuruş yuvarlamasıyla 33,34 + 33,33 + 33,33 TL olabilir. Bunlar örnek oranlardır; gerçek alış teklifi kart ve tutarla belirlenir. Ödeme ayrıntısını okuyun. Kart seçilmeden totalMinor, alış komisyonu ve net alanları bulunmayabilir veya null olabilir; sıfır varsaymayın. Gerçek seçim sonrası komisyon/toplam/taksit alanları sabitlenir. netMinor, tekliften hesaplanan tahmini nettir; banka valörü, kesin mutabakat veya muhasebe kaydı değildir. Başlatılmış bir denemenin sonucu belirsizse sağlayıcı durumunu sorgulayın. Bu çağrı mevcut denemeyi kontrol eder; çekim/iade göndermez. Cevabı paymentId, status, verification ve reconciliation içerir; komisyonlar ve bağlantı için ayrıntıyı yeniden okuyun. Başlatılmamış talepler bu sorguya uygun değildir. HTTP 200, 3D dönüş sayfası veya API makbuzundaki succeeded tek başına Ödendi anlamına gelmez. verification=query_unavailable, review_required veya sağlayıcıda bulunamayan sonuçta yeni çekim başlatmayın. Sürekli sık sorgu yerine istek sınırlarına uygun aralıklarla kayıt durumunu izleyin.

​
6. Tam iptal veya iade gönderin

Ödeme ayrıntısında canReturn=true ve pozitif remainingMinor varsa tam iptal/iade talep edilebilir. amountMinor güncel kalan çekim tutarının tamamı olmalıdır. Ana tutar 100 TL, müşteriden çekilen toplam 103 TL ise iade tutarı 10300 kuruştur. Bu çağrı için ayrı iş niyetine ait kalıcı Idempotency-Key kullanın. Kısmi tutar 422 BANKPOS_FULL_RETURN_REQUIRED üretir. Ödenmiş kayıt, aynı firma/ortam ve sağlayıcının mali uygunluk koşulları ayrıca denetlenir. Gün sonu ve iade uygunluğu sağlayıcıya bağlıdır. returnOperations[].state=verified, kind=void|refund, returnedMinor ve remainingMinor alanlarını inceleyin. Bekleyen veya belirsiz sonuçta aynı mali isteği yeni anahtarla göndermeyin; mevcut ödemeyi sorgulayın. Tamamlanmış iptal/iade tekrarında yeni mali gönderim oluşturulmaz.

​
İşlem makbuzu ve ödeme durumu farklıdır

POST /payments ve POST /payments/{paymentId}/returns çağrıları genel işlem takibi makbuzu üretir. Göreli yollar burada /apps/bankpos köküne göredir. Makbuzdaki succeeded, talebin API tarafından işlendiğini gösterir. Ödemenin/iptal/iadenin mali doğruluk kaynağı ödeme kaydının doğrulanmış durumudur. Aynı anahtar ve farklı içerik 409 IDEMPOTENCY_PAYLOAD_CONFLICT üretir. Tamamlanmış tekrar cevabı ayrıntı yerine makbuz ve güvenli kimlikler içerir; paymentId ile ayrıntıyı okuyun. Genel makbuz dispatching, review_required veya provider_accepted durumunda kalmışsa yeni anahtar üretmek işlemi yeniden başlatma izni vermez. GET /apps/operations/{operationId} ile makbuzu ve ödeme kaydını okuyun. Sağlayıcı doğrulaması için yalnız mevcut ödeme sorgusunu kullanın. E-Pos makbuzunu okumak için de açık epos:read veya epos:write izni gerekir.

​
Hesap yaşam döngüsü ve destek sınırları

  • Hesapları listeleyin; arşivlenmiş hesaplar için status=archived gönderin. Hesap adı/sağlayıcı/durum ve sayfalama desteklenir.
  • Pasifleştirme ve arşivleme hesap güncelleme üzerinden yapılır. İşlem geçmişi korunur.
  • Silme yalnız işlem/faaliyet kaydı olmayan hesap için geçerlidir.
  • Varsayılan hesabı seçin. Ortam/para birimi başına tek uygun aktif hesap atanabilir; liste bütün olarak değiştirilir.
  • Ödeme taleplerini hareket listesinden izleyin. Liste tutarı, kart seçilmeden ana tutar; sonrasında çekim toplamıdır. Komisyon analizi için ayrıntıyı kullanın.
  • Kayıtlı kart, tekrarlı tahsilat, kısmi iade, genel müşteri webhook’u, başlatılmamış talebi API ile kapatma ve otomatik cari/muhasebe mahsubu sunulmaz.
E-Pos API referansı · OpenAPI · Manuel kabul