Naar de hoofdinhoud

🔗 Enterprise API: push medewerkers- en loondata vanuit jouw HR-systeem naar Payflip

Alles wat jouw team moet weten om de Payflip Enterprise API op te zetten: van wat het doet, over toegang krijgen, tot live gaan.

Vandaag bijgewerkt

💡 Dit artikel legt uit wat de Payflip Enterprise API is, wat deze doet en alles wat je team nodig heeft om ermee aan de slag te gaan. Zakelijke stakeholders vinden de meerwaarde in de eerste secties (1–4); je IT-/ontwikkelingsteam vindt alles wat ze nodig hebben om de integratie verder op te bouwen in de latere secties (5–10).

1. Wat is de Enterprise API? 📘

De Payflip Enterprise API is een manier om je HR-systeem rechtstreeks met Payflip te verbinden. In plaats van handmatig werknemers- en salarisgegevens op twee plaatsen up-to-date te houden, bouwt je IT-team een eenmalige integratie en vanaf dat moment synchroniseert alles automatisch.
​

Je HR-systeem blijft de enige bron van waarheid. Geen exports meer, geen imports meer, geen gedoe met reconciliatie.

⚠️ De Enterprise API is ontworpen voor organisaties met een intern IT-/ontwikkelingsteam, of voor organisaties die willen samenwerken met een externe IT-partner. Payflip biedt zelf geen implementatiediensten aan.

2. Wat is de meerwaarde voor jou? 🫵🏼

Dit verandert er zodra de integratie live staat

  • Geen dubbele input meer: Werknemersgegevens en salariswijzigingen in je HR-systeem worden automatisch doorgestuurd naar Payflip.

  • Minder fouten: Handmatige imports zijn een veelvoorkomende bron van datakwaliteitsproblemen: foute lonen, ontbrekende werknemers, verouderde contracten.

  • Werkt voor meerdere entiteiten: Of je nu één of tien juridische entiteiten hebt, één integratie volstaat voor allemaal. Geen aparte setup per entiteit nodig.

  • Je HR-administratie focust op wat echt belangrijk is: Ze hoeven alleen in te grijpen wanneer dat nodig is: bij een conflict, een uitdiensttreding of een item dat manuele controle vereist. De rest verloopt automatisch.

  • Gestandaardiseerd en toekomstbestendig: Elke organisatie gebruikt hetzelfde API-schema. Geen maatwerk nodig aan de kant van Payflip, en het schaalt mee met je groei.

3. Wat wordt er gesynchroniseerd en wat niet? 🔁

✅ Wat wordt er gesynchroniseerd

  • Medewerkersgegevens (naam, e-mail, taal, startdatum, contracttype, juridische entiteit, payroll-ID).

  • Loongegevens (salaris, arbeidsregime, RSZ-coëfficiënten — inclusief wijzigingen doorheen het jaar).

❌ Wat momenteel buiten scope valt

  • Budgetten (zoals eindejaarspremie of bonus) — deze dien je nog steeds zelf toe te kennen in Payflip.

  • Historische looncontracten van vorige jaren (enkel contracten vanaf het begin van het lopende jaar).

  • Data die terug van Payflip naar jouw HR-systeem stroomt ➡️ dit is een eenrichtings-API.

4. Hoe werkt het 💡

Het model is eenvoudig: jouw systeem pusht data naar Payflip. Payflip haalt nooit iets op van jouw kant.

Dit gebeurt er telkens wanneer je data pusht:

  1. Jouw HR-systeem (of middleware) roept de Enterprise API aan met medewerkers- of contractdata.

  2. Payflip valideert de data en plaatst die in een staging.

  3. Een sync-job verwerkt de data naar Payflip.

  4. Als er iets aandacht vereist (een conflict, een uitdienst, een reviewitem), krijgt jouw HR-admin een melding in de tool.

Zie het als "push and forget" ➡️ eens de integratie draait, hoeft jouw IT-team er niet meer naar om te kijken. Jouw HR-admin behandelt eventuele uitzonderingen in Payflip.

💡 Data verschijnt niet meteen in Payflip nadat je die gepusht hebt ➡️ ze gaat eerst door een korte staging procedure. Als iets dringend is, kan jouw HR-admin een manuele sync triggeren vanuit de tool.

5. Voordat jouw IT-team begint te bouwen 🚧

Zorg dat je het volgende klaar hebt voordat je van start gaat met de de ontwikkeling:

  • Een ontwikkelaar (of team) met ervaring in het bouwen van REST API-integraties

  • Toegang tot de medewerkers- en loondata uit jouw HR-systeem of een middleware/ETL die die data kan extraheren

  • De Payflip company ID's voor elk van jouw juridische entiteiten ➡️ weet je niet waar je die vindt? Neem volgend artikel eens door

  • Een contactpersoon aan jouw kant die de API-credentials ontvangt

6. Toegang krijgen 🔑

De Enterprise API activeren doen we samen met jou. Zo verloopt het:

  1. Neem contact op met het Payflip supportteam via de blauwe knop in de tool of stuur een e-mail naar [email protected] en laat hen weten dat je de Enterprise API wilt activeren.

  2. Zij activeren het op jouw account en schakelen het technisch team van Payflip in.

  3. Het technisch team genereert API-credentials specifiek voor jouw organisatie.

  4. Jouw credentials worden gedeeld via een beveiligde Bitwarden-link. Het wachtwoord voor die link wordt apart doorgestuurd via een tweede kanaal naar keuze (Slack, Intercom, e-mail, etc.)

Your credentials package will include:

  • Auth0 Client ID and Client Secret

  • Auth0 token endpoint URL

  • API base URL

⚠️ Houd jouw Client Secret vertrouwelijk. Deel het nooit via e-mail of een onversleuteld kanaal.

7. Authenticatie 🛡️

De Enterprise API gebruikt OAuth2 Machine-to-Machine (M2M) authenticatie via Auth0. In de praktijk werkt het zo:

  1. Jouw systeem vraagt een token op bij het Auth0-endpoint met jouw Client ID en Secret.

  2. Auth0 geeft een gesigneerd JWT bearer token terug.

  3. Dat token gaat in de Authorization: Bearer <token> header van elke API-aanroep die je maakt.

Tokens verlopen, dus jouw integratie moet de vernieuwing automatisch afhandelen (doorgaans door een nieuw token op te vragen wanneer het huidige bijna verlopen is).

Voor alle details, voorbeeldaanvragen en foutcodes: enterprise.payflip.be

8. Wat moet jouw IT-team bouwen? 🛠️

Twee endpoints, meer niet:

  • POST /employees ➡️ om medewerkers te pushen

  • POST /contracts ➡️ om looncontracten te pushen

Upsert-logica: beide endpoints werken als een upsert. Elk record heeft een unieke sleutel (employeeKey of contractKey) die jij definieert en beheert. Bestaat die sleutel al in Payflip, dan wordt het record bijgewerkt. Bestaat het nog niet, dan wordt het aangemaakt. Zorg dat de sleutels consistent blijven bij elke push.
​

Bulk pushes: je kan meerdere records in één call sturen. Als sommige records in de batch ongeldig zijn, gaan de geldige records toch door en de respons vertelt je exact wat gelukt is, wat mislukt is, en waarom.

Volgorde is belangrijk: een medewerker moet al bestaan in Payflip voordat je een looncontract voor die medewerker kan pushen.

Voor de volledige veldreferentie, verplichte vs. optionele velden en voorbeeldpayloads: enterprise.payflip.be

9. Test voordat je live gaat 🧪

Rol niet meteen uit naar je volledige organisatie. We raden een gefaseerde aanpak aan:

  1. Begin klein: push 5–10 medewerkers en controleer of hun records correct verschijnen in Payflip.

  2. Test contracten: push looncontracten voor diezelfde medewerkers en bevestig dat de koppeling klopt.

  3. Test uitdiensttreding: push één medewerker met een endDateEmployer en verifieer dat de markering correct verschijnt voor jouw HR-admin.

  4. Multi-entiteit check (indien van toepassing): push records voor verschillende entiteiten en bevestig dat ze op de juiste plek terechtkomen.

  5. Ga live zodra alles er goed uitziet. 🚀

Een aantal specifieke situaties 📌

Iemand verlaat de organisatie

Push het record van de medewerker opnieuw met het veld endDateEmployer ingesteld op de laatste werkdag. Payflip trekt de toegang in op die datum en markeert de medewerker zodat jouw HR-admin actie kan ondernemen.

⚠️ De API geeft het signaal, maar verwerkt de volledige uitdienst niet. Jouw HR-admin moet de uitdienstprocedure in Payflip nog manueel afwerken (er zijn inputs vereist zoals details over de uitdiensttreding die de API niet kan aanleveren). De markering is een teken om actie te ondernemen.

Een voormalige medewerker opnieuw in dienst nemen

Als een eerder gedeactiveerde medewerker terugkomt, kan dit niet via de API worden afgehandeld. Neem contact op met het Payflip support-team, zij archiveren het oude record en koppelen het nieuwe aan jouw integratie.

Meerdere juridische entiteiten

Geen nood aan meerdere API-sleutels. Één set credentials dekt al jouw entiteiten. Gebruik gewoon het veld companyId op elk record van een medewerker om het naar de juiste juridische entiteit te gidsen.

Je hebt foutieve data gepusht

Push hetzelfde record (employeeKey or contractKey) opnieuw met de correcte waarden en het wordt overschreven. Als de data al naar Payflip gesynchroniseerd was, kan jouw HR-admin een conflict zien in de Integratiemodule dat manueel opgelost moet worden.

Voor vragen kun je contact opnemen met het Payflip supportteam via de blauwe knop in de Payflip admin tool of een e-mail sturen naar [email protected]. Indien nodig brengen zij je in contact met het technische team van Payflip om de details te bespreken.
​

Voor de volledige technische documentatie (endpoints, velddefinities, request/response-formaat, voorbeeld payloads), raadpleeg de live API-specificatie op enterprise.payflip.be.

Was dit een antwoord op uw vraag?