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. Calculates installment plans and applies promo codes, see Offers & installment plans.

  • 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. You 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.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.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. a form submission whose data fail business validation. 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 occur, 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.

Following webhook events are supported:

  • Completion of customer scoring
  • Changes in financing status

To integrate Flowpay webhooks into your application, follow these steps:

  • Register YOUR_WEBHOOK_BASE_URL for both TEST and PROD environments with Flowpay.
  • Implement HTTP endpoints that can receive and process incoming webhook POST requests.
  • Secure your integration by verifying each webhook's authenticity via message authentication.

Flowpay will deliver webhook POST requests to your endpoint at {YOUR_WEBHOOK_BASE_URL}/{event-type}. The supported event types are:

  • customer-scoring — Completion of customer scoring
  • financing-state — Changes in financing status

Best practice for webhook handler implementation

  • Verify the webhook signature and the x-flowpay-ts timestamp first. If both checks pass, respond with HTTP 200 OK immediately, before processing the payload
  • Process the webhook payload asynchronously to avoid blocking the response
  • Handle webhook processing errors gracefully without rejecting the webhook request
  • Discard duplicate deliveries by the x-flowpay-event-id header
  • Order events by the effectiveAt payload field, not by arrival time
  • Return HTTP 401 if the signature or the timestamp check fails

Delivery and retries

If your endpoint does not return an HTTP 2xx response, Flowpay retries the delivery with exponential backoff. Every retry of one event carries the same x-flowpay-event-id header value. Flowpay calculates a new x-flowpay-ts timestamp and signature for every attempt.

Because of retries, an event can arrive more than once and after a newer event. Use x-flowpay-event-id to discard a duplicate. Use effectiveAt to discard an event that is older than the last event you processed for the same financing or customer.

If a request fails the signature or the timestamp check, return HTTP 401 and discard the payload. Flowpay retries the delivery and calculates a new timestamp and signature for every attempt. If you correct the cause (for example the webhook secret) before Flowpay stops retrying, the next retry passes verification and no event is lost.

If all retries fail, read the current state of each financing with GET /partner-api/v2/financings. A customer-scoring result cannot be read back through the Partner API.

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. To identify the event across retries we include x-flowpay-event-id header with a UUID in each request. The signature does not cover x-flowpay-event-id.

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 and YOUR_WEBHOOK_BASE_URL = https://yourdomain.com/webhooks

Webhook request with the customer scoring event notification will be sent to following endpoint:

https://yourdomain.com/webhooks/customer-scoring

with payload:

{"customerId":"5653fdfe-8b71-4c2d-b070-d0fda1d10000","result":"OFFER","effectiveAt":"2023-06-30T12:05:28.466076Z","partnerCode":"YOUR_PARTNER_CODE","merchantId":"merchant-123"}

Received webhook request headers

x-flowpay-event-id: 0b7a4f1e-3c9d-3e2a-9f61-2d8c5e4b7a10
x-flowpay-ts: 2023-06-30T12:05:28.521071Z
x-flowpay-sig: 9a7d0bf3022c37eff45bcf3d60506ab0f1df4736396c82a457ccadd78f690a2e


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.