Plata cu cardul, evenimente și căderi

Plata cu cardul

Pui "type": "2" la plată, fără rrn. POSfix deschide ecranul de plată al băncii peste aplicația ta, clientul apropie cardul, iar după răspuns ecranul se închide și revii în aplicația ta. Ecranul POSfix nu apare.

Terminal	Aplicația băncii
PAX cu SPS (MICB, VICB)	serviciul SPS al terminalului
Sunmi cu Ashburn SmartPOS (MAIB, VICB)	SmartPOS
Telefon cu TapXphone	TapXphone

Pe Sunmi și TapXphone, POSfix deschide aplicația băncii la plata cu cardul, la card.void, card.refund și la închiderea zilei bancare de după report.z. Android permite asta doar cât aplicația ta e pe ecran și legată la POSfix; SDK-ul pune singur flag-ul cerut de Android 14+. Dacă aplicația ta comandă din fundal, dă-i lui POSfix permisiunea „Afișare peste alte aplicații”.

Pe PAX cu SPS nu e nevoie de nimic din toate acestea. Dacă Android refuză deschiderea, plata întoarce CARD_PAYMENT_DECLINED.

Dacă vânzarea nu se finalizează după ce cardul a fost aprobat, POSfix încearcă singur să anuleze plata la bancă. Asta se întâmplă când alt card din aceeași vânzare e refuzat, când bonul nu ajunge la SFS sau când altă operațiune fiscală ține terminalul ocupat.

MIA QR

Pe Sunmi cu SmartPOS Victoriabank și pe TapXphone, când banca oferă MIA QR, clientul îl poate alege chiar în ecranul băncii, în locul cardului. Tu trimiți tot "type": "2". POSfix fiscalizează plata ca „alt instrument de plată” (ACPS 7), iar în răspuns cardPaymentResult.isMiaQr e true.

Evenimentele

Cu setEventListener primești etapele comenzilor, ca să le arăți pe ecranul tău. Fiecare eveniment are type, requestId și data. Evenimentele ajung la toate aplicațiile conectate, deci le filtrezi după requestId.

// sent = ce a întors posfix.execute(...) pentru vânzarea curentă
posfix.setEventListener { event ->
    if (event.optString("requestId") != sent.requestId) return@setEventListener
    when (event.getString("type")) {
        "cardPaymentStarted" -> showMessage("Apropiați cardul")
        "fiscalizing" -> showMessage("Se emite bonul…")
        "printFailed" -> showMessage("Bonul nu s-a tipărit — verifică hârtia")
    }
}

type	Ce s-a întâmplat
commandStarted / commandFinished	Comanda a început / s-a terminat. data.success spune cum.
cardPaymentStarted	S-a deschis ecranul băncii și se așteaptă cardul.
cardPaymentApproved / cardPaymentDeclined	Răspunsul băncii.
fiscalizing	Bonul pleacă la SFS.
mevRetry	SFS n-a răspuns. POSfix reîncearcă: attempt, maxAttempts, secondsLeft.
fiscalized	Bonul e emis: receiptNumber, fiscalCode.
saleFailed	Bonul nu s-a emis la SFS. POSfix a încercat să anuleze cardurile aprobate.
printing / printed / printFailed	Tipărirea bonului. Merge separat de răspuns; printed sau printFailed vin de obicei după el.
cancelRequested	POSfix a primit cererea de oprire.

Nu aștepți hârtia ca să închizi vânzarea pe ecranul tău. La printFailed, după ce rezolvi imprimanta, trimiți sale.reprint cu saleId: iese originalul, nu un duplicat.

Oprirea unei vânzări

posfix.cancel(sent.requestId) oprește o vânzare cât se mai poate:

• Înainte de card: vânzarea nu mai pornește.
• Cât clientul e pe ecranul băncii: aplicația băncii nu se poate închide din afară, dar clientul poate renunța pe ea. Dacă totuși cardul se aprobă, POSfix îl anulează imediat.
• Cât POSfix reîncearcă SFS: așteptarea se întrerupe, iar vânzarea se oprește.
• După ce bonul fiscal e emis: oprirea nu mai are efect. Bonul nu se poate retrage.

O vânzare oprită întoarce SALE_CANCELLED. Doar aplicația care a trimis comanda o poate opri.

Căderi și reluare

Aplicația ta cade în mijlocul unei vânzări. POSfix termină vânzarea oricum. La repornire trimiți request.result cu cheia vânzării și afli rezultatul. Vezi Cheia de idempotență.

POSfix se oprește în mijlocul unei vânzări. SDK-ul închide pe loc comenzile în curs cu POSFIX_DISCONNECTED și anunță onDisconnected. Când POSfix pornește din nou, inclusiv după o actualizare, SDK-ul se leagă singur și anunță onConnected. Apoi verifici cu request.result.

Terminalul se repornește. POSfix pornește singur după boot, fără ecran.

Prima comandă după o pornire la rece durează câteva secunde. POSfix își pornește serviciile, iar cererile tale așteaptă în coadă, nu se pierd. Dacă nu pornește în 45 s, primești ENGINE_NOT_READY.

Ziua fiscală

Ziua fiscală ține 24 de ore de la primul bon. După ce expiră, vânzările întorc FISCAL_DAY_EXPIRED până trimiți report.z. Dacă terminalul are raportul Z automat pornit, POSfix îl emite singur la ora setată, chiar și cu ecranul închis. Pe Sunmi, închiderea zilei bancare care urmează deschide SmartPOS, deci are nevoie de permisiunea „Afișare peste alte aplicații”.