Integrace pokladen

Právě čtete integrační dokumentaci služby MúzaPay pro pokladní systémy (tzv. POS API).

Tuto službu použijete z vašeho pokladního systému k integraci plateb zaměstnaneckými benefity prováděných mobilní aplikací MúzaPay - tedy bez použití starší karty Benefit Plus.

Platba je postavena na principu prezentace čarového kódu v mobilu zákazníka. Čarový kód naskenuje pokladní skenerem pokladny. Platby autorizuje zákazník v nové mobilní aplikací MúzaPay s použitím biometrie nebo PINu. Pro autorizaci platby se už nepoužívají SMS a pokladní tedy po zahájení platby nic dalšího nezadává.

Souběh s Benefit Plus POS integrací

Pokud už máte implementovánu integraci pokladny na Benefit Plus PartnerService – tedy na program používající k identifikaci zákazníka kartu Benefit Plus a chcete starou integraci zachovat, můžete služby rozlišit přídáním nové platební metody “MúzaPay“ navíc k původní “Benefit Plus” a podle výběru platební metody pak upravte váš pokladní systém tak, aby použil buď starou, nebo novou integraci.

Kategorie produktu

MúzaPay potřebuje znát produktovou kategorii nákupu, aby mohl čerpat ze správných rozpočtů a aplikovat na platbu zákonná pravidla čerpání zaměstnaneckých benefitů. U každé platby jde o jednoduchý výběr ze tří kategorií:

Cestování, turistika, kultura, sport, tištěné knihy, vzdělávání (“volný čas”)
Zboží nebo služby zdravotního, léčebného, hygienického a obdobného charakteru od zdravotnických zařízení nebo pořízení zdravotnických prostředků na lékařský předpis (“zdraví“)
Jídlo a nealkoholické nápoje (“stravenky”).

MúzaPay neumožnuje společnou platbu za košík, který obsahuje kombinaci těchto kategoríí. Pokud takovou situaci potřebujete řešit, musí vaše pokladna platby rozložit na části (tzv. split payments).

Postup integrace

Požádejte o přístup do testovacího prostředí služby na support@benefit-plus.cz
1. Poskytněte následující údaje:
  1. jméno partnera/integrátora (subjektu)
  2. IČ partnera/integrátora
  3. typ subjektu, který se bude připojovat - Partner, Integrátor.
  4. email na technický kontakt
  5. telefon na technický kontakt
  6. jméno a příjmení technického kontaktu
  7. zemi, ve které chcete registrovat POS integraci - CZ, SK
  8. seznam obchodů/poboček ve kerých chcete provozovat integrované pokladny.
Od MúzaPay obdržíte identifikátor(y) obchodu storeId a tajný klíč(e), který budete potřebovat pro zkušební provoz.
Implementujte a vyzkoušejte integraci vašeho systému na službu v testovacím prostředí.
1. V případě technických problémů se obraťte na support@benefit-plus.cz.
Proveďte testovací scénáře specifikované v Integrační testy - POS.
Oznamte připravenost na přechod do produkčního provozu.
MúzaPay ověří integraci, nastaví s vámi tajné klíče do produkčního prostředí, a naplánuje s vámi předprodukční ověření.
Společně provedete předprodukční ověření.
MúzaPay přepne službu do produkčního režimu.

POS API

Obecná pravidla:

Aplikační rozhraní (API) je specifikováno podle OpenAPI standardu verze 3: https://swagger.io/specification/v3/ .
API je REST-ful.
Přenosovým protokolem je HTTPS.
Standardní datovou strukturou je JSON.
Pro veškerou komunikaci je použito kódování UTF-8.
Parametry reprezentující data a časy jsou formátované podle Internet Date/Time Format - RFC 3339 kapitoly 5.6 (profil ISO 8601) date-time a jsou vždy v časové zóně UTC.
- Výjimkou z tohoto formátu jsou datové údaje posílané v URL, ve kterých jsou vypuštěny oddělovače, milisekundy a indikátor časové zóny a zůstávají tedy jen číselné hodnoty data, hodin, minut a vteřin bez mezer.
Parametry typu string, obsahující řetězec nulové délky budou považovány za nepřijaté.
Parametry typu string, začínající nebo končící na neviditelné znaky, nebo obsahující pouze neviditelné znaky, budou odmítnuty jako nevalidní.

Specifikace OpenAPI/swagger je v	OpenAPI Dokument - POS
Testovací služba je dostupná na	https://int.pos.pay.muza.app
Produkční služba je dostupná na	https://pos.pay.muza.app

Průběh platby

Zákazník sdělí pokladní, že chce platit MúzaPay, tzn. prostředky z programu MúzaPay v mobilu.
Pokladní uzavře košík v pokladně a vybere platební metodu MúzaPay.
1. Pokladna instruuje pokladní, že má naskenovat čarový kód z mobilní aplikace MúzaPay zákazníka.
Zákazník otevře mobilní aplikaci MúzaPay a ukáže čarový kód pokladní.
Pokladní kód naskenuje.
Pokladna iniciuje platbu voláním cloudové služby MúzaPay. V požadavku předá načtený kód.
Pokladna sleduje průběh platby, dokud se platba nedostane do konečného stavu.
Pokladna zobrazí výsledek platby pokladní.
Mobilní aplikace zobrazí výsledek platby zákazníkovi.

Sekvenční diagram platby

Řešení problémů

Služba může ve výjimečných případech vrátit odpověď (HTTP 472), která indikuje potřebu znovu naskenovat čarový kód. V takovém případě instruujte pokladní, že má skenování kódu zopakovat a vytvořte novou platbu.

V platbě, která přešla do jednoho z koncových stavů (CANCELED, DECLINED, EXPIRED) už nelze dále pokračovat. Pokud ještě nemáte zaplacený nákup/košík (tzn. stav PAID), vytvořte novou platbu ve které můžete použít stejný identifikátor košíku orderReferenceCode.

Platbu, u které z jakéhokoliv důvodu neznáte jistě její stav, byste se měli pokusit stornovat. Nejlépe s určitým časovým odstupem umožňujícím případné zotavení z výpadku konektivity nebo funkčnosti služby. Pokusy o storno můžete v případě neúspěchu opakovat, ale vyhněte se nekonečné smyčce. Rozumný počet pokusů o storno je 3, ideálně provedených s progresivně se zvyšujícím časovým intervalem.

V případě reportování problémů s platbou podpoře MúzaPay je klíčové oznámit paymentId, orderReferenceCode a čas, kdy byla platba provedena (hodnota paymentTimestamp nebo alespoň datum a přibližný čas).

Podrobnosti

Následující kapitoly obsahují podrobnější informace doplňující POS API specifikaci.