Skip to content

Fully embedded API

Endpoints

This specification describes Flowpay API suite supporting the Fully Embedded (Native) flow, including customer onboarding, account data integration, offer management and financing operations. You can implement fully featured embedded lending solution directly within your web app.

  • Customers

    Handles onboarding and identity verification. Enables activating or cancelling services, updating representatives and retrieving customer profile data—laying the foundation for a compliant lending relationship.

  • Open Banking

    Supports seamless integration with customers’ bank accounts. These endpoints provide transaction and account data, essential for real-time creditworthiness assessments and offer personalization.

  • Offers

    Manages financing offers dynamically. Allows requesting, recalculating, and retrieving personalized loan offers based on up-to-date customer and financial data.

  • Financings

    Covers the full financing lifecycle—from applying for a loan and document signing to managing active financings, prolongations and repayments.

Configuration and authorization

Our API endpoints are secured by a standard OAuth 2.0 Client Credentials Flow suitable for machine-to-machine authorization, so no end-user authorization is needed. Your should only access our secured API endpoints from within a secure backend environment.

As part of partner onboarding process we will provide you with respective credentials enabling you to generate access tokens to access our secured endpoints. These include YOUR_PARTNER_CODE, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET and YOUR_WEBHOOK_SECRET.

Note

Each runtime environment includes its own configuration settings and is secured with separate credentials.

API environment configuration

API_URL_BASE:  https://api.test.my.flowpay.io
API_TOKEN_URL: https://flowpay-test.eu.auth0.com/oauth/token
API_AUDIENCE:  https://api.test.partner.flowpay.io

API_URL_BASE:  https://api.my.flowpay.io
API_TOKEN_URL: https://flowpay.eu.auth0.com/oauth/token
API_AUDIENCE:  https://api.partner.flowpay.io

Request access token

To access our API, your app must request an access token for it. To do so, you will need to POST to the token URL. 

curl --request 'POST' \
--url 'API_TOKEN_URL' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type='client_credentials' \
--data client_id='YOUR_CLIENT_ID' \
--data client_secret='YOUR_CLIENT_SECRET' \
--data audience='API_AUDIENCE'

HTTP 200 OK response with a payload 

{
    "access_token":"eyJz93a...k4laUWw",
    "token_type":"Bearer",
    "expires_in":86400
}

HTTP 401 Unauthorized response with a payload 

{"error":"access_denied","error_description":"Unauthorized"}

Call API endpoint

To call an API endpoint, your application must pass the retrieved access token as a Bearer token in the Authorization header of the HTTP request.

curl --request 'GET' \
--url 'API_URL_BASE/partner-api/v1/financings' \
--header 'authorization: Bearer ACCESS_TOKEN' \
--header 'content-type: application/json'

HTTP 200 OK response with a payload 

[
    {
        "id": "5687646c-6862-4bf2-93e8-47909ba3fa88",
        "customerId": "3e6fe776-8b0c-4329-8980-8efa1ef52778",
        "state": "NEW",
        "createdAt": "2025-02-05T16:42:53.586618Z"
    }
]

HTTP 401 Unauthorized response with a payload 

{
    "message": "Unauthorized",
    "logref": "0d3d0bde-6d73-9d37",
    "_embedded": {
        "errors": [
            {
                "message": "Unauthorized"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/partner-api/v1/financings",
            "templated": false
        }
    }
}

Principles and standards

Flowpay API follows REST approach with resource oriented URLs, JSON encoded request and response messages, standard HTTP verbs and response codes.

Error handling

Flowpay API uses standard HTTP response codes to indicate the success or failure of an API request.

We return an HTTP 400 Bad Request response for requests that do not pass syntactic validation. E.g. invalid string size, etc. The payload contains the respective errors. 

{
    "message": "Bad Request",
    "logref": "2f6d9e4d-0dba-fe11",
    "_embedded": {
        "errors": [
        {
            "message": "dto.company.country: size must be between 2 and 2"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/customers/service-activation",
        "templated": false
        }
    }
}

We return an HTTP 401 Unauthorized response for requests that lack valid authentication credentials or fail to provide any authentication information when it is required.

{
    "message": "Unauthorized",
    "logref": "6a127f89-795e-2369",
    "_embedded": {
        "errors": [
        {
            "message": "Unauthorized"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/financings/000e788d-85db-4ab7-bb63-2712c84c4d6a",
        "templated": false
        }
    }
}

We return an HTTP 403 Forbidden response for requests that are authenticated but do not have the necessary permissions to access the requested resource.

{
    "message": "Forbidden",
    "logref": "345a3136-08f5-2c3b",
    "_embedded": {
        "errors": [
        {
            "message": "Forbidden"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/financings/000e788d-85db-4ab7-bb63-2712c84c4d6a",
        "templated": false
        }
    }
}

We return an HTTP 404 Not Found response to requests to non existing resources. 

{
    "message": "Not Found",
    "logref": "1997634a-f538-12a2",
    "_embedded": {
        "errors": [
        {
            "message": "Not found"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/financings/dee4f1e0-8a08-4484-bcc7-e785479b4bad",
        "templated": false
        }
    }
}

We return an HTTP 422 Unprocessable Entity response to requests that failed business validations. E.g. form submit that cannot be processes as the data are not valid. The payload contains the respective errors. 

{
    "message": "Unprocessable Entity",
    "logref": "63f993f1-e0d0-d28d",
    "_embedded": {
        "errors": [
        {
            "message": "INVALID_BUSINESS_ID"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/customers/service-activation",
        "templated": false
        }
    }
}

Webhooks

Webhooks enable your system to receive instant notifications about important events from our API. When key events occurs, our system automatically sends updates to your specified endpoint, allowing your application to respond in real-time. This creates a seamless and efficient integration between our services.

  • Completion of customer scoring
  • Changes in financing status

To receive webhook events from Flowpay in your web application, you must:

  • Implement HTTP endpoints to handle incoming webhook requests
  • Verify the authenticity of each webhook by implementing message authentication
  • Share the endpoint URL with Flowpay

Best practice for webhook handler implementation

  • Respond with HTTP 200 OK immediately upon receiving the webhook, before processing the payload
  • Process the webhook payload asynchronously to avoid blocking the response
  • Handle webhook processing errors gracefully without rejecting the webhook request
  • Verify the webhook signature before processing
  • Check the timestamp to prevent replay attacks
  • Return HTTP 200 even if signature verification fails to prevent unnecessary retries

Webhook message authentication and replay attack prevention

To verify authenticity and integrity of the events that Flowpay sends to your webhook endpoints we include x-flowpay-sig header with a message signature in each request. To prevent replay attacks we include x-flowpay-ts header with a message timestamp in each request.

The signature is generated using a hash-based message authentication code (HMAC) with SHA-256 hash function, the secret YOUR_WEBHOOK_SECRET shared with you during onboarding process as the key and the actual JSON payload from the webhook request concatenated with the message timestamp from request header as the message. To construct the message for HMAC calculation concatenate the actual JSON payload of the webhook request with the timestamp from request header x-flowpay-ts.

To verify the signature, compare the result of your HMAC calculation with the content of x-flowpay-sig header.

Webhook message and signature example

Let's assume YOUR_WEBHOOK_SECRET = secret

Received webhook request payload 

{"id":"5653fdfe-8b71-4c2d-b070-d0fda1d10000","state":"NEW","effectiveAt":"2023-06-30T12:05:28.466076Z"}

Received webhook request headers 

x-flowpay-ts: 2023-06-30T12:05:28.521071Z
x-flowpay-sig: 460d5701cb35f9dfc699423a76a952c747f32a6ccdf5da18f8f9955f03ebd8b7

Open Banking Data

Flowpay supports two modes for partners to integrate and provide required PSD2/AIS bank account data: PUSH mode and PULL mode. Both modes enable Flowpay to maintain up-to-date, consistent, and accurate financial data for customers, and partners may choose the mode that best fits their technical and operational processes.

General Requirements (Applicable to Both Modes)

  • Transaction History Coverage: Partners SHOULD provide up to 730 days of transaction history if available. A minimum of 90 days is required; less is only acceptable if explicitly communicated to Flowpay.
  • Data Update Frequency: Data must be updated or made available to Flowpay at least once daily.
  • Incremental Updates & Deduplication: Only new transactions since the last update should be pushed or appear in queries; deduplication is mandatory.
  • Event Notification: The partner MUST notify Flowpay immediately when data changes (new transactions, balances, or account metadata updates), enabling timely data refresh.
  • Data Fetch Interruptions: Any interruption must be proactively investigated by the partner, and Flowpay must be notified of the reason, impacted customers, and expected next steps.

PUSH Mode: Partner Pushes Data to Flowpay

In PUSH mode, the partner is responsible for proactively sending updated bank account data to Flowpay using specific API endpoints. This is suitable for partners that aggregate or process banking data in their own systems.

The partner MUST implement the following API interactions:

  1. Account Balances and Metadata Update: Use the designated endpoint /partner-api/v1/customers/{id}/bank-accounts to push updated account balances and any changes in account metadata to Flowpay.
  2. Post New Transactions: Use a dedicated endpoint /partner-api/v1/customers/{id}/bank-transactions to send only new transactions to Flowpay since the last update (incremental push, not full history).
  3. Event Notification: After new data is pushed (balances, metadata, or transactions), send an explicit event to notify Flowpay that updated data is available via endpoint /partner-api/v1/customers/{id}/bank-accounts-updated.

PULL Mode: Flowpay Retrieves Data from Partner

In PULL mode, the partner exposes an API conforming to Flowpay's requirements, and Flowpay periodically queries this API to retrieve the latest account data.

The partner MUST provide a documented API endpoint from which Flowpay can retrieve up-to-date account balances, metadata, and recent transactions. The data structure and content requirements are the same as documented for the PUSH mode API endpoints above.

The API must be available and performant to support Flowpay's data retrieval schedule.