This guide explains the process for building the Standard Integration with Payflow's Public API in Spain.

1. Initial context: What is Payflow?

Payflow is a financial wellbeing platform whose main service is earned wage access.

This means that the companies that adopt the platform can allow their employees to withdraw part of the salary they have already earned, whenever they want or need it.

Payflow's goal is not to advance the entire salary, but to offer responsible liquidity. This means that Payflow will only advance the portion the employee has already worked, within the limits established by the contracting company.

It is not a solution that advances the full monthly salary, nor is it a lending solution. Payflow lets employees obtain liquidity on what they have worked, while preventing them from running out of income at the end of the month.

Practical example:

An employee with a net base salary of €3,000:

Earns €100 per day (3,000 / 30)

On day 10 of the month they have completed 9 worked days (day 10 is not over yet) and have therefore earned: €100 × 9 = €900

HR defines that they can withdraw 60%

They will therefore have €540 available

This way:

The employee covers specific needs

They do not run out of salary at month-end

No negative payroll is generated

Responsible use of the benefit is maintained

The goal is for the employee to have a percentage of their salary available, not 100% of it.

Along these lines, for a company that has adopted the Payflow platform to properly deliver the earned wage access service to its employees, it is necessary that it:
1.
Keeps the required basic employee information updated on a daily basis: new hires, terminations and changes
2.
Consumes the payment information (also daily) so the company can report it in its payroll system and process the payments.

2. Payflow: The Product

Payflow offers 3 main components:

Mobile app for employees:

Available on:

App Store: https://apps.apple.com/es/app/payflow/id1503530690

Google Play: https://play.google.com/store/apps/details?id=es.payflow.app&hl=en

It allows the user to:

See their available salary

Make transactions (cash withdrawals)

Review their history

Other: additional app features

It works as the trigger for earned wage withdrawal requests.

Web dashboard for administrators

URL: https://admin.payflow.es/auth/login

The web version used day to day by Payflow administrators (usually HR) to manage relevant aspects such as:

Reviewing the hires/edits/terminations executed by the integration

Configuring usage limits

Viewing transactions

Monitoring usage

Main page — Project statistics

Here you can see:

Number of registered employees: total and by product

Total amount transacted

Average transaction amount

Total number of transactions

Monthly evolution of total transactions

Monthly evolution of total amount transacted

Payflow Public API

Allows the dashboard operations to be automated through a public API.

The API allows you to automate sending and retrieving information through the /employees and /payments endpoints:

Create/Edit/Deactivate employees in the dashboard

Retrieve employee transactions into the payroll software

3. Goal of the integration

In companies with a considerable number of employees, this management is usually handled unattended — that is, through a system-to-system integration.

With the integration:

Payflow becomes a mirror of the payroll software, with the payroll software as the source of truth.

This reduces:

Human error

Delays

Production incidents

Operational workload

4. Architecture

For a better understanding of how to build this integration, we have essentially divided it into 2 parts:

1. Employee synchronization flow (POST /employees).
This API endpoint works as a POST + PUT method even though you only do a POST:
1.
Creates employees
2.
Updates employees (data and status)

2. Payment synchronization flow (GET /payments).
This API endpoint exposes the transactions made in Payflow by your company's employees.

The solution architecture is as follows:

5. Employee synchronization flow

Employee hires / terminations / changes

For an employee to be able to use the Payflow platform, they must first be created — that is, they must be set up as a potential user by their company in their Payflow dashboard.

The goal of this flow is to guarantee that only the correct employees can use Payflow and that their data is up to date.

It is important to remember that Payflow is a platform provided by the employer and the employee cannot modify any data there. If they want to change something, they must go to their employer, who makes the change in the HR software; this integration will then synchronize the changes into Payflow. This prevents fraud and guarantees the correct delivery of the service.

5.1 Information to synchronize from your HR software to your Payflow dashboard

5.1.1 Employee fields to synchronize

Detail of the information that must be synchronized for each employee (these are the fields that go in the JSON to be synchronized):

Field name in the Payflow API	Field group	Description	Field type / limitations	Mandatory?
payrollId	Identification data	Employee ID in your payroll software	String (max. 100 characters)	NO
personalId	Identification data	Valid identification document number	String (max. 100 characters)	YES
documentType	Identification data	Identification document type	String (max. 100 characters)	NO
firstName	Identification data	Full first name of the employee	String (max. 100 characters)	YES
lastName	Identification data	Full last name of the employee	String (max. 100 characters)	YES
email	Contact data	Valid email address of the employee	String (cannot be generic, must be unique) Invalid emails will be voided	YES [required if there is no phone number]
phone	Contact data	Valid phone number of the employee	String (cannot be generic, must be unique) Invalid phone numbers will be voided* - Can be sent without the country code*	YES [required if there is no email]
address	Contact data	Employee address	String (max. 100 characters)	YES
iban	Salary and banking data	Valid IBAN of the employee.	String (max. 100 characters)	YES
bankAccountType	Salary and banking data	Employee's bank account type.	String (max. 100 characters) Possible values: `savings`, `checking`, `maestra`	NO
netSalary	Salary and banking data	Employee's net salary (after taxes)	Number (must be a positive integer) If grossSalary is provided, do not send netSalary	YES [required if there is no grossSalary]
grossSalary	Salary and banking data	Employee's salary before taxes	Number (must be a positive integer) If netSalary is provided, do not send grossSalary	YES [required if there is no netSalary]
startDate	Contract data	Employee's contract start date	String Must be in `YYYY-MM-DD` format	NO
contractEnd	Contract data	Contract end date	String Must be in `YYYY-MM-DD` format	NO
status	Contract data	Employee status.	String Possible values: `active`, `inactive`, `on_leave`	YES
subsidiary	Contract data	Tax ID (CIF) of the subsidiary the employee belongs to	String	YES
availableAmount	Salary and banking data	Amount available for withdrawal	Number (must be a positive integer)	NO [This is for special Payflow projects. In standard projects, using grossSalary or netSalary is recommended]

5.1.2 Employee statuses and business rules (`status` field)

Detail of the possible statuses

This is the explanation of the possible values to send in the status field:

active → Can use Payflow; is an active employee at the company

inactive → Cannot use Payflow; no longer works at the company

on_leave → Temporarily cannot use Payflow; temporary leave defined by business rules

Detail of the business rules for defining the on_leave status

The business rules that can be applied in the code so that the employee is sent to Payflow with status = "on_leave", and thus comply with the standard integration standards against the Payflow API, are:

Tenure: Employees who have been at the company for less than X months

Holiday: Employees on holiday on the day of the synchronization.

Maternity/Paternity: Employees on maternity/paternity leave on the day of the synchronization

Sick leave: Employees on sick leave on the day of the synchronization

Intern/trainee: Employees who are interns or trainees

5.2 Technical synchronization process, method and endpoint to use

Operating standard:
Send the updates for all employees in bulk using the POST method (ideally in batches of 500 max) and the /employees endpoint.
Our API can take one request per second from the same IP — no more than that, because our firewall may block you.
Suggested frequency: 1–2 times a day (if you have >1000 employees) or every 4–8 hours (if you have <1000 employees). This is fully configurable.

Avoid common mistakes:
Always send all mandatory data.
Do not use salary = 0 to deactivate; always use the status field.
Do not stop sending employees in order to deactivate them; always use the status field.
Send full first and last names

Technical tips:
Handle 503 errors with retries and backoff.
Make sure your system can handle the volume: CPU, memory, timeouts.
Document the key rules for your team: salaries and statuses.

So, in order to synchronize employees to the Payflow API and keep them updated, the following flow must be automated so that it runs unattended at regular intervals (for example, every 4 hours):

0. Meet the prerequisites:
Access to the Payflow dashboard — the team will give you access.
The base URL and the endpoints:
Testing environment:
Base URL: https://api-public.payflow-dev.net
Endpoint to use: https://api-public.payflow-dev.net/employees
Production:
Base URL: https://api-public.payflow.es
Endpoint to use: https://api-public.payflow.es/employees
The API key.
You can generate it in the dashboard by following these steps:
1.
Go to the "integrations" section → "integrations"
2.
Select Payflow API
3.
Click the "Generate API Key" button
4.
Save the API Key somewhere safe so you can use it in the integration
You can come back here to generate a new one whenever you want
In Postman it would look like this:

1. Extract the required employee data from the HR software.

2. Format this data into the JSON accepted by the Payflow API (batches of 500 employees max per request).

Example of the JSON to send (batch of 3 employees)

[
    {
        "payrollId": "Emp01",
        "firstName": "Test User",
        "lastName": "Prueba Uno",
        "personalId": "12345228G",
        "iban": "ES7915389586411761022929",
        "grossSalary": 2500,
        "startDate": "2025-06-01",
        "email": "test_user_espana1989@payflow.com",
        "phone": "+34620002400",
        "address": "Calle 1",
        "status": "active",
        "subsidiary": "A66213898"
    },
    {
        "payrollId": "Emp02",
        "firstName": "Test User",
        "lastName": "Prueba Dos",
        "personalId": "12345672A",
        "iban": "ES7300351502021779400113",
        "grossSalary": 1500,
        "startDate": "2025-06-01",
        "email": "test_user_espana1988@payflow.com",
        "phone": "610304000",
        "address": "Calle 2",
        "status": "inactive",
        "subsidiary": "A66213898"
    },
    {
        "payrollId": "Emp03",
        "firstName": "Test User",
        "lastName": "Prueba Tres",
        "personalId": "52345128X",
        "iban": "ES7400752841167757417475",
        "grossSalary": 5000,
        "startDate": "2022-08-15",
        "email": "test_user_espana4263@payflow.com",
        "phone": "+34620402401",
        "address": "Calle 3",
        "status": "active",
        "subsidiary": "A66213898"
    }
]

In Postman it would look like this

3. Use the POST method pointing to the Payflow API /employees endpoint with these batches of up to 500 employees.

6. Payment synchronization flow

Synchronization of transactions to be deducted from employee payroll

To prepare employee payroll, the payments made on the Payflow platform must be correctly recorded in the payroll software so they can be deducted from that period's payroll.

The goal of this flow is to guarantee that the transactions made in Payflow are deducted from employee payroll.

Keep in mind that even though payroll is paid at the end of the month or fortnight, final settlements may be paid during the period to employees who are leaving. In those cases, the transactions made on the Payflow platform will need to be considered and deducted.

6.1 Information to synchronize from your Payflow dashboard to your HR software

6.1.1 Transaction fields to synchronize

Detail of the information the Payflow API will give you when querying employee transactions (these are the fields that go in the JSON):

Field name in the Payflow API	Description
id	Unique ID of each transaction
user	Identification document number of the employee who made the transaction
userPayrollId	Employee ID in your payroll software
amount	Amount of the transaction
fee	Transaction cost (always 0)
status	Transaction status
paid	Boolean confirming whether it was paid or not
requestedAt	Date and time of the request by the employee
paidAt	Date and time the transaction was received
message	N/A
informedToIntegration	Boolean confirming whether the transaction was reported to the payroll software or not

6.1.2 Transaction statuses in Payflow (`status` field)

The API will only show you the processed and processing statuses, but we are leaving the detail here so you know the rest.

Detail of the statuses

In the first column are the possible values of the status variable, in the second its definition, and in the third whether or not it is a final status.

Status	Definition	Is it a final status?
pending	Pending: The payment has been requested by the employee but has not yet been sent to the bank for execution.	NO
processing	Processing: The payment has been sent to the bank; it has not been confirmed yet.	NO
processed	Processed: The bank has confirmed that the transaction was processed successfully.	YES
canceled	Cancelled: The transaction was cancelled and was not paid.	YES
delayed	Delayed: The transaction was sent to the bank but is delayed.	NO
error	The bank has reported that there is an error with this transaction and it cannot be processed; the transaction was not paid.	YES

6.1.3 Optional parameters (they go in the query headers)

The API will show you all transactions with status = processed or processing, one by one, that have been made at your company, unless you use parameters in the headers to filter them.

The parameters you can use are the following; all of them are optional:

paid
Boolean to show only the transactions that have or have not been paid
paid = true — returns the transactions paid so far
paid = false — returns the transactions not paid so far
In Postman it would look like this:

convoluted

Boolean that shows the sum of the transactions along with the transaction id for each employee at the company.

convoluted = true — returns the sum of transactions with their ids per employee

convoluted = false — returns the transactions one by one

In Postman it would look like this:

And the JSON of the Payflow API response would look like this:

{
    "data": [
        {
            "ids": [
                "luqmR001",
                "aaa4Fc2e28"
            ],
            "user": "1023765879",
            "userPayrollId": "abc39485",
            "amount": 130000,
            "fee": 0,
            "informedToIntegration": false,
            "paid": true,
            "firstTransactionRequestedAt": "2025-01-24T00:00:00.000Z",
            "lastTransactionRequestedAt": "2025-01-28T14:28:29.000Z",
            "TransactionPaidAt": "2025-01-24T00:00:00.000Z",
            "lastTransactionPaidAt": "2025-01-28T14:28:29.000Z"
        },
        {
            "ids": [
                "aaa4Fc2e23",
                "aaa4Fc2e29"
            ],
            "user": "1098764900",
            "userPayrollId": "abc39489",
            "amount": 10000,
            "fee": 0,
            "informedToIntegration": false,
            "paid": true,
            "firstTransactionRequestedAt": "2025-01-24T00:00:00.000Z",
            "lastTransactionRequestedAt": "2025-02-03T13:41:55.000Z",
            "TransactionPaidAt": "2025-01-24T00:00:00.000Z",
            "lastTransactionPaidAt": "2025-02-03T13:41:55.000Z"
        }
    ]
}

start
Date from which the search starts, in YYYY-MM-DD format
If you combine it with end you can get the transactions between specific days.
In Postman it would look like this:

end
Date up to which the search ends, in YYYY-MM-DD format
If you combine it with start you can get the transactions between specific days.
In Postman it would look like this:

cycle
Payment cycle date in YYYY-MM format
In Postman it would look like this:

6.2 Information to synchronize from your HR software to your Payflow dashboard (optional but recommended)

6.2.1 Acknowledge payments call

Informs Payflow that a payment has been recorded in the payroll system to be deducted from a specific employee's payroll.

You must use the PUT method and the /payments/acknowledge endpoint

This endpoint changes the value of the informedToIntegration variable from false (default value) to true.

So, when you retrieve your employees' transactions again, you will be able to tell apart the ones you already reported in your HR software (informedToIntegration=true) from the ones you have not yet reported (informedToIntegration=false)

6.3 Technical synchronization process, method and endpoint(s) to use

Operating standard:
Query employee transactions using the GET method and the /payments endpoint
Use each transaction's id to identify it in your system so transactions are not duplicated.
All Processing and Processed payments must be retrieved and posted as a payroll item, since Processing payments are already in the hands of the receiving bank and will become Processed shortly.
If you decide to implement acknowledge payments, you must use the PUT method and the /payments/acknowledge endpoint
Suggested frequency: 1–2 times a day (if you have >1000 employees) or every 4–8 hours (if you have <1000 employees). This is fully configurable.

Avoid common mistakes:
Before building this flow, make sure a payroll concept exists at your company for the Payflow transactions to land in and be deducted.

Technical tips:
Make sure your system can handle the volume: CPU, memory, timeouts.

So, in order to synchronize the transactions from the Payflow API to your HR software, the following flow must be automated so that it runs unattended at regular intervals (for example, every 4 hours):

0. Meet the prerequisites:
A payroll concept created in the HR Software to post the Payflow transaction deductions; it is usually called "Anticipo Payflow"
Access to the Payflow dashboard — the team will give you access.
The base URL and the endpoints:
Testing environment:
Base URL: https://api-public.payflow-dev.net
Endpoint to use: https://api-public.payflow-dev.net/payments
Production:
Base URL: https://api-public.payflow.es
Endpoint to use: https://api-public.payflow.es/payments
The API key is the same one you generated for the employee flow
Decide whether you will use any parameter to filter the transactions from the Payflow API

1. Use the GET method to extract the transaction data from Payflow.

Example of the JSON returned by the endpoint

{
    "data": [
        {
            "id": "aaa4Fc2e291",
            "user": "12345228G",
            "userPayrollId": "Emp01",
            "amount": 20,
            "fee": 0,
            "status": "processed",
            "paid": true,
            "requestedAt": "2025-10-27T10:39:00.000Z",
            "paidAt": "2025-10-27T10:39:00.000Z",
            "message": null,
            "informedToIntegration": false
        },
        {
            "id": "aaa4Fc2e292",
            "user": "12345672A",
            "userPayrollId": "Emp02",
            "amount": 100,
            "fee": 0,
            "status": "processed",
            "paid": true,
            "requestedAt": "2025-10-27T08:10:00.000Z",
            "paidAt": "2025-10-27T08:10:00.000Z",
            "message": null,
            "informedToIntegration": false
        }
    ]
}

In Postman it would look like this

2. Take the data you need from the Payflow API response and post it into the HR Software, in the payroll concept reserved for Payflow transactions.
The data you need will vary depending on the HR Software and its requirements for creating a payroll item, but usually you take at least:
id to identify the transaction and avoid duplicates
user and/or userPayrollId to identify the employee the deduction applies to
amount to post the amount to be deducted in the concept

3. (Optional but recommended) Use the PUT method pointing to the Payflow API /payments/acknowledge endpoint to mark the transactions reported to the HR Software.
This endpoint allows you to change the value of the informedToIntegration variable from false (default value) to true.
Testing environment:
Base URL: https://api-public.payflow-dev.net
Endpoint to use: https://api-public.payflow-dev.net/payments/acknowledge
Production:
Base URL: https://api-public.payflow.es
Endpoint to use: https://api-public.payflow.es/payments/acknowledge
Example of the JSON to send in the request body
{
    "paymentsToMarkAsInformed": [
        "aaa4Fc2e1",
        "aaa4Fc2e2",
        "aaa4Fc2e3"
    ]
}
Example of the JSON returned by the endpoint
{
    "paymentsMarked": [
        "aaa4Fc2e1",
        "aaa4Fc2e2",
        "aaa4Fc2e3"
    ]
}
Once all the reported transactions are marked, on your next call to the /payments endpoint you will see informedToIntegration=true on the transactions you sent in this step.

7. Step by step of the integration

Here we will support you at every step and will be happy to schedule working sessions with you and your team to resolve any questions! The steps to implement this integration are:

We start in the testing environment

Receive testing environment access and generate the API Key

Test the endpoints mentioned in the previous steps with Postman

You can create some dummy employees, change their statuses and/or some of their data, and verify in the dashboard front end that they were updated successfully.

Ask us to load some dummy transactions so you can see them in the transactions endpoint

Build the Employee Flow

Build the Transaction Flow

Validate the result of both synchronization flows

Here is the detail of these validations

We always recommend involving the Payflow integrations team during these tests; you can do so by writing to integrations@payflow.es or to your technical account manager assigned to the project.

In the following link you can find a recommended test suite for the cases that need to be validated, both for employee and transaction synchronization.

The most important thing is to validate that employees are being created and deactivated correctly, to guarantee that new joiners can use the app and that leavers can no longer use it once they leave the company.

Then, it is also very important to validate that payments can be recorded correctly, especially in edge cases such as many payments requested on the same day or many payments requested within the same period.

Some payroll systems have the limitation of a single item per concept during a period, or on the same day within a period; in those cases it may be necessary to aggregate the totals before posting the payments.

Finally, some checks that help are:

Check the total number of employees both in the HR Software and in the Payflow dashboard (the easiest way is to download them to Excel from "view employees" in the Payflow dashboard and run these checks in Excel).
Check that number broken down by legal entity, in case we are working with more than 1 legal entity, and confirm that they match.
Sort the 'Net salary' column from lowest to highest. Review both the lowest and the highest salaries to confirm that the information was sent correctly and that there is no odd data such as 0s, negatives, extremely high numbers, etc.
Review 5 people at random to check that the information is correct: name, salary, complete banking details, status and the tax identification number of the legal entity they belong to.

With both flows validated, schedule a testing session with the project stakeholders (your company's payroll, finance, etc.) to run a live demo

With the full test suite complete and stakeholder sign-off, we proceed to go-live.

In the production environment

You will do your go-live.

You will receive the Payflow production credentials

You will switch on both integration flows and run the first employee synchronization to the Payflow dashboard

We will schedule a demo with the same stakeholders so that they can:

Review the employee synchronization.

Download the app, make a transaction, and have you synchronize it correctly.

8. Initial monitoring

It is always good practice to set up some kind of monitoring of what is happening in the integration.

For example, a daily email summarizing the employee/payment synchronization with success/error messages. Include a description in the error messages, since they are often due to simple issues such as fields with incorrect information.

You can include soporte_empresas@payflowapp.co in this report and we will help with proactive monitoring.

This alert also allows us to understand whether it stopped running for some reason, and on what date.

9. Troubleshooting

If you are having problems, this section may help. It is a collection of issues we have seen and resolved in the past:

A very typical error we have seen, both during Postman testing and during go-lives, is that the correct development/production credentials or URLs are not being used.

Development API URL: https://api-public.payflow-dev.net/
Development Dashboard: https://dashboard.payflow-dev.net/auth/login

Production API URL: https://api-public.payflow.es/
Production Dashboard: https://admin.payflow.es/auth/login

The firewall is preventing communication with the Payflow API. Remember that here you will also need to include both the development and production URLs so that both are reachable.

It is not unusual for some requests to fail when testing against our development environment (payflow-dev.net). Try several times, since it is a development environment and does not have the same capacity as production. If it keeps failing after several attempts, contact us.

API Integration guide

1. Initial context: What is Payflow?#

Practical example:#

2. Payflow: The Product#

Mobile app for employees:#

Web dashboard for administrators#

Payflow Public API#

3. Goal of the integration#

4. Architecture#

5. Employee synchronization flow#

5.1 Information to synchronize from your HR software to your Payflow dashboard#

5.1.1 Employee fields to synchronize#

5.1.2 Employee statuses and business rules (status field)#

5.2 Technical synchronization process, method and endpoint to use#

6. Payment synchronization flow#

6.1 Information to synchronize from your Payflow dashboard to your HR software#

6.1.1 Transaction fields to synchronize#

6.1.2 Transaction statuses in Payflow (status field)#

6.1.3 Optional parameters (they go in the query headers)#

6.2 Information to synchronize from your HR software to your Payflow dashboard (optional but recommended)#

6.2.1 Acknowledge payments call#

6.3 Technical synchronization process, method and endpoint(s) to use#

7. Step by step of the integration#

8. Initial monitoring#

9. Troubleshooting#