FiskalPRO technical documentation

Dokumentácia SK

Tento dokument popisuje integráciu FiskalPRO platobnej brány. Je určený pre vývojárov..

Pre rýchlu integráciu je k dispozícii aj dokumentácia swagger, ktorá je dostupná pre vývojárov.

Registrácia obchodníka

Každý obchodník musí mať vytvorený prístup do portálu FiskalPRO. Na umožnenie komunikácie s platobnou bránou je dôležité špecifikovať informácie o účte obchodníka. Tieto údaje sú použité pri všetkých budúcich platobných transakciách.

Komunikácia s platobnou bránou je jednoduchá. Je potrebné poslať všetky povinné polia na platobnú bránu pomocou JSON reťazca na definovaný endpoint.

Všetky potrebné endpointy budú špecifikované pre každého obchodníka v zmluve.

Autentifikácia

API používa Bearer token na autorizáciu obchodníka. Je potrebný na vytváranie akýchkoľvek platieb. Je zahrnutý v hlavičke požiadavky.

Každá platba má svoj vlastný prístupový token, ktorý je vytvorený po vytvorení požiadavky na platbu.

Testovacie karty

Tieto karty (Mastercard) sú dostupné na testovacie účely:

Životný cyklus platby

1. Žiadosť o platbu. Prehliadač držiteľa karty odošle žiadosť o platbu za jeho objednávku kartou obchodníkovi.
2. Vytvorenie platby. Obchodník odošle žiadosť o vytvorenie platobnej transakcie do FiskalPay.
3. Presmerovacia URL s kódom. FiskalPay odošle presmerovaciu URL s kódom späť obchodníkovi.
4. Presmerovacia URL. Obchodník presmeruje prehliadač držiteľa karty na novú platbu.
5. Platba dokončená. IFrame sa zavrie.
6. Oznámenie o platbe. Poskytovateľ odošle oznámenie o platbe do FiskalPay vrátane stavu platby.
7. Oznámenie obchodníkovi. FiskalPay oznámi obchodníkovi stav platby. Oznámenie o stave platby
8. Získanie stavu platby. Prehliadač držiteľa karty odošle žiadosť o stav platby do FiskalPay.
9. Stav platby. FiskalPay odošle stav platby do prehliadača držiteľa karty.

Spracovanie platby

Povinným poľom je Bearer token. Tento token obchodník získa počas registrácie.

Získajte prístupový kód a vytvorte platbu.

Platba môže byť realizovaná dvoma spôsobmi (paymentType).

Priama - prehliadač je presmerovaný na URL, kde si používateľ môže vybrať platobnú metódu a vyplniť potrebné údaje.

Email - viz Platba emailem (Pay By Link).

Po správnom odoslaní žiadosti o platbu je zákazník presmerovaný na platobnú bránu FiskalPRO.

Existujú tri spôsoby, ako môžu používatelia zaplatiť:

• platobnou kartou
• cez GooglePay
• cez ApplePay

Keď chce používateľ z nejakého dôvodu zaplatiť neskôr, je tu možnosť zaplatiť cez platobný odkaz, ktorý je odoslaný na email používateľa.

Na konci platby prehliadač dostane oznámenie o stave platby a presmeruje sa na webovú stránku obchodníka.

Stav platby a platnosť

Pre stav platby pozri MerchantPaymentStatus
Platnosť platby funguje nasledovne podľa typu platby (Defaultné hodnoty sú uvedené pre prípad chybného nastavenia):

Priama platba: Platnosť je nastavená na 5 minút. (Defaultne 5 minút)

Platba emailom: Pre emailovú platbu sa použije hodnota zaslaná v parametri EmailTtl. Ak táto hodnota nie je špecifikovaná, použije sa hodnota z konfigurácie 24h (Defaultne 24 hodín). Maximálna hodnota platnosti je 31 dní. (Defaultne 31 dní)

Pre ostatné typy platieb: Hodnota je nastavená na 5 minút.

Platnosť nie je presná hodnota ale skôr časové rozmedzie Pri priamej platbe získa užívateľ ešte dodatočný čas 5 minút v UI pre vyhotovenie platby z jeho strany. Ďalej sa kontrola platnosti platieb odohráva v cykloch. Preto je potrebné brať do úvahy, že vyššie spomínané hodnoty platnosťou sú časové údaje "minimálnej" platnosti a skutočná môže byť viac.

Platby

Štandardné platby

Zákazníci musia odoslať objekt PaymentCreateRequestData ako žiadosť o vytvorenie platby.
Odpoveď na platbu je odoslaná po prijatí žiadosti o platbu. Odpoveď obsahuje URL adresu platobnej brány, na ktorú musia byť zákazníci presmerovaní.

Platba emailom (Pay By Link)

Platba emailom je špeciálny druh platby. Je vygenerovaná nová URL platby, ktorú je možné zaslať zákazníkovi. V žiadosti o vytvorenie platby je potrebné nastaviť parameter "paymentType" na hodnotu "email" a zadať hodnotu emailTtl viď. Žiadosť o platbu. Má dlhšiu dobu platnosti ako priama platba viď. Stav platby a platnosť.

Platba kartou

Nižšie je obrázok platobnej brány FiskalPRO, kde zákazníci vyplnia všetky potrebné údaje pre úspešnú platbu kartou.

Tu zákazník vyplní povinné polia potrebné pre úspešnú platbu. V pravom hornom rohu je podpora šiestich jazykov - angličtina, čeština, slovenčina, poľština, maďarčina, rumunčina.

Zákazník musí vyplniť tieto polia:

• Meno na karte
• Číslo karty
• Dátum expirácie
• Bezpečnostný kód

Je tu tiež možnosť uložiť kartu pre ďalšie použitie.

Platba cez GooglePay

Nasledujúci obrázok ukazuje obrazovku, keď používateľ vyberie platbu cez GooglePay.

Platba cez ApplePay

Nasledujúci obrázok ukazuje obrazovku, keď používateľ vyberie platbu cez ApplePay.

Opakované platby

Opakované platby je špeciálny typ platieb, pre ktorý sa postupuje rovnako ako pri zakladaní normálnej platby, akurát s rozdielom, že request na založenie platby obsahuje špeciálne dáta.

Pri založení prvej platby sa platba ihneď vykoná a nastaví sa scheduler, ktorý naplánuje ďalšie opakovanie platby. Presný čas a deň založenia opakovanej platby je dôležitý, pretože z neho sa počítajú ďalšie opakovania.

Body requestu pre založenie platby musia obsahovať klasické povinné dáta pre bežnú platbu obohatené o nasledujúce:

"paymentType" : "Recurrent"

"Recurrence" objekt

Po každom vykonaní platby by sa mala odoslať merchantu notifikácie s detailmi o stave vykonanej platby viď Oznámenie o stave platby

Príklad

{

  "paymentType": "recurrent",

  "Recurrence":
  {
      "period":"1",

      "cycle":"day",

      "dateTo":"2026-10-11"
  }
}

API referencie

Skratky :

• M - povinné pole.
• O - voliteľné pole.

Platobné operácie

Žiadosť o platbu

Vytvorenie žiadosti o platbu

[ POST ] `/api/merchant/payment/create`

Hlavičky žiadosti o platbu

Telo žiadosti o platbu objekt PaymentCreateRequestData

Jednoduchý príklad žiadosti o platbu:

{
  "merchantPaymentId": "{{payment-guid}}",
  "amount": "123",
  "orderNo": "123456",
  "basket": {
    "header": {
      "documentNumber": "abc123"
    },
    "payments": [
      {
        "paymentId": 2,
        "value": 123
      }
    ],
    "customer": {
      "customerNumber": "58633",
      "cardNumber": "495978",
      "externalUId": "668855"
    },
    "items": [
      {
        "name": "Test item",
        "vatRate": 0.21,
        "quantity": 2,
        "measureUnit": "ks",
        "originalUnitPrice": 20.5,
        "unitPrice": 23.5,
        "priceTotal": 47,
        "priceVatBaseTotal": 40,
        "priceVatTotal": 7,
        "itemRounding": 0
      }
    ]
  },
  "customer": {
    "cardholderName": "Tester Name",
    "email": "{{cardholder email}}"
  },
  "redirectUrl": "https://example.com/merchant-notify-url"
}

Kompletný príklad žiadosti o platbu:

{
    "merchantPaymentId": "{{payment-guid}}",
    "language": "cs-CZ",
    "paymentType" : "email",
    "emailTtl" : "31",
    "message" : "some message",
    "amount": "123",
    "orderNo": "123456",
    "token:": "4ed8df5d-9cc4-42a0-9e86-5405492bb3b9",
    "token:": "6a4ee8f2-1636-4f22-a7a9-635d7e9217b5",
    "basket": {
        "header": {
            "documentNumber": "abc123",
            "reference": "123456",
            "rounding": 0,
            "text1": "some text 1",
            "text2": "some text 2",
            "text3": "some text 3"
        },
        "payments": [{
            "paymentId": 2,
            "value": 123,
            "description": "payment description"
        }],
        "customer": {
            "customerNumber": "58633",
            "cardNumber": "495978",
            "externalUId": "668855"
        },
        "items": [{
            "article": "Item 558"
            "chr1": "XL",
            "chr2": "black",
            "ean": "item bar code",
            "name": "Test item",
            "vatRate": 0.21,
            "quantity": 2,
            "measureUnit": "ks",
            "originalUnitPrice": 20.5,
            "unitPrice": 23.5,
            "priceTotal": 47,
            "priceVatBaseTotal": 40,
            "priceVatTotal": 7,
            "itemRounding": 0,
            "externalUId": "Ext Id",
            "text1": "some text",
            "textLong1": "some long text"
        }]
    },
    "customer": {
        "cardholderName": "Tester Name",
        "mobilePhone": {
            "cc": "420",
            "subscriber": "777123123"
        },
        "homePhone": {
            "cc": "420",
            "subscriber": "534123123"
        },
        "workPhone": {
            "cc": "420",
            "subscriber": "778123123"
        },
        "billAddrLine1": "Testing street 51/17",
        "billAddrLine2": "second floor",
        "billAddrLine3": "flat no. 5",
        "billAddrPostCode": "15000",
        "billAddrCity": "Praha",
        "billAddrState": "10",
        "billAddrCountry": "203",
        "email": "{{cardholder email}}",
        "shipAddrLine1": "Testing street 51/17",
        "shipAddrLine2": "second floor",
        "shipAddrLine3": "flat no. 5",
        "shipAddrPostCode": "15000",
        "shipAddrCity": "Praha",
        "shipAddrState": "10",
        "shipAddrCountry": "203"
    },
    "redirectUrl": "https://example.com/merchant-notify-url"
}

Platba Na požiadanie

Pri prvej žiadosti o platbu musíte vytvoriť platbu s typom OnDemand Po dokončení platby zákazníkom sa token získa požiadaním o stav platby. Pri následných platbách odošlete token v žiadosti o platbu, ID platby bude vrátené, ale presmerovacia URL už nebude. Platba prebehne bez interakcie zákazníka. Po dokončení platby budete upozornení rovnako ako pri štandardnej platbe.

Prvá žiadosť o platbu OnDemand:

{
  "merchantPaymentId": "{{payment-guid}}",
  "amount": "123",
  "orderNo": "123456",
  "paymentType": "OnDemand",
  "basket": {
    "header": {
      "documentNumber": "abc123"
    },
    "payments": [
      {
        "paymentId": 2,
        "value": 123
      }
    ],
    "customer": {
      "customerNumber": "58633",
      "cardNumber": "495978",
      "externalUId": "668855"
    },
    "items": [
      {
        "name": "Test item",
        "vatRate": 0.21,
        "quantity": 2,
        "measureUnit": "ks",
        "originalUnitPrice": 20.5,
        "unitPrice": 23.5,
        "priceTotal": 47,
        "priceVatBaseTotal": 40,
        "priceVatTotal": 7,
        "itemRounding": 0
      }
    ]
  },
  "customer": {
    "cardholderName": "Tester Name",
    "email": "{{cardholder email}}"
  },
  "redirectUrl": "https://example.com/merchant-notify-url"
}

Druhá žiadosť o platbu OnDemand - bez interakcie zákazníka:

{
  "merchantPaymentId": "{{payment-guid}}",
  "amount": "123",
  "orderNo": "123456",
  "paymentType": "OnDemand",
  "token": "4ed8df5d-9cc4-42a0-9e86-5405492bb3b9",
  "basket": {
    "header": {
      "documentNumber": "abc123"
    },
    "payments": [
      {
        "paymentId": 2,
        "value": 123
      }
    ],
    "customer": {
      "customerNumber": "58633",
      "cardNumber": "495978",
      "externalUId": "668855"
    },
    "items": [
      {
        "name": "Test item",
        "vatRate": 0.21,
        "quantity": 2,
        "measureUnit": "ks",
        "originalUnitPrice": 20.5,
        "unitPrice": 23.5,
        "priceTotal": 47,
        "priceVatBaseTotal": 40,
        "priceVatTotal": 7,
        "itemRounding": 0
      }
    ]
  },
  "customer": {
    "cardholderName": "Tester Name",
    "email": "{{cardholder email}}"
  },
  "redirectUrl": "https://example.com/merchant-notify-url"
}

Požiadavka na informácie o platbe

[ POST ] /api/merchant/payment/info

Telo požiadavky na informácie o platbe objekt PaymentInfoRequestData

Príklad požiadavky na informácie o platbe:

{
    "paymentId": {{payment-guid}}
}

Odpoveď na vytvorenie platby

Telo odpovede na vytvorenie platby objekt PaymentCreateResponse

Príklad odpovede na vytvorenie platby (priama):

{
  "paymentId": "18c18413-2b2e-4b98-b08a-442a39b479b1",
  "redirectUrl": "https://staging.fiskalpay.eu/?code=d8d16d82-eb5c-48dc-8cf7-add9e67f23f3"
}

Príklad odpovede na vytvorenie platby (email):

{
  "paymentId": "33ef6c57-df28-40cf-9395-9b03fa048cfe",
  "redirectUrl": "https://staging.fiskalpay.eu/?key=fpk0431b3ff5be374876af50ae7ac283cd0bab2cea077482c130731fd4d5b8e5b7f435f5ef23ca80d2be871468bb98bfc209"
}

Príklad odpovede na vytvorenie platby (OnDemand) - prvá:

{
  "paymentId": "18c18413-2b2e-4b98-b08a-442a39b479b1",
  "redirectUrl": "https://staging.fiskalpay.eu/?code=d8d16d82-eb5c-48dc-8cf7-add9e67f23f3"
}

Príklad odpovede na vytvorenie platby (OnDemand) - ďalšia:

{
  "paymentId": "33ef6c57-df28-40cf-9395-9b03fa048cfe",
  "redirectUrl": null
}

Odpoveď na informácie o platbe

Telo odpovede na informácie o platbe object PaymentInfoResponse

Objekty

Košik

BasketHeader

BasketPayment

BasketCustomer

BasketItem

CardHolder

CardHolderPhoneNumber

Enums

PaymentReferenceType

PaymentId (v objekte BasketPayment)

BasketItemMeasureUnit

MerchantPaymentStatus

Recurrence

Oznámenie o stave platby

Oznámenie obchodníka o stave platby sa zasiela na NotifyUrl vo forme JSON objektu obsahujúceho paymentId a status.

Telo tejto žiadosti vyzerá nasledovne:

Overenie oznámenia

Pri odosielaní oznámenia o stave platby v tele žiadosti je tiež možnosť zabezpečiť autentickosť oznámenia prostredníctvom podpisu oznámenia v hlavičke žiadosti. Podpis oznámenia má kľúč Signature a jeho hodnota je hašovaný reťazec. Tento hašovaný reťazec bol vytvorený z dvoch častí: parametre objektu oznámenia z tela a ako kľúč bol použitý SignatureSalt ktorý bol automaticky vygenerovaný a vrátený v tele odpovede pri vytvorení MerchantMethodTerminal. Ak ste stratili hodnotu SignatureSalt, je možné vygenerovať novú prostredníctvom odoslania POST žiadosti na endpoint merchants/{merchantId}/methods/{methodId}/terminals/{terminalId}/regenerate.

Na overenie autentickosti oznámenia postupujte nasledovne:

1. Vypočítajte vlastný podpis Kombinujte parametre prijatého tela oznámenia ako reťazec v tvare ${{htmlContent}}quot;{paymentId}{status}". Táto hodnota musí byť hašovaná (HMAC) pomocou algoritmu SHA256 a hodnoty SignatureSalt ako kľúča na hašovanie. Posledný krok je odstránenie znaku "-" z reťazca. Konečný výsledok by mal byť reťazec s veľkými písmenami a mal by byť dlhý 32 bajtov.

2. Porovnanie Porovnajte vygenerovaný hašovaný kód s prijatým kódom v hlavičke žiadosti.