FiskalPRO technical documentation

Documentation EN

This document described the integration of the FiskalPRO payment gateway. It is targeted at developers.

For quick integration there is also a swagger document which is available for developers.

Merchant onboarding

Each merchant needs to have created access into the FiskalPRO portal. To enable communication with payment gateway, it is important to specify merchant account information. These data are used in all future payment transactions.

Payment gateway communication is simple. It is needed to send all mandatory fields to the payment gateway by json string on the defined endpoint.

All needed endpoints will be specified for each merchant in the contract.

Authentication

The API uses Bearer token for merchant Authorization. It is needed for creating any payments. It is included in the request header.

Each payment has its own access token, which is created after create payment request.

Testing cards

These cards (Mastercard) are available for testing purposes :

Payment lifecycle

1. Request for the payment. Cardholder browser sends the request for the pay his order by card to merchant.
2. Create payment. Merchant sends the request for create payment transaction to FiskalPay.
3. Redirect URL with a code. FiskalPay sends a redirect URL with a code back to the merchant.
4. Redirect URL. Merchant redirects Cardholder's browser for a new payment.
5. Payment completed. IFrame is closed.
6. Payment notification. Provider sends payment notification to FiskalPay including payment status.
7. Notify merchant. FiskalPay notifies merchant about payment status. Notification of merchant
8. Get payment status. Cardholder's browser sends request for payment status to FiskalPay.
9. Payment status. FiskalPay sends payment status to cardholder's browser.

Process a payment

As a mandatory field is Bearer token. This token merchant receive during onboarding.

Obtain access code and create payment.

Payment could be realized by two ways (paymentType).

Direct - browser is redirect on url where user could choose payment method and fill needed data.

Email - see Payment by email (Pay By Link)

After the correct payment request is made, the customer is redirected to the FiskalPRO payment gateway.

There are three choices, how users can pay.

• by card
• by GooglePay
• by ApplePay

When a user wants to pay later for some reason, there is an option to pay from the payment link, which is send to the user’s email.

At the end of payment, browser receive notification with payment status and redirect to merchant web side.

Payment status and expiration

For payment status see MerchantPaymentStatus
The validity of the payment works as follows according to the type of payment (Default values ​​are given in case of incorrect settings):

Direct payment: Validity is set to 5 minutes. (Default 5 minutes)

Payment by email: The value sent in the EmailTtl parameter is used for email payment. If this value is not specified, the value from the 24h configuration is used (Default 24 hours). The maximum validity value is 31 days. (Default 31 days)

For other payment types: The value is set to 5 minutes.

Validity is not an exact value, but rather a time range When paying directly, the user gets an additional time of 5 minutes in the UI to make the payment on his part. Furthermore, the payment validity check takes place in cycles. Therefore, it is necessary to take into account that the above-mentioned validity values ​​are time data of "minimum" validity and the actual value may be more.

Payments

Standard payments

Customers have to send object PaymentCreateRequestData as a request for creating payment.
Payment response is sent after receiving a payment request. Response contains the url address of the payment gateway, where customers have to be redirected.

Payment by email (Pay By Link)

Email payment is a special type of payment. A new payment URL is generated that can be sent to the customer. In the request to create a payment, you need to set the "paymentType" parameter to "email" and enter the emailTtl value, see Payment request. It has a longer validity period than direct payment, see Payment status and expiration

Pay by card

Below is a picture of the FiskalPRO payment gateway, where customers fill all needed fields for successful payment by card.

Here the customer fills the mandatory fields needed for the successful payment. There is support for two languages on the right upper corner - English and Czech for now.

Customer have to fill these fields :

• Name on the card
• Card number
• Expiration date
• Security code

There is also a possibility to save the card for the next usage.

Pay by GooglePay

Next picture shows the screen, when a user selects pay by GooglePay.

Pay by ApplePay

Next picture shows the screen, when a user selects pay by ApplePay.

Recurring payments

Recurring payments are a special type of payment, for which the procedure is the same as when setting up a normal payment, with the only difference being that the request for setting up the payment contains special data.

When the first payment is established, the payment is made immediately and a scheduler is set to schedule the next payment repetition. The exact time and day the recurring payment is established is important because it is used to calculate the next recurring payment.

The body of the request for establishing a payment must contain the classic mandatory data for a regular payment enriched with the following:

"paymentType" : "Recurrent"

"Recurrence" object

After each payment, a notification should be sent to the merchant with details about the status of the payment, see Payment status notification

Example

{

  "paymentType": "recurrent",

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

      "cycle":"day",

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

API reference

Abbreviations :

• M - mandatory field
• O - optional field.

Payment operations

Payment request

Create payment request

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

Payment request headers

Payment request body object PaymentCreateRequestData

Simple payment request example :

{
  "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"
}

Complete payment request example :

{
    "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"
}

OnDemand payment

The first time you request a payment, you must create a payment with the OnDemand type. After the customer completes the payment, a token is obtained by asking for the payment status. On subsequent payments you pass the token in the payment request, the payment id will be returned, but no longer the redirect url. The payment will take place without customer interaction. You will be notified when the payment is complete, just like a standard payment.

First OnDemand payment request

{
  "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"
}

Second OnDemand payment request - without customer interaction

{
  "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"
}

Payment info request

[ POST ] /api/merchant/payment/info

Payment info request body object PaymentInfoRequestData

Payment info request example :

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

Create payment response

Payment response body object PaymentCreateResponse

Payment response example (direct) :

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

Payment response example (email):

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

Payment response example (OnDemand) - first:

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

Payment response example (OnDemand) - next:

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

Payment info response

Payment info response body object PaymentInfoResponse

Objects

Basket

BasketHeader

BasketPayment

BasketCustomer

BasketItem

CardHolder

CardHolderPhoneNumber

Enums

PaymentReferenceType

PaymentId (in BasketPayment object)

BasketItemMeasureUnit

MerchantPaymentStatus

Recurrence

Notification of payment status

Notifying merchant about payment status is addressed to NotifyUrl sending notification JSON object containing paymentId and status.

Body of that request looks like:

Notification verification

While sending notification about payment status in a body of request, there is also possibility to ensure notification authenticity via notification signature in a header of request. The notification signature has key Signature and its value is hashed string. This hashed string was made with two parts: parameters of notification object from body and as key was used SignatureSalt which was automatically generated and returned in response body when MerchantMethodTerminal was created. If you lost this SignatureSalt value there is way to generate new one via sending POST request to endpoint merchants/{merchantId}/methods/{methodId}/terminals/{terminalId}/regenerate.

To verify notification authenticity follow these steps:

1. Calculate own signature Combine the parameters of recieved notification body as string like this ${{htmlContent}}quot;{paymentId}{status}". This value needs to be hashed (HMAC) using SHA256 algorithm and SignatureSalt value as key to hash. Last step is to remove "-" character from string. Final result should be string with uppercase letters and be 32 Bytes long

2. Compare Compare generated hashed code with recieved one in header of request