Fizen API definition (latest)

Fizen sp. z o.o. is a licensed entity with an entry in the AISP register obtained from the Polish Financial Supervision Authority (KNF), enabling the provision of the account information access service (AIS).

The offered FIZEN API solution enables business customers, with the consent of the account owner, to gain access to banking data in a standardised form. To do this, FIZEN API requires the consent of the account owner in the interface of the bank from which the data are to be made available. To perform this operation, FIZEN provides WIDGET FIZEN that can be placed on the page in the form of an iframe.

In addition, Fizen enables access to the technology of the Payment Initiation Service (PIS) for the entities who own a PISP licence using their production certificates.

Access to API

Access to FIZEN API is secured with two-step authentication:

• API KEY and TOKEN – these are confidential values provided by FIZEN that enable identification and connection with the FIZEN API infrastructure. The apiKey and token value are required with each request to the FIZEN API. The value should be placed in the request header as an apiKey and token.

• IP ADDRESS – is the source of each request to the FIZEN API. Each query should be sent from a server with one public IP ADDRESS. Before starting the production use of FIZEN API, you must provide the IP ADDRESS of the server from which requests will be sent to FIZEN API. In the case of FIZEN API SANDBOX tests, the IP address is not verified.

For full communication with API FIZEN, we will also ask you to provide the url address to which we transfer the following parameters:

• AIS service - state, userId, bankId, accounts[accountId], dateTime
• PIS service - state, userId, bankId, paymentStatus, amount, userId, dateTime

Initiation of AIS and PIS process

Initiation of services for AIS and PIS are based on the authorization of the user consent granted in the bank interface for access to the bank account. PIS initiation is based on initiating and authorising domestic payment for the retail account. Access to the service is available from the API or WIDGET level.

FIZEN API, with the account owner's consent, grants access to a variety of account types, including retail, company, and corporate accounts. It offers a comprehensive suite of features, such as domestic payments, future-dated payments, express transactions, bundled services, and recurring payments, all of which are provided for major commercial banks.

• Poland:

  • PKO BP
  • Pekao SA
  • Santander Bank Polska
  • ING Bank Śląski
  • mBank
  • BNP Paribas Bank Polska S.A.
  • Bank Millennium
  • Alior Bank
  • Velo Bank
  • Credit Agricole
  • Bank Pocztowy
  • Bank Ochrony Środowiska
  • Nest Bank
  • Inteligo

• Czech Republic:

  • Raiffeisen Czech Republic
  • Uni Credit Czech Republic
  • Komercni Banka
  • CSOB Czech Republic
  • Ceska sporitelna (Ersta)
  • Moneta Money Bank

• Slovakia:

  • Slovenska Sporitelna
  • Slovakia Tatra Banka
  • Slovakia Raiffaisen
  • CSOB Banka
  • UniCredit
  • Prima Banka

• Hungary:

  • Raiffeisenbank Hungary
  • Erste Bank Hungary
  • UniCredit Bank Hungary

• Romania:

  • Raiffeisen Romania
  • Uni Credit Romania
  • Banca Comerciala Romana

FIZEN WIDGET

FIZEN WIDGET enables the complementary service of the end user by enabling the transfer of consent in the banking interface for access to data from the account.

• It takes care of the user login to the banking interface. Confidential data such as login and password for end-user online banking will never pass through the client's server, thus eliminating the occurrence of security risks.
• Integration is quick and easy

The process of giving consent by the user in the banking interface using FIZEN WIDGET is as follows:

FIZEN API Sandbox

Before the production connection, Fizen enables access to the test environment, which is connected to real banking environments in sandbox mode. The environment allows you to fully download the test information about the user's account in order to test our technology. When using FIZEN SANDBOX, access to FIZEN WIDGET and FIZEN API is given.

FIZEN API (sandbox) url address: https://api.sandbox.fizen.com/

To ensure the best possible user experience, we decided to make the following banks available in the test environment:

• fizenbank (Our test bank implementation.)
• ing
• alior
• mbank

Normal working hours for the sandbox environment are from 8 AM to 6 PM UTC Time. Outside of these hours, the environment enters a napping state. If you decide to interact with it during non-operational hours, the environment will require 2 to 5 minutes to start up after the initial interaction.

Test Data for bank sandboxes is available here

In order to obtain access, apiKey and a token, please contact us at contact@fizen.com

FIZEN API Production

In order to switch and gain access to the production FIZEN API environment, a request should be made by e-mail to contact@fizen.com along with the information about the IP ADDRESS that will be used to communicate with FIZEN API. After obtaining approval, the values of apiKey and a token will be sent to grant the establishment of production communication with the FIZEN API.

• FIZEN API url address: https://api.app.fizen.com/

Securing your scripts from potentially suspicious calls is advised. To achieve this, consider implementing IP address filtering for incoming connections.

You should be aware of the IP address ranges associated with Fizen servers:

Sandbox environment

IP: 34.118.93.200

Production environment

IP: 34.116.211.162, 34.118.70.53

The following table defines the lifetimes for the state depending on the type of operation

Whenever the process of authorizing an account or ordering a transaction is successfully completed, information about it will be sent to a pre-configured endpoints with the help of the POST method.

To ensure correct communication via the POST method, three return addresses need to be configured:

• Return address for the AIS service - dedicated for successful responses for account information access operations.

• Return address for the PIS service - dedicated to handling successful responses for payment initialisation.

• Return address for error handling - common to the AIS and PIS services, used when errors occur.

Each of these addresses should be configured individually to ensure the correct operation of the respective processes.

Once the operation is successful, the following parameters are transferred via POST endpoints:

For AIS Service:

For PIS Service:

The above parameters are necessary to complete the operation under the selected service.

Parameters transfer takes place in the following way:

• POST method - parameters are sent into the endpoint prepared on the client side. The endpoint has to take the following data structure:

  AIS service:
  
  {
  "state": "ExAmPlEsTaT-5e83-11ed-a320-856ce1faa777",
  "userId": "exampleUserId",
  "bankId": "exampleBankId",
  "accounts": [
    {
      "accountId": "ExampleAccountIIVzdweGpkUS95OTNnOTdxMXZrOEk0QjUwOU1tU2iMA=="
    },
    {
      "accountId": "ExampleAccountIS9INW53c2k0M2g1cHFiN3pSWlRpKVFg0TWl1bFBncQ=="
    }
  ]
  },
  
  PIS service:
  
    {
    "state": "ExAmPlEsTaTece1a4cb6-5e83-11ed-a320-856ce1faa777"
    "userId": "exampleUserId",
    "bankId": "exampleBankId",
    "paymentStatus": "examplePaymentStatus",
    "amount": "0.01",
    }
  

  Possible Payment Statuses:

  Status	Description
  Submitted	The payment has been successfully submitted and is awaiting execution.
  Scheduled	The payment is scheduled for a future date and awaits the specified date.
  Pending	The payment is pending further verification or approval before execution.
  InProgress	The recurring payment is correctly defined and executed according to the schedule or Bundle payments include at least one transaction with a future date (applies to FIZEN API).
  RECURRING_PLANNED	The recurring payment is correctly defined and executed according to the schedule (applies to FIZEN PAY).
  Cancelled	The payment has been canceled by the user or the system before execution.
  Rejected	The payment has been rejected and will not be executed.
  Done	The payment has been successfully executed and recorded in the recipient's account.

FizenPay is a payment page hosted by Fizen where users complete all the steps of the payment process: selecting the customer's bank, initializing the payment process, and redirecting to the bank service to allow the user to complete the payment. Payment is initiated through a dedicated endpoint, through this endpoint payment parameters are provided.

The payment process begins with the generating of a payment link. The user clicks on the link and is redirected to a panel to select the bank from which he wants to make the payment.

Once the payment is approved at the bank, the user is redirected to a screen with the status of the payment. Finally on the page we are expected to see a green status, which means that the payment was successful. Red x at the end means that payment failed. Once the final status is received, it also sends feedback to the addresses provided earlier.

To start working with the payment gateway it is necessary to generate the access keys for this purpose contact us. In the next step it is necessary to create a transaction by executing api endpoint.

A list of available banks for AIS and PIS services along with redirecting to the chosen bank interface

FIZEN API for AIS, or Account Information Service, provides individuals with access to information about their payment accounts. With AIS, you can conveniently monitor the real-time status of your finances through various third-party applications. This service empowers users to gain a holistic view of their financial transactions and balances, making it easier to manage their financial affairs and make informed decisions about their money. AIS is a key component of PSD2 (Payment Services Directive 2), promoting financial transparency and enhancing the user's ability to leverage innovative financial tools and services.

FIZEN's Domestic Payment Services are responsible for processing domestic payments.

In this context, a domestic payment refers to a financial transaction in which funds are transferred from one bank account to another within the same country or a specific geographical region, typically using the local currency. These payments serve various purposes, including bill payments, transferring money to family and friends, making purchases, and settling financial obligations within the same country or region. It's important to distinguish domestic payments from international payments, which involve the transfer of funds between bank accounts located in different countries, often requiring currency conversion and compliance with international banking regulations.

It's important to highlight that payments initiated and approved by users through their banking service cannot be canceled. This guarantees the successful delivery of payments, ensuring that once a user authorizes a transaction, it will be executed as scheduled. This assurance contributes to the reliability and trustworthiness of the domestic payment service, giving users peace of mind regarding the arrival of their funds at the intended destination.

FIZEN's Future Date Domestic Payment Services are responsible for processing domestic payments with a future date. This specialized service operates in a manner similar to standard domestic payments but introduces the ability to schedule payments for specific dates in the future. It allows users to proactively set up payments in advance, ensuring that financial commitments are met precisely when needed. Future date domestic payments offer a valuable solution for planning and managing financial transactions within the same country or specific geographical region, granting users greater flexibility and control over their payment schedules. It's important to emphasize that this service remains distinct from international payments, focusing solely on domestic transactions and eliminating the complexities associated with cross-border transfers and currency conversion.

It's important to emphasize that this service allows for the cancellation of scheduled payments until the transfer is executed, providing users with complete control over their finances. This feature ensures that users have the flexibility to modify or cancel future date domestic payments as needed, offering peace of mind and adaptability in managing their financial commitments.

Additionally, it's worth noting that this service also provides users with the option to lock funds in their account, in which case the cancellation of a transfer may not be possible.

FIZEN's Express Domestic Payment Services are responsible for processing domestic payments with immediate delivery time. This specialized service operates similarly to standard domestic payments but with the added advantage of near-instantaneous transaction execution. Users can initiate and receive payments promptly, ensuring that funds are deposited directly into the recipient's account without delay, facilitating swift and efficient financial transactions.

FIZEN's Recurring Payment Services are responsible for processing payments on a recurring basis. This specialized service functions similarly to standard payments but offers the added convenience of automated, scheduled payments that occur at regular intervals, such as monthly or weekly.

Users can set up recurring payments to meet their financial commitments without manual intervention, ensuring that payments are made consistently and on time. This feature provides users with the flexibility to establish and manage recurring financial transactions, streamlining their financial obligations. It's worth noting that, like other payment which nas future execution date, recurring payments can also be canceled until the scheduled payment date, giving users full control over their recurring financial transactions and allowing for adjustments as needed.

FIZEN's Bundle Payment Services are responsible for processing bundled payments. This specialized service operates similarly to standard payments but offers the added convenience of grouping multiple payments into a single, comprehensive transaction. Users can combine various payments into a bundle, streamlining their financial transactions and simplifying the management of multiple financial commitments. This feature allows for more efficient and organized payment processing.

FIZEN's SEPA Retail Payment Service enables individual customers to seamlessly initiate and manage international payments within the Single Euro Payments Area (SEPA). This service is tailored for personal transactions, allowing individuals to transfer funds across European countries with the same ease as domestic payments.

SEPA retail payments ensure fast, secure, and standardized cross-border transfers in EUR, eliminating the complexity of traditional international wire transfers. By following SEPA standards, users can conduct international transactions as efficiently as domestic ones, ensuring compliance with European banking regulations.

Key Features:

• SEPA Credit Transfer (SCT) for Individuals: Retail SEPA payments follow the SCT scheme, allowing personal international transfers with minimal fees.
• Cross-Border Transactions in EUR: The transferred amount must be specified in EUR, regardless of the sender's local currency.
• Bank-Dependent Processing Times: The completion time of SEPA retail payments depends on the recipient's bank and the standard cut-off times set by SEPA regulations.
• Mandatory Recipient Country Code: Each SEPA transaction requires the ISO country code of the recipient’s bank to ensure accurate processing.
• Low-Cost International Transfers: SEPA retail transactions are typically cheaper than traditional SWIFT payments, making them ideal for individuals.
• EU-Wide Standardization: Ensures uniform rules across all SEPA member states, allowing users to make seamless transactions.

The SEPA Retail Payment Service provides a convenient, cost-effective, and reliable way for individuals to transfer money across European borders, ensuring smooth and predictable financial transactions. With transparent processing and standardized banking practices, users can confidently send funds internationally without unexpected fees or delays.