Platební brána

Právě čtete integrační dokumentaci platební brány MúzaPay.

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í“) - od API verze 2.

• 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í váš e-shop platby rozložit na části (tzv. split payments).

Postup integrace

1. Vygenerujte si pár podpisových klíčů podle návodu v https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/786435.

2. Požádejte o přístup do testovacího prostředí brány na support@benefit-plus.cz , poskytněte následující údaje:

   1. jméno partnera/integrátora (subjektu)

   2. IČO 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 e-shop - CZ, SK

   8. veřejné jméno e-shopu, které chcete zobrazovat zákazníkům

   9. váš testovací veřejný podpisový klíč.

3. Obdržíte přístupové údaje (eshopId, heslo) které budete potřebovat pro zkušební provoz.

4. Implementujte a vyzkoušejte integraci vašeho e-shopu na bránu v testovacím prostředí

   1. V případě technických problémů se obraťte na support@benefit-plus.cz. Detaily vizte v https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/753665/Platebn+br+na#%C5%98e%C5%A1en%C3%AD-probl%C3%A9m%C5%AF

5. Proveďte testovací scénáře specifikované v kapitole Integrační testy.

6. Vygenerujte si produkční podpisový pár klíčů a privátní klíč bezpečně uložte.

7. Oznamte připravenost na přechod do produkčního provozu (provedení testů) na support@benefit-plus.cz.

   1. V emailu uveďte veřejné jméno vašeho eshopu.

8. MúzaPay ověří integraci a naplánuje s vámi předprodukční ověření.

9. Společně v produkčním prostředí provedete:

   1. nastavení a výměnu přístupových údajů, výměnu a nastavení veřejného podpisového klíče

   2. předprodukční ověření funkčnosti e-shopu.

10. MúzaPay přepne bránu do produkčního režimu a tím je integrace dokončena.

API platební brány

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) a jsou v časové zóně UTC.

• Parametry typu string, obsahující řetězec nulové délky nebo null 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í.

Průběh platby

Open

1. Zákazník si v e-shopu zvolí placení platební metodou “MúzaPay“.

2. Back-end e-shopu získá z back-endu platební brány přístupový token, a jeho použitím iniciuje platbu. Tím získá identifikátor platby a dynamické URL na UI brány.

3. E-shop otevře prohlížeč zákazníka na dynamickém URL brány.

4. Zákazník načte a potvrdí platbu v mobilní aplikaci. V tomto kroku není vyžadována žádná činnost e-shopu.

5. Brána presměruje prohlížeč zákazníka zpět do e-shopu, nebo e-shop načte nový stav platby z back-endu brány.

6. E-shop načte nový stav platby z back-endu brány (pokud to ještě neudělal).

7. E-shop zobrazí výsledek platby zákazníkovi.

Sekvenční diagram platby

Open

Řešení problémů

V platbě, která přešla do některého z konečných stavů už nelze dále pokračovat. Pokud ještě nemáte zaplacený nákup/košík, musíte požádat o novou platbu a můžete použít stejný identifikátor košíku orderReferenceCode.

Nespoléhejte na to, že přesměrování prohlížeče zákazníka vždy proběhne, protože to nelze zaručit. Ke zjištění stavu platby vždy použijte Sledování stavu platby.

Platbu, u které z jakéhokoliv důvodu neznáte jistě její stav, byste se měli pokusit stornovat. Nejlépe s kratším časovým odstupem umožňujícím případné zotavení z výpadku konektivity nebo funkčnosti brány. 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 provedení platby (hodnota paymentDateTime nebo alespoň přibližný čas).

V případě žádosti o technickou podporu během integrace je ideální předat kompletní log celého požadavku i případné odpovědi včetně HTTP hlaviček na support@benefit-plus.cz.

Podrobnosti

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

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/1376286

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/884766

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/983054

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/983043

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/786435

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/884755