FiskalPRO technical documentation

Dokumentace CZ

Tento dokument popisuje integraci FiskalPRO platební brány. Je určen pro vývojáře.

Pro rychlou integraci je také k dispozici dokument Swagger, který je k dispozici pro vývojáře.

Zřízení obchodníka

Každý obchodník potřebuje mít vytvořený přístup do portálu FiskalPRO. Aby byla umožněna komunikace s platební bránou, je důležité specifikovat informace o účtu obchodníka. Tyto údaje jsou používány ve všech budoucích platebních transakcích.

Komunikace s platební bránou je jednoduchá. Je třeba zaslat všechna povinná pole platební bráně ve formátu json na definovaný koncový bod.

Všechny potřebné koncové body budou specifikovány pro každého obchodníka ve smlouvě.

Autentizace

API používá Bearer token pro autorizaci obchodníka. Je nutný pro vytvoření jakýchkoli plateb. Je zahrnut v záhlaví požadavku.

Každá platba má svůj vlastní přístupový token, který je vytvořen po vytvoření žádosti o platbu.

Testovací karty

Tyto karty (Mastercard) jsou k dispozici pro testovací účely:

Životní cyklus platby

1. Žádost o platbu. Prohlížeč držitele karty odešle obchodníkovi žádost o zaplacení objednávky kartou.
2. Vytvoření platby. Obchodník odešle žádost o vytvoření platební transakce FiskalPay.
3. Přesměrovací URL s kódem. FiskalPay odešle přesměrovací URL s kódem zpět obchodníkovi.
4. Přesměrovací URL Obchodník přesměruje prohlížeč držitele karty na novou platbu.
5. Platba dokončena. IFrame je uzavřen.
6. Oznámení o platbě. Poskytovatel odešle oznámení o platbě do FiskalPay včetně stavu platby.
7. Oznámení obchodníkovi. FiskalPay informuje obchodníka o stavu platby. Oznámení o stavu platby
8. Získání stavu platby. Prohlížeč držitele karty odešle žádost o stav platby do FiskalPay.
9. Stav platby. FiskalPay odešle stav platby do prohlížeče držitele karty.

Zpracování platby

Povinným polem je Bearer token. Tento token obchodník obdrží během onboardingu.

Získejte přístupový kód a vytvořte platbu.

Platba může být realizována dvěma způsoby (paymentType).

Přímá - prohlížeč je přesměrován na URL, kde uživatel může vybrat platební metodu a vyplnit potřebné údaje.

Email - viz Platba emailem (Pay By Link).

Po provedení správné žádosti o platbu je zákazník přesměrován na platební bránu FiskalPRO.

Existují tři možnosti, jak mohou uživatelé zaplatit:

• platební kartou
• cez GooglePay
• cez ApplePay

Pokud chce uživatel zaplatit později z nějakého důvodu, je zde možnost zaplatit z platebního odkazu, který je zaslán na e-mail uživatele.

Na konci platby obdrží prohlížeč oznámení o stavu platby a přesměruje se na web obchodníka.

Stav platby a platnost

Pro stav platby viz MerchantPaymentStatus

Platnost platby funguje následovně podle typu platby (Defaultní hodnoty jsou uvedeny pro případ chybného nastavení):

Přímá platba: Platnost je nastavena na 5 minut. (Defaultně 5 minut)

Platba emailem: Pro emailovou platbu se použije hodnota zaslaná v parametru EmailTtl. Pokud tato hodnota specifikovaná není, použije se hodnota z konfigurace 24h (Defaultně 24 hodin). Maximální hodnota platnosti je 31 dní. (Defaultně 31 dní)

Pro ostatní typy plateb: Hodnota je nastavena na 5 minut.

Platnost není přesná hodnota ale spíše časové rozmezí Při přímé platbě získá uživatel ještě dodatečný čas 5 minut v UI pro vyhotovení platby z jeho strany. Dále se kontrola platnosti plateb odehrává v cyklech. Tudíž je potřeba brát zřetel, že výše zmíněné hodnoty platností jsou časové údaje "minimální" platnosti a skutečná může být více.

Platby

Standardní platby

Zákazníci musí odeslat objekt PaymentCreateRequestData jako žádost o vytvoření platby. Odpověď na platbu je odeslána po obdržení žádosti o platbu. Odpověď obsahuje URL adresu platební brány, kam musí být zákazníci přesměrováni.

Platba emailem (Pay By Link)

Platba emailem je speciální druh platby. Je vygenerována nová URL platby, kterou lze zaslat zákazníkovi. V žádosti o vytvoření platby je potřeba nastavit parametr "paymentType" na hodnotu "email" a zadat hodnotu emailTtl viz. Žádost o platbu. Má delší dobu platnosti než přímá platba viz. Stav platby a platnost.

Platba kartou

Níže je obrázek platební brány FiskalPRO, kde zákazníci vyplní všechna potřebná pole pro úspěšnou platbu kartou.

Zde zákazník vyplní povinná pole potřebná pro úspěšnou platbu. Na pravém horním rohu je podpora pro šest jazyků - angličtina, čeština, slovenština, polština, maďarština, rumunština.

Zákazník musí vyplnit tato pole:

• Jméno na kartě
• Číslo karty
• Datum vypršení platnosti
• Bezpečnostní kód

Existuje také možnost uložit kartu pro další použití.

Platba přes GooglePay

Další obrázek ukazuje obrazovku, když uživatel vybere platbu přes GooglePay.

Platba přes ApplePay

Další obrázek ukazuje obrazovku, když uživatel vybere platbu přes ApplePay.

Opakované platby

Opakované platby je speciální typ plateb, pro který se postupuje stejně jako při zakládání normální platby, akorát s rozdílem, že request na založení platby obsahuje speciální data.

Při založení první platby se platba ihned vykoná a nastaví se scheduler, který naplánuje další opakování platby. Přesný čas a den založení opakované platby je důležitý, protože z něj se počítají další opakování.

Body requestu pro založení platby musí obsahovat klasické povinné data pro běžnou platbu obohacené o následující:

"paymentType" : "Recurrent"

"Recurrence" objekt

Po každém provedení platby by se měla odeslat merchantu notifikace s detaily o stavu provedené platby viz Oznámení o stavu platby

Příklad

{

  "paymentType": "recurrent",

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

      "cycle":"day",

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

API reference

**Zkratky ** :

• M - povinné pole.
• O - volitelné pole.

Platební operace

Žádost o platbu

Vytvoření žádosti o platbu

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

Záhlaví žádosti o platbu

Tělo žádosti o platbu objekt PaymentCreateRequestData

Jednoduchý příklad žádosti 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í příklad žádosti 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 vyžádání (OnDemand)

Při prvním požadavku na platbu musíte vytvořit platbu s typem OnDemand Po dokončení platby zákazníkem získáte token dotazem na stav platby. Při následných platbách předáte token v požadavku na platbu, ID platby bude vráceno, ale již ne přesměrovací URL. Platba proběhne bez interakce zákazníka. Budete informováni, když bude platba dokončena, stejně jako u standardní platby.

První žádost o platbu na vyžádání (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ý požadavek na platbu OnDemand – bez interakce se zákazníkem:

{
  "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žadavek na informace o platbě

[ POST ] /api/merchant/payment/info

Tělo požadavku na informace o platbě objekt PaymentInfoRequestData

Příklad požadavku na informace o platbě:

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

Odpověď na vytvoření platby

Tělo odpovědi na vytvoření platby objekt PaymentCreateResponse

Příklad odpovědi na vytvoření platby (přímá platba):

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

Příklad odpovědi na vytvoření platby (email):

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

Příklad odpovědi na vytvoření platby (OnDemand) - první:

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

Příklad odpovědi na vytvoření platby (OnDemand) - další:

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

Odpověď na informace o platbě

Tělo odpovědi na informace o platbě objekt PaymentInfoResponse

Objekty

Basket

BasketHeader

BasketPayment

BasketCustomer

BasketItem

CardHolder

CardHolderPhoneNumber

Enums

PaymentReferenceType

PaymentId (v BasketPayment objektu)

BasketItemMeasureUnit

MerchantPaymentStatus

Recurrence

Oznámení o stavu platby

Oznámení obchodníka o stavu platby je zasláno na NotifyUrl jako JSON objekt obsahující paymentId a status.

Tělo tohoto požadavku vypadá takto:

Ověření oznámení

Při zasílání oznámení o stavu platby v těle požadavku je také možnost zajistit autentičnost oznámení pomocí podpisu oznámení v hlavičce požadavku. Podpis oznámení má klíč Signature a jeho hodnota je hashovaný řetězec. Tento hashovaný řetězec je vytvořen ze dvou částí: parametry objektu oznámení z těla a jako klíč byl použit SignatureSalt který byl automaticky generován a vrácen v těle odpovědi při vytvoření MerchantMethodTerminal. Pokud ztratíte hodnotu SignatureSalt, je možné vygenerovat novou odesláním POST požadavku na endpoint merchants/{merchantId}/methods/{methodId}/terminals/{terminalId}/regenerate.

Pro ověření autentičnosti oznámení postupujte takto:

1. Vypočítejte vlastní podpis Kombinujte parametry přijatého těla oznámení jako řetězec ve formátu ${{htmlContent}}quot;{paymentId}{status}". Tuto hodnotu je třeba hashovat (HMAC) pomocí algoritmu SHA256 a hodnoty SignatureSalt jako klíče k hashování. Posledním krokem je odstranění znaku "-" z řetězce. Konečný výsledek by měl být řetězec s velkými písmeny a dlouhý 32 bajtů.

2. Porovnejte Porovnejte vygenerovaný hashovaný kód s přijatým kódem v hlavičce požadavku.