Billink Documentatie

## Sections
• [Introductie](https://ontwikkelaars.billink.nl/introductie.md): De Billink API is ontworpen met een RESTful architectuur, en biedt ontwikkelaars een voorspelbare en efficiënte manier om hun applicaties te integreren. De API ondersteunt JSON antwoordformaten. De Billink API biedt een robuuste set van endpoints voor het beheren van belangrijke operaties, waaronder orderafhandeling en betalingsverwerking. De belangrijkste functies zijn: Orderbeheer : Orders aanmaken, in de wacht zetten en hervatten, workflows opstarten, Betalingen : Maak betaalsessies aan, verwerk betalingen en volg de status ervan. Berichten : Stuur updates en berichten over bestellingen. Status bijhouden : Bewaak de voortgang en status van orders en workflows. Kunt u het eindpunt dat u nodig hebt niet vinden? We helpen je graag elke werkdag. Je kunt ons rechtstreeks bereiken via de chat, per telefoon of WhatsApp. Alle details vind je hier . Om naadloos testen en implementeren mogelijk te maken, biedt de Billink API twee operationele modi: Sandbox-modus : Een veilige testomgeving waarmee u kunt experimenteren met API-functies zonder de live productiegegevens te beïnvloeden. Productiemodus : De live-omgeving voor echte operaties en klantinteracties. Je kunt onze API Explorer gebruiken om onze endpoints meteen te testen. U kunt altijd schakelen tussen de sandbox - en productieomgeving API URLs Billink API biedt twee verschillende omgevingen om ontwikkeling en productie te vergemakkelijken. Elke omgeving is toegankelijk via een speciale URL: Staging-omgeving : Gebruik deze omgeving voor test- en ontwikkelingsdoeleinden. URL: https://api-staging.billink.nl Productie-omgeving: Gebruik deze omgeving voor live bewerkingen op productieniveau. URL: https://api.billink.nl Zorg ervoor dat je de juiste URL gebruikt, afhankelijk van of je in staging of productie werkt, om onbedoelde interacties met live gegevens te voorkomen
• [Billink Status](https://ontwikkelaars.billink.nl/billink-status.md): Je kunt altijd de actuele status van onze diensten bekijken op: https://status.billink.nl
• [Billink Changelog](https://ontwikkelaars.billink.nl/billink-changelog.md): Op deze pagina vind je relevante updates aan het Billink-platform: van nieuwe features en verbeteringen in Billink One tot belangrijke bugfixes, API-wijzigingen en nieuwe PSP-integraties. Zo blijf je altijd op de hoogte van wat er verandert en hoe dit jouw checkout, integratie of klantbeleving verbetert.
  • [Release v2026.2 - 4 maart, 2026](https://ontwikkelaars.billink.nl/billink-changelog/release-v2026-1-20-januari-2026-copy.md): Gedurende deze release zijn we met diverse A/B-testen bezig om de conversie te optimaliseren en de klantervaring in de Billink One checkout verder te verbeteren, waaronder verbeteringen in de mobiele checkout en communicatie bij betaalopties. Features Diverse design- en tekstoptimalisaties in de checkout en betaalpagina Verbeteringen in de orderbevestiging voor een duidelijkere gebruikerservaring Een nieuwe branded loading screen tijdens achtergrondcontroles Weergave van een tweede e-mailadres van klanten op de order detailpagina Op de betaalpagina in Billink One wordt nu duidelijk weergegeven dat het totaalbedrag incl. BTW is. App-iconen voor Android en iOS bijgewerkt naar de nieuwste versie Bug Fixes Pushnotificaties in de mobiele apps zijn geoptimaliseerd Kleine visuele verbeteringen doorgevoerd in de interface van Billink One Loginproblemen met Mijn Billink zijn opgelost Hotfixes Laadtijd van Billink One sessies verder geoptimaliseerd voor een snelle checkoutervaring.
  • [Release v2026.1 - 20 januari 2026](https://ontwikkelaars.billink.nl/billink-changelog/release-66-november-11-2025-copy.md): Project features Billink One Optimalisatie Doorlopend verbeteren we Billink One via A/B-tests en systeemoptimalisaties om de winkelervaring en functionaliteit te versterken. Features Nieuwe functionaliteit maakt het eenvoudiger om gestructureerde B2B-facturen digitaal via Peppol te verzenden, ondersteund door Maventa. Verbeteringen in de winkelmand zorgen voor een duidelijkere weergave van betaalinformatie, inclusief totalen en btw, in alle ondersteunde talen. Het notificatieproces in Billink One is geoptimaliseerd, waardoor berichten efficiënter en overzichtelijker naar klanten worden gestuurd. Bug Fixes De e-mailfunctionaliteit is verbeterd zodat alle adressen, inclusief speciale tekens en spaties, correct worden verwerkt en in de app correct verschijnen. Gebruikers kunnen bij een iDIN-mismatch eenvoudig een alternatieve betaalopties kiezen. Optimalisaties zorgen voor een betrouwbare registratie van Belgische KvK- nummers. Het betaalproces voor Bancontact is geoptimaliseerd, waardoor shoppers correct en probleemloos naar de juiste betaalpagina worden geleid.
  • [Release 66 - November 11, 2025](https://ontwikkelaars.billink.nl/billink-changelog/release-66-november-11-2025.md): Project features Optimalisatie Billink One Gedurende de release testen we verschillende varianten via AB-testen om zowel de conversie als de klantervaring te blijven optimaliseren. Features Billink One interface geoptimaliseerd met nieuwe labels en een verbeterde formulierstructuur. Btw-informatie en betaalopties zijn overzichtelijker en consistenter weergegeven in Billink One. Hotfixes Mobiele apps geüpdatet voor consistente labeling en automatische selectie van relevante betaalopties. Bug Fixes Webhooks en API-integraties zijn gestabiliseerd voor betrouwbare data-overdracht. Pop-ups en meldingen worden correct getriggerd en verschijnen op het juiste moment. Correcties doorgevoerd in berekeningen en pagina-updates, inclusief iDIN- verificatie en volledige crediteringen.
  • [Release 64 – 7 oktober, 2025](https://ontwikkelaars.billink.nl/billink-changelog/release-64-october-7-2025-1.md): Project features Verbeteringen Mobiele App. Voorheen was het niet mogelijk voor een consument om direct een openstaande order die te laat is betaald, af te betalen. Vanaf nu kan dit direct in de app. Optimalisatie Billink One Gedurende deze release zijn we met diverse AB-testen bezig om de conversie optimaal te houden en de klantervaring te blijven verbeteren. HPP – Apparaatvingerafdruk v0 Op Billink One krijg elk apparaat een unieke identificatiecode voor verbeterde fraudedetectie. Features Aanbetalingsdetails worden getoond in klantmeldingen. Algemene fixes en stabiliteitsverbeteringen. Klanten ontvangen nu e-mails bij gedeeltelijke credits. Uitbreiding Developer Portal met Billink One branding. Mogelijkheid om PDF-facturen van bestellingen te downloaden. Verbeterde betrouwbaarheid van instellingen en succesmeldingen. Verbeteringen facturen: Openstaande facturen hebben nu paginering voor betere overzichtelijkheid. Maintenance Optimalisaties in klantinstellingen. Uitgebreidere ondersteuning voor webhooks. Optimalisaties voor databaseprestaties. Bug Fixes Diverse verbeteringen aan loginprocessen, vertalingen en interfaceweergave. Betere e-mailcommunicatie en correctie van foutmeldingen in betalingsflows.
  • [Release 62 – augustus 26, 2025](https://ontwikkelaars.billink.nl/billink-changelog/release-62-august-26-2025.md): Project features HPP – Aanbetalingen v1: De logica rondom aanbetalingen is nog meer verfijnd. De optie wordt alleen getoond wanneer dit wettelijk en commercieel verantwoord is. Rebrand Mobile apps v0: Onze mobiele apps zijn voorzien van een nieuw design, afgestemd op de Billink branding. Een moderner uiterlijk, betere leesbaarheid, eenvoudigere navigatie en een dark mode voor gebruiksgemak. Multi-email accounts (app): Gebruikers kunnen nu meerdere e-mailadressen koppelen aan één Billink-account. Hierdoor kunnen consumenten meerdere orders inzien als zij meerdere e-mailadressen gebruiken. Features Session Cancel status toegevoegd → geeft merchants en klanten meer duidelijkheid wanneer een sessie wordt afgebroken. Nieuwe velden in aanbetalingen betaaloptie → meer inzicht in betaalopties en betere beslislogica. Nieuwe betaalmethode-selector en verbeterde Next-button in Billink One → minder klikken, snellere checkout. Factuurnummers toegevoegd aan betaalomschrijvingen Affiliate-programma voorwaarden gelinkt in systeem → direct inzicht voor merchants. Webhook-voorbeelden toegevoegd in developer documentatie → eenvoudiger testen en sneller integreren. Documentatie vernieuwd en voorzien van nieuwe branding → consistentere ervaring voor developers. Mid release deployments (Hotfixes) Uitgebreide documentatie over webhooks sessie/orderinfo toegevoegd. Bankoptie verwijderd bij iDEAL in mijn.billink.nl voor een duidelijkere betaalervaring voor klanten. Bug fixes We hebben een groot aantal bugs verholpen die de stabiliteit en betrouwbaarheid verbeteren. Enkele belangrijke fixes: Orderbedragen en geboortedata nu correct weergegeven in portals. Diverse fixes in Customer Portal (login, orderoverzicht, factorloon-tabellen). Betere foutafhandeling bij formulieren en disputeflows → minder blokkades voor merchants. Kleine UI- en UX-fixes in portals (icons, vertalingen, lay-outs). Billink One-logo toegevoegd aan developer portal → herkenbaarheid en consistentie. Maintenance Verbeterde dialogen en prompts in portals voor een duidelijkere interactie met merchants Branding en kleine tekstwijzigingen doorgevoerd op portals en affiliatepagina’s.
• [Partners Exclusief](https://ontwikkelaars.billink.nl/partners-exclusief.md): De sectie Clientbeheer is uitsluitend bedoeld voor het aanmaken van e-merchants binnen het systeem. Gebruikers kunnen nieuwe e-merchants registreren door de benodigde klantinformatie te verstrekken. Deze sectie zorgt ervoor dat merchants correct worden aangemeld op het Billink-platform.
  • [Merchant Create](https://ontwikkelaars.billink.nl/partners-exclusief/client-api.md): Met het Merchant Create -endpoint kunnen partners (resellers) een nieuw klant(submerchant)-profiel aanmaken binnen het Billink-platform. Het wordt meestal gebruikt tijdens onboarding om een klant te registreren met alle benodigde bedrijfs-, facturatie- en contactgegevens. billinkUsername en billinkID zijn de inloggegevens van je partneraccount — de nieuwe klant wordt onder je partneraccount aangemaakt en eraan gekoppeld. De username en het email -adres van de nieuwe klant moeten uniek zijn binnen Billink. Het veld method bepaalt de workflow-configuratie: stuur 1 om betaalworkflows voor de nieuwe klant in te richten (Billink-standaarden, of de configuratie die je meestuurt in workflows ); elke andere numerieke waarde slaat de workflow-configuratie over. Zet changePasswordLink op "true" om in het response een eenmalige wachtwoord-herstellink voor de nieuwe klant te ontvangen. Alle mogelijke foutmeldingen voor deze endpoint zijn te vinden in de sectie met foutcodes .
• [Betaling autoriseren](https://ontwikkelaars.billink.nl/beheer-van-betaalsessies.md): Het onderdeel Beheer van betaalsessies vergemakkelijkt het aanmaken en bewaken van betaalsessies en zorgt voor een soepel en gestroomlijnd betaalproces voor gebruikers. Met dit onderdeel kun je betaalsessies initialiseren en hun huidige status controleren, waardoor je realtime inzicht krijgt in de levenscyclus van de betaling. Deze mogelijkheden zijn essentieel voor het leveren van een veilige en efficiënte betaalervaring.
  • [Create Session](https://ontwikkelaars.billink.nl/beheer-van-betaalsessies/create-session.md): Maakt een nieuwe Billink-betaalsessie aan door gegevens van de merchant, klant, adres en bestelling in te dienen. Retourneert een sessie-URL die de klant doorstuurt naar de Billink-checkout om de betaling te voltooien. Geschikt voor integratie van Billink in je online checkoutproces. De sessie blijft geldig totdat een van de volgende situaties zich voordoet: • De klant voltooit de betaling, • De sessie wordt geannuleerd , • Of er is 1 uur verstreken sinds de sessie is aangemaakt. Alle mogelijke foutmeldingen voor deze endpoint zijn te vinden in de sectie met foutcodes .
  • [Session Status](https://ontwikkelaars.billink.nl/beheer-van-betaalsessies/session-status.md): Het Session Status endpoint stelt je in staat om de real-time status van een bestelling geplaatst via het Billink platform te controleren. Het is vooral handig om te bepalen of een betaalsessie succesvol is afgerond, nog in behandeling is, of werd verlaten. Alle opgegeven identifiers worden gecombineerd — de sessie moet aan alle voldoen; de nieuwste passende sessie wordt teruggegeven. Zonder identifier faalt het request met 400 "Missing search parameters". Alle mogelijke foutmeldingen voor deze endpoint zijn te vinden in de sectie met foutcodes .
• [Orderbeheer](https://ontwikkelaars.billink.nl/orderbeheer.md): Het gedeelte Orderbeheer biedt tools voor het afhandelen van de levenscyclus van een order: bewaking, het starten van de workflow, betaling en meer. Het maakt efficiënte orderverwerking mogelijk door middel van functionaliteiten zoals het controleren van de status van een order, het toevoegen van berichten aan orders en het beheren van workflows door orders in de wacht te zetten of te hervatten. Deze functies zorgen voor naadloze integratie, nauwkeurige tracering en gestroomlijnde operaties voor orderbeheer. Houd er rekening mee dat de beschreven eindpunten slechts enkele voorbeelden van foutreacties bevatten. Raadpleeg het gedeelte Fouten voor een uitgebreide lijst met foutcodes en berichten.
  • [Start Workflow](https://ontwikkelaars.billink.nl/orderbeheer/start-workflow.md): De Start Workflow wordt gebruikt om automatisch het workflowproces te starten voor één of meerdere facturen na levering van een bestelling. Standaard past Billink een vertraging van 3 dagen toe voordat de workflow start, zodat klanten de tijd hebben om de levering te controleren. Deze vertraging kan echter worden aangepast via je accountinstellingen om beter aan te sluiten bij je bedrijfsbehoeften. Alle mogelijke foutmeldingen voor deze endpoint zijn te vinden in de sectie met foutcodes .
  • [Credit](https://ontwikkelaars.billink.nl/orderbeheer/credit.md): De Credit stelt je in staat om gedeeltelijke of volledige crediteringen toe te passen op bestaande facturen binnen het Billink-systeem. Dit biedt meer flexibiliteit bij het afhandelen van situaties na verkoop, zoals retourzendingen, kortingen of factuurcorrecties. Alle mogelijke foutmeldingen voor deze endpoint zijn te vinden in de sectie met foutcodes .
  • [Carriers list](https://ontwikkelaars.billink.nl/orderbeheer/carriers-list.md): De Carriers List geeft alle vervoerders terug die door de tracker-endpoints worden ondersteund. Gebruik dit endpoint als bron voor de carrierCode -parameter van Create Tracker en Update Tracker . Per vervoerder is code de exacte waarde die je als carrierCode meestuurt, en name het leesbare label dat je in je interface kunt tonen. Sommige codes wijken af van de weergavenaam (bijv. DHL_Express vs "DHL Express") — stuur altijd de code . Voor dit endpoint is geen authenticatie nodig.
  • [Create Tracker](https://ontwikkelaars.billink.nl/orderbeheer/create-tracker.md): De sectie “Create” stelt gebruikers in staat om een nieuwe tracker aan het systeem toe te voegen. Met deze endpoint kunnen gebruikers eenvoudig traceerinformatie koppelen aan specifieke bestellingen, wat zorgt voor een efficiënte monitoring en beheer van zendingen. Daarnaast ontvangen gebruikers gedetailleerde reacties die aangeven of het aanmaken van de tracker succesvol was of is mislukt.
  • [Update Tracker](https://ontwikkelaars.billink.nl/orderbeheer/update-tracker.md): De Update Tracker API stelt je in staat om verzendinformatie van een bestaande tracker te wijzigen. Dit is handig voor het corrigeren van fouten, bijwerken van leveringsgegevens of het uploaden van extra bestanden, zoals bijgewerkte verzendlabels of afleverbevestigingen. Door het opgeven van de tracker-ID en de bijgewerkte velden, kun je details wijzigen zoals de vervoerder, het factuurnummer of de track-en-tracecode. Optioneel kun je ook gekoppelde bestanden (bijvoorbeeld afbeeldingen of PDF’s) toevoegen of vervangen, gecodeerd in Base64.
  • [Payment](https://ontwikkelaars.billink.nl/orderbeheer/payment.md): De Payment stelt merchants in staat om betalingen te initiëren voor één of meerdere facturen binnen het Billink-systeem. Deze functionaliteit is bedoeld voor situaties waarin betalingen buiten de standaard Billink-checkout plaatsvinden — zoals terugkerende klanten die rechtstreeks via een webshop betalen, administratief factuurbeheer, of integratie met maatwerk facturatieprocessen. Alle mogelijke fouten voor dit endpoint zijn te vinden in de foutenlijst .
  • [On Hold](https://ontwikkelaars.billink.nl/orderbeheer/on-hold.md): De On Hold stelt merchants in staat om een factuur tijdelijk “on hold” te zetten binnen het Billink-platform. Dit biedt meer flexibiliteit bij het beheren van facturatie- en betalingscycli. Zodra een factuur on hold staat, worden er gedurende de opgegeven periode - voor het aantal dagen dat je opgeeft, of totdat de order handmatig wordt hervat Alle mogelijke fouten voor dit endpoint zijn te vinden in de foutenlijst .
  • [Resume Order](https://ontwikkelaars.billink.nl/orderbeheer/resume-order.md): De Resume Order stelt gebruikers in staat om facturen te heractiveren die eerder on hold zijn gezet. Deze API zorgt voor een soepele voortzetting van het facturatie- en betalingsproces, waardoor onderbrekingen in de administratie worden voorkomen. Merchants krijgen hiermee meer flexibiliteit en controle over het beheer van de factuurlifecycle binnen het Billink-systeem. Alle mogelijke fouten voor dit endpoint zijn te vinden in de foutenlijst .
  • [Order Info](https://ontwikkelaars.billink.nl/orderbeheer/order-info.md): Met Order Info kunnen gebruikers gedetailleerde informatie opvragen over de betaalstatus en de huidige workflowpositie van één of meerdere facturen. Dit maakt effectieve tracking van orders mogelijk en helpt gebruikers te controleren of betalingen zijn gedaan en waar orders zich bevinden in de verwerkingscyclus. Het biedt inzichten voor het efficiënt beheren van facturen binnen het Billink-platform. Statuswaarden: 1 — factuur betaald. description bevat de huidige workflowstap van de order. 0 — factuur nog niet betaald. description bevat de huidige workflowstap ("No steps given" als de workflow geen stappen heeft, "Pending COEO" zolang de order in de incassofase zit). -1 — geen order gevonden voor het opgegeven factuurnummer. description is "Order not found". Statuswaarden worden als string teruggegeven. Het veld description wordt alleen meegestuurd als stapomschrijvingen voor je account zijn ingeschakeld. Alle beschikbare fouten voor dit endpoint vind je in de foutenlijst .
  • [Message](https://ontwikkelaars.billink.nl/orderbeheer/message.md): De Message API stelt gebruikers in staat om interne berichten aan specifieke orders toe te voegen. Deze berichten zijn zichtbaar voor het Billink klantenserviceteam via de backend-interface en kunnen worden gebruikt om belangrijke informatie, statusupdates of speciale instructies met betrekking tot een factuur door te geven. Deze functie verbetert de interne communicatie en stroomlijnt het beheer van workflows gedurende de hele factureringscyclus. Alle beschikbare fouten voor dit endpoint vind je in de foutenlijst .
• [Dispute](https://ontwikkelaars.billink.nl/dispute.md): De sectie Dispute biedt de basisfunctionaliteit die nodig is om met geschillen te werken. Hiermee kunt u de beschikbare geschilcategorieën opvragen en, indien nodig, een nieuw geschil voor een transactie aanmaken.
  • [Dispute Categories](https://ontwikkelaars.billink.nl/dispute/dispute-categories.md): Het eindpunt Dispute Categories biedt de mogelijkheid om een lijst op te vragen van alle beschikbare geschillencategorieën en hun ID's.
  • [Dispute Create](https://ontwikkelaars.billink.nl/dispute/dispute-create.md): De Dispute stelt handelaars in staat om geschillen met betrekking tot klantfacturen te starten. Het biedt een gestructureerde manier om zaken zoals productretouren, beschadigde goederen of klantspecifieke problemen af te handelen.
• [Reconciliatie](https://ontwikkelaars.billink.nl/afstemming.md): De Reconciliatie -sectie biedt toegang tot financiële gegevens voor het matchen en opvolgen van klantfacturen . Momenteel worden de volgende functies ondersteund: Ophalen van een paginagewijs overzicht van facturen voor een specifieke Billink-klant Downloaden van factuurgegevens voor verdere verwerking of rapportage
  • [Invoices](https://ontwikkelaars.billink.nl/afstemming/invoices.md): Haalt een paginagewijs overzicht op van facturen voor een specifieke Billink-klant. Ondersteunt optionele filtering op datumbereik en retourneert factuurbedragen, factuurnummers en bijbehorende afstemmings-ID’s. Alle mogelijke foutmeldingen voor dit endpoint zijn te vinden in de foutenlijst .
  • [Invoice Download](https://ontwikkelaars.billink.nl/afstemming/invoice-download.md): Met dit eindpunt kunnen klanten alle beschikbare factuurdocumenten downloaden als een ZIP-archief. Hiervoor is een geldige Billink klantidentificatie, gebruikersnaam, factuurjaar en factuurnummer nodig. Bij succes retourneert het een 200 statuscode met application/zip content type, waardoor een ZIP-bestand wordt gedownload. Alle beschikbare fouten voor dit eindpunt kun je vinden in de sectie fouten .
• [Webhooks](https://ontwikkelaars.billink.nl/webhooks-v3.md): De Order Webhook v3 voegt HMAC signature verification en drie nieuwe eventtypes toe bovenop alle bestaande events. De huidige webhook blijft ongewijzigd werken — v3 is opt-in. “v3” verwijst naar de webhook-versie, niet naar de API-versie. Alle Webhook v3-eindpunten gebruiken het voorvoegsel /v2/. Elke v3-webhook bevat drie beveiligingsheaders: Title Description Header Purpose X-Billink-Signature HMAC-SHA256-handtekening (hexadecimaal gecodeerd) X-Billink-Timestamp Unix-tijdstempel (seconden) — afwijzen als ouder dan 5 minuten X-Billink-Webhook-Id Uniek leverings-ID — blijft bij herhalingspogingen hetzelfde; gebruik dit voor het verwijderen van dubbele gegevens Kenmerkende formule: HMAC-SHA256(timestamp + raw_body, secret) — de uitvoer bestaat uit kleine letters in hexadecimale notatie, zonder voorvoegsel. De onbewerkte HTTP-body moet worden gehasht — JSON mag nooit worden geparseerd en opnieuw geserialiseerd vóór de verificatie. Handtekeningcontrole Herhalingen (retries) Billink probeert mislukte leveringen tot 3 keer opnieuw te verzenden met een exponentiële wachttijd (exponential backoff). Elke herpoging gebruikt dezelfde X-Billink-Webhook-Id . Na 3 opeenvolgende mislukte pogingen wordt er een e-mailnotificatie verzonden. Snel starten: Stap 1: Genereer een ondertekeningsgeheim CURL POST https://api-staging.billink.nl/v2/client/webhook-v3/secret/generate Body: Plain text { "billinkUsername": "your_username", "billinkID": "your_billink_id" } Response: Plain text { "status": "success", "message": "Webhook V3 secret is generated successfully", "secret": "npHiAuRps5S+nTsDL2L663zmm9gfiP3wtmMDgbQNDLg=" } Sla dit geheim veilig op — je hebt het nodig om webhook-handtekeningen te verifiëren. Het geheim is een base64-gecodeerde string. Eén geheim wordt gebruikt voor alle v3-webhooks (zowel session als order). Stap 2: Registreer je v3 webhook-URL’s Order webhook: CURL POST https://api-staging.billink.nl/v2/client/webhook-v3/set Body: Plain text { "billinkUsername": "your_username", "billinkID": "your_billink_id", "url": "https://your-domain.com/webhook/order" } Session webhook: CURL POST https://api-staging.billink.nl/v2/session/webhook-v3/set Body: Plain text { "billinkUsername": "your_username", "billinkID": "your_billink_id", "url": "https://your-domain.com/webhook/session" } Response (both): Plain text { "status": "success", "message": "Webhook has been set" } Stap 3: Implementeer signature verification Elke v3 webhook bevat drie headers: Signature constructie : HMAC-SHA256(timestamp + payload, secret) waarbij timestamp de Unix timestamp string is en payload de ruwe request body bytes zijn, direct aan elkaar gekoppeld (zonder scheidingsteken). De output is lowercase hex, zonder sha256= prefix. Belangrijk : je moet de ruwe HTTP request body exact zo hashen als die wordt ontvangen — parse de JSON niet en serialize hem niet opnieuw. Verschillende talen serialiseren JSON op verschillende manieren (bijv. Node.js escapt / niet, PHP wel), waardoor de signature ongeldig wordt. Stap 4: Schakel oude webhooks uit (optioneel) Let op: je kunt oude en v3 webhooks tegelijk gebruiken tijdens het testen. Events worden dan dubbel verzonden als beide ingeschakeld zijn. Order webhook: Plain text POST https://api-staging.billink.nl/v2/client/webhook/disable POST https://api-staging.billink.nl/v2/client/webhook/disable Session webhook: Plain text POST https://api-staging.billink.nl/v2/session/webhook/disable POST https://api-staging.billink.nl/v2/session/webhook/disable Body ( beide ): Plain text { "billinkUsername": "your_username", "billinkID": "your_billink_id" } Signature Verification — Codevoorbeelden PHP PHP <?php $secret = 'npHiAuRps5S+nTsDL2L663zmm9gfiP3wtmMDgbQNDLg='; // BELANGRIJK: gebruik de ruwe HTTP body — NIET json_decode direct — // zodat je de originele bytes behoudt. $rawBody = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_BILLINK_SIGNATURE'] ?? ''; $timestamp = $_SERVER['HTTP_X_BILLINK_TIMESTAMP'] ?? ''; // 1. Replay-bescherming if (abs(time() - (int)$timestamp) > 300) { http_response_code(403); exit('Timestamp too old'); } // 2. Verifieer signature tegen RAW body bytes $expected = hash_hmac('sha256', $timestamp . $rawBody, $secret); // 3. Timing-safe vergelijking if (!hash_equals($expected, $signature)) { http_response_code(403); exit('Invalid signature'); } // 4. Parseer pas na verificatie $event = json_decode($rawBody, true); http_response_code(200); Node.js (Express) JavaScript const crypto = require('crypto'); const express = require('express'); const app = express(); const SECRET = 'npHiAuRps5S+nTsDL2L663zmm9gfiP3wtmMDgbQNDLg='; // BELANGRIJK: gebruik express.raw — NIET express.json() — // zodat req.body een Buffer is met de originele bytes. app.post('/webhook/order', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-billink-signature'] || ''; const timestamp = req.headers['x-billink-timestamp'] || ''; // 1. Replay-bescherming if (Math.abs(Date.now() / 1000 - parseInt(timestamp, 10)) > 300) { return res.status(403).send('Timestamp too old'); } // 2. Verifieer signature tegen RAW body bytes const rawBody = req.body.toString('utf8'); const expected = crypto .createHmac('sha256', SECRET) .update(timestamp + rawBody) .digest('hex'); const sigBuf = Buffer.from(signature, 'utf8'); const expBuf = Buffer.from(expected, 'utf8'); if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) { return res.status(403).send('Invalid signature'); } // 3. Alleen parsen na verificatie const event = JSON.parse(rawBody); res.status(200).end(); } ); app.listen(3000); Python Python import hmac, hashlib, time, json SECRET = 'npHiAuRps5S+nTsDL2L663zmm9gfiP3wtmMDgbQNDLg=' def verify_billink_webhook(raw_body: str, headers: dict, secret: str): signature = headers.get('X-Billink-Signature', '') timestamp = headers.get('X-Billink-Timestamp', '') # 1. Replay-bescherming if abs(time.time() - int(timestamp)) > 300: raise ValueError('Timestamp too old') # 2. Verifieer signature expected = hmac.new( secret.encode(), f'{timestamp}{raw_body}'.encode(), hashlib.sha256 ).hexdigest() if not hmac.compare_digest(expected, signature): raise ValueError('Invalid signature') Flask usage: Python from flask import Flask, request, abort app = Flask(__name__) @app.post('/webhook/order') def webhook(): raw_body = request.get_data(as_text=True) # Ruwe body, niet request.json try: verify_billink_webhook(raw_body, dict(request.headers), SECRET) except ValueError as e: abort(403, str(e)) event = json.loads(raw_body) return '', 200 FastAPI usage: Python from fastapi import FastAPI, Request, HTTPException app = FastAPI() @app.post('/webhook/order') async def webhook(request: Request): raw_body = (await request.body()).decode('utf-8') # Ruwe body try: verify_billink_webhook(raw_body, dict(request.headers), SECRET) except ValueError as e: raise HTTPException(status_code=403, detail=str(e)) event = json.loads(raw_body) return {} Alle event types Order events Title Description Title Event Beschrijving Typisch gebruik order_placed Klant heeft succesvol een order geplaatst. Markeer order als aangemaakt. order_workflow_started De order is in het interne verwerkingsproces opgenomen. Order kan als gestart worden weergegeven. partial_payment_added Er is een deelbetaling voor de order ontvangen. Haal de nieuwe ordergegevens op om het openstaande bedrag bij te werken. order_paid De order is volledig betaald. Markeer order als betaald. partial_credit_added Er is een gedeeltelijke creditering of terugbetaling toegepast op de order. Haal de nieuwe ordergegevens op om het openstaande bedrag bij te werken. order_fully_accredited Er is een volledige creditering of terugbetaling toegepast op de order. Markeer order als volledig gecrediteerd in het systeem. customer_fully_paid De klant heeft alle openstaande bedragen voldaan. Markeer order als betaald. order_on_hold De order staat tijdelijk on hold (bijv. in afwachting van beoordeling of geschilproces). Markeer order als gepauzeerd. dispute_created Er is een geschil geopend voor de order (bijv. de klant betwist een bedrag). Pauzeer de fulfillment en volg de geschilstatus. dispute_resolved Een eerder geopend geschil is opgelost. Hervat de normale orderverwerking. retrocession_credit_applied Er is een retrocessiekrediet toegepast op de order (krediet teruggestort aan de merchant door Billink). Pas het ordersaldo aan en werk de boekhouding bij. Session events Session-webhooks worden alleen verzonden bij statuswijzigingen van een bestaande sessie . Het aanmaken van een nieuwe sessie triggert geen webhook — het eerste event dat je ontvangt komt overeen met de eerste statusovergang (bijv. order_created wanneer de koper de checkout afrondt, of cancelled als de sessie wordt geannuleerd). Title Description Title Status Beschrijving Typisch gebruik session_active De sessie is succesvol geinitialiseerd en is momenteel actief. De sessie is gestart en de klant doorloopt het betaalproces. cancelled De klant heeft de sessie handmatig geannuleerd of de checkout gesloten. Stop het volgen van de sessie en markeer deze als geannuleerd. failed De sessie is mislukt door een technische of validatiefout (bijv. betaalmethode niet beschikbaar, ongeldige gegevens). Toon een foutmelding of log de fout voor een nieuwe poging. session_expired De sessie is automatisch verlopen na een timeout (1 uur) zonder het afronden van de checkout. Markeer sessie als verlopen en annuleer gerelateerde lopende processen. order_created De checkout is succesvol afgerond en er is een order aangemaakt. Bevestig de order en start de fulfillment in uw systeem. Webhook Payload Formats Payload van order webhook Alle order-events gebruiken dezelfde payload-structuur (ongewijzigd ten opzichte van de huidige webhook): Plain text { "order_id": 12345, "invoice_number": "INV-2026-001", "invoice_number_clean": "INV2026001", "workflow_id": 67, "event": "order_paid", "timestamp": "2026-04-07 10:00:00" } Title Description Title Veld Type Beschrijving order_id integer Billink order ID invoice_number string factuurnummer invoice_number_clean string factuurnummer zonder speciale tekens workflow_id integer Workflow instance ID event string eventtype (zie eventtabel hierboven) timestamp string Tijdstempel van het event (Y-m-d H:i:s) Payload van session webhook Dit formaat is hetzelfde voor zowel v2- als v3-session webhooks. Session-webhooks gebruiken een andere payload-structuur: Plain text { "transactionId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "billinkInvoiceNumber": "INV-2026-001", "invoiceNumber": "ORDER-2026-001", "status": "order_created" } Title Description Title Veld Type Beschrijving transactionId string Sessie transactie-ID billinkInvoiceNumber string Billink invoice number invoiceNumber string Billink factuurnummer status string Sessie status (zie session events tabel hierboven)
  • [Signing Secret Genereren](https://ontwikkelaars.billink.nl/webhooks-v3/signing-secret-genereren.md): Genereert of roteert het HMAC-SHA256 signing secret dat gedeeld wordt door zowel order- als sessie v3 webhooks. Het roteren van het secret maakt het vorige onmiddellijk ongeldig — werk uw verificatielogica bij voordat u roteert. Het gegenereerde secret is ook zichtbaar op de instellingenpagina van het Billink-merchantportaal.
  • [Order Webhook](https://ontwikkelaars.billink.nl/webhooks-v3/order-webhook.md): De Order Webhook stelt uw systeem op de hoogte van belangrijke gebeurtenissen in de levenscyclus van een bestelling. Hierdoor kan uw platform in realtime reageren, bijvoorbeeld wanneer een bestelling wordt geplaatst, gedeeltelijk wordt betaald, volledig wordt betaald, wordt gecrediteerd of in de wacht wordt gezet. Je kunt ook lezen hoe je de Order Webhook kunt instellen of uitschakelen.: Order Webhook Instellen | Order Webhook Uitschakelen Billink ondertekent elke levering met HMAC-SHA256 met het gedeelde secret. De volgende order events worden naar de geconfigureerde URL gestuurd: order_placed partial_payment_added order_paid partial_credit_added order_fully_accredited customer_fully_paid order_workflow_started order_on_hold dispute_created dispute_resolved retrocession_credit_applied
    • [Order Webhook Instellen](https://ontwikkelaars.billink.nl/webhooks-v3/order-webhook/order-webhook-instellen.md): Configureert of wijzigt de v3 order webhook URL voor de merchant. Er moet eerst een signing secret gegenereerd worden via het /v2/client/webhook-v3/secret/generate endpoint.
    • [Order Webhook Uitschakelen](https://ontwikkelaars.billink.nl/webhooks-v3/order-webhook/order-webhook-uitschakelen.md): Verwijdert de geconfigureerde v3 order webhook URL voor de merchant. Er worden geen order events meer verzonden na het uitschakelen. Het signing secret blijft bewaard en kan opnieuw worden gebruikt wanneer de webhook weer wordt ingeschakeld.
  • [Session Webhook](https://ontwikkelaars.billink.nl/webhooks-v3/session-webhook.md): De Session Webhook stelt uw systeem op de hoogte wanneer een betalingssessie van status verandert. Hierdoor kan uw platform in realtime reageren, bijvoorbeeld wanneer een sessie actief wordt, mislukt of verloopt. Je kunt ook lezen hoe je de sessiewebhook kunt instellen of uitschakelen: Session Webhook Instellen | Session Webhook Uitschakelen De volgende sessie events worden naar de geconfigureerde URL gestuurd: order_created — er is een order aangemaakt vanuit de sessie session_expired — de sessie is verlopen session_active — de sessie is actief geworden failed — de sessie is mislukt cancelled — de sessie is geannuleerd Let op: Webhooks worden alleen getriggerd bij statuswijzigingen. Het aanmaken van een nieuwe sessie genereert geen webhook.
    • [Sessie Webhook URL instellen](https://ontwikkelaars.billink.nl/webhooks-v3/session-webhook/sessie-webhook-url-instellen.md): Configureert of wijzigt de v3 sessie webhook URL voor de merchant. Gebruikt hetzelfde gedeelde signing secret als de order webhook — genereer het via /v2/client/webhook-v3/secret/generate als u dat nog niet heeft gedaan.
    • [Sessie Webhook Uitschakelen](https://ontwikkelaars.billink.nl/webhooks-v3/session-webhook/sessie-webhook-uitschakelen.md): Verwijdert de geconfigureerde v3 sessie webhook URL voor de merchant. Er worden geen sessie events meer verzonden na het uitschakelen. Het signing secret blijft bewaard en kan opnieuw worden gebruikt wanneer de webhook weer wordt ingeschakeld.
• [Errors](https://ontwikkelaars.billink.nl/errors-fouten.md): In Billink API , error responses follow a consistent format. All errors are returned with an HTTP status code 200 , which indicates the request was processed but there was an issue with the operation. The format of the error is as follows: JSON { "code": "000", "description": "Error message", "result": "error" } Code : A unique error code representing the specific issue. Description: A detailed description of the error. Result: Short informative status These errors might indicate a variety of issues including but not limited to problems with API versioning, client authentication, missing or incorrect parameters, data format issues, and restrictions on actions (such as workflow limitations or invalid operations). Common Issues: Client Identification : Errors related to missing or incorrect client username, client id, or API version. Invoice and Workflow Management : Missing or incorrect invoice numbers or workflow data. Order Management : Trying to perform actions on orders that are not allowed or are already processed. Request Limitations : Exceeding request limits (e.g., number of invoices, action frequency). Parameter Validation : Incorrect or unsupported parameters in requests. This helps you to easily handle and debug issues by following the provided error code descriptions across all API endpoints. In the next subsections, you will see errors specific to each endpoint. Each of these subsections includes a list of error codes and their corresponding descriptions to help you understand and resolve issues effectively.
  • [Client API Fouten](https://ontwikkelaars.billink.nl/errors-fouten/client.md): Overzicht van Client API-foutcodes De foutcodes binnen de Client API richten zich voornamelijk op problemen met de identificatie van klanten, ouder-kindrelaties tussen klanten en de validatie van klantgerelateerde gegevensvelden. Veelvoorkomende problemen zijn onder andere: Onbekende of ongeldige client-gebruikersnaam of client-ID. Problemen met ouder-kindrelaties tussen klanten, zoals een client die zichzelf als ouder opgeeft of een ongeldige ouder-ID. Validatiefouten bij bedrijfs- en persoonsgegevens, waaronder bedrijfsnaam, voor- en achternaam, IBAN, BIC, contactgegevens en adresinformatie. Fouten met betrekking tot uniciteitsvereisten, zoals dubbele gebruikersnamen of e-mailadressen. Ontbrekende of ongeldige informatie over het platform of de reseller. Code Message 101 Onbekende client-gebruikersnaam of client-ID 102 Onbekende client-gebruikersnaam of client-ID 103 Client met gebruikersnaam “%message%” heeft geen toegang tot api/create-client 104 Onbekende gebruikersnaam van ouderclient 105 Een client kan zichzelf niet als ouder instellen 106 De opgegeven ouderclient-ID behoort niet tot de reseller-clientlijst 401 Ontbrekende of ongeldige bedrijfsnaam (2-100 tekens) 402 Ontbrekende of ongeldige voornaam (2-255 tekens) 403 Ontbrekende of ongeldige achternaam (2-255 tekens) 404 IBAN ontbreekt 405 Geef een geldig IBAN of bankrekeningnummer op 406 BIC-nummer ontbreekt of ongeldig formaat (ISO 9362) 407 Ontbrekende of ongeldige plaatsnaam (alleen letters, spaties, ‘-’, ‘.’, ‘’’) 408 Ontbrekend of ongeldig KvK-nummer (8 cijfers) 409 Ontbrekend of ongeldig contact-e-mailadres 410 Ongeldige landcode 411 Ontbrekend of ongeldig telefoonnummer (9–18 tekens, cijfers, ‘+’, ‘()’, ‘-’) 412 Ontbrekend of ongeldig e-mailadres 413 Huisnummer ontbreekt 414 Ongeldig huisnummerformaat 417 Logo-afbeelding kon niet worden opgeslagen 418 Ontbrekend of ongeldig telefoonnummer (9–18 tekens, cijfers, ‘+’, ‘()’, ‘-’) 419 Ontbrekende of ongeldige postcode 420 Ontbrekende of ongeldige straatnaam (letters, cijfers, spaties, ‘-’, ‘’’, ‘.’) 421 Naam van de rekeninghouder ontbreekt 422 Ontbrekend of ongeldig btw-nummer 423 Ontbrekende of ongeldige website-URL (bv. www.voorbeeld.nl) 424 Ontbrekende of ongeldige methode (moet numeriek zijn) 425 Ontbrekende of ongeldige gebruikersnaam (4–50 tekens) 426 Landcode ontbreekt 427 Client met gebruikersnaam “%message%” bestaat al 428 Client met e-mailadres “%message%” bestaat al 429 Platform-ID ontbreekt 430 Platform met deze ID bestaat niet 431 Gebruikersnaam van ouderclient ontbreekt 432 ID van ouderclient ontbreekt
  • [Session Status Fouten](https://ontwikkelaars.billink.nl/errors-fouten/session-status.md): Samenvatting van sessiestatus-foutcodes De foutcodes voor sessiestatus hebben voornamelijk betrekking op problemen met gebruikersvalidatie, toegangsrechten, het al dan niet bestaan van een sessie en onverwachte serverfouten. Veelvoorkomende problemen zijn onder andere: Verplichte formuliergegevens ontbreken, zoals een leeg gebruikersnaamveld. Toegang geweigerd vanwege onvoldoende rechten. Sessies die niet gevonden kunnen worden of zijn verlopen. Algemene serverfouten die wijzen op onverwachte storingen. Code Message 400 Het formulier bevat de volgende fouten: 1) billinkUsername: Deze waarde mag niet leeg zijn. 403 Toegang geweigerd 404 Sessie niet gevonden 500 Er is iets misgegaan
  • [Create Session Submerchant Fouten](https://ontwikkelaars.billink.nl/errors-fouten/create-session.md): Samenvatting van foutcodes bij het aanmaken van een sessie voor submerchant De foutcodes bij het aanmaken van een sessie voor submerchant hebben vooral betrekking op validatieproblemen met klantgegevens, toegangsrechten en algemene serverfouten. Veelvoorkomende problemen zijn onder andere: Verplichte klantvelden ontbreken, zoals billinkUsername, billinkID en workflowNumber. Toegang geweigerd vanwege onvoldoende rechten. Klant niet gevonden wanneer billinkID of billinkUsername niet overeenkomen met bestaande gegevens. Onverwachte serverfouten die het aanmaken van een sessie verhinderen. Code Message 400 Het formulier bevat de volgende fouten: 1) client.billinkUsername: Deze waarde mag niet leeg zijn. 2) client.billinkID: Deze waarde mag niet leeg zijn. 3) client.workflowNumber: Deze waarde mag niet leeg zijn. 403 Toegang geweigerd 404 Geen klant gevonden met het opgegeven billinkID of billinkUsername 500 Er is iets misgegaan
  • [Start Workflow API Fouten](https://ontwikkelaars.billink.nl/errors-fouten/start-workflow.md): Samenvatting van Start Workflow API Foutcodes De foutcodes van de Start Workflow API richten zich voornamelijk op problemen met klantidentificatie, factuurvalidatie, workflowbeheer en verzoeklimieten. Veelvoorkomende problemen zijn onder andere: Onbekende gegevens zoals API-versie, gebruikersnaam van de klant of klant-ID. Problemen met factuurvalidatie, bijvoorbeeld ontbrekende of onbekende factuurnummers. Workflowfouten, zoals het proberen te starten van een workflow die al gestart is of wanneer de gebruiker niet gemachtigd is om de bestelling te beheren. Verzoeklimieten, zoals het overschrijden van het maximaal toegestane aantal facturen per aanvraag. Code Message 101 Onbekende client-gebruikersnaam of client-ID 102 Onbekende client-gebruikersnaam of client-ID 103 Onbekende actie 603 Redirect Billink API-fout 704 Onbekend factuurnummer 705 Geen facturen opgegeven 706 U bent niet gemachtigd deze order te beheren 707 Orderworkflow is al gestart 708 Maximaal 10 facturen per verzoek toegestaan
  • [Credit API Fouten](https://ontwikkelaars.billink.nl/errors-fouten/credit.md): Samenvatting van Credit Foutcodes De foutcodes van de Credit API richten zich vooral op problemen binnen workflows, validatie van bestellingen en factuurbeheer. Veelvoorkomende problemen zijn onder andere: Onbekende gegevens zoals API-versie, client gebruikersnaam of client-id. Workflowfouten gerelateerd aan ontbrekende of onjuiste workflownummers. Bestelfouten, bijvoorbeeld het proberen krediet toe te passen op een bestelling die al bestaat of niet beheerd kan worden in de huidige fase. Ongeldige gegevens, zoals ontbrekende facturen. Toegangsproblemen, bijvoorbeeld het niet kunnen beheren van een bestelling of het toepassen van krediet in een bepaalde fase. Code Message 101 Onbekende client-gebruikersnaam of client-ID 102 Onbekende client-gebruikersnaam of client-ID 103 Onbekende actie 402 Workflow met nummer %number% bestaat niet 404 Order met nummer %number% bestaat al 603 Redirect Billink API-fout 705 Geen facturen opgegeven 706 U bent niet gemachtigd deze order te beheren 707 Credit kan niet op dit moment worden toegepast 708 Credit kan niet op dit moment worden toegepast (0)
  • [Payment API Fouten](https://ontwikkelaars.billink.nl/errors-fouten/payment.md): Samenvatting van Payment foutcodes De Payment API-foutcodes hebben voornamelijk betrekking op problemen met clientidentificatie, factuurbeheer en orderstatus. Veelvoorkomende problemen zijn onder andere: Onbekende gegevens zoals API-versie, client-gebruikersnaam of client-ID. Fouten gerelateerd aan facturen, zoals ontbrekende of onbekende factuurnummers. Problemen met orderbeheer, bijvoorbeeld het beheren van een order waarvoor u geen toestemming heeft, of het proberen te betalen van een order die al betaald is. Fouten in de beschrijving, zoals het overschrijden van het maximale aantal toegestane tekens in betalingsomschrijvingen. Alle beschikbare foutcodes en berichten voor de Payment: Code Message 001 Onbekende API-versie 101 Onbekende client-gebruikersnaam of client-ID 102 Onbekende client-gebruikersnaam of client-ID 103 Onbekende actie 402 Workflow met nummer %number% bestaat niet 420 Ontbrekende factuurnummers 603 Redirect Billink API-fout 704 Onbekend factuurnummer 706 U bent niet gemachtigd deze order te beheren 707 Order is al betaald 708 Beschrijving is te lang (max. 30 tekens)
  • [On Hold API Fouten](https://ontwikkelaars.billink.nl/errors-fouten/on-hold.md): Samenvatting van On Hold API-foutcodes De On Hold API-foutcodes hebben vooral betrekking op problemen met clientidentificatie, factuur- en workflowbeheer, en de status van het in de wacht zetten van orders. Veelvoorkomende problemen zijn: Onbekende gegevens zoals API-versie, client-gebruikersnaam of client-ID. Ontbrekende of onjuiste factuur- of workflownummers. Problemen met de houdperiode, bijvoorbeeld het overschrijden van de maximale toegestane duur door beperkingen van gegarandeerde betaling. Fouten bij orderbeheer, zoals het proberen een order in de wacht te zetten wanneer dit niet mogelijk is of het gebruik van niet-ondersteunde parameters om een order te hervatten. Alle beschikbare foutcodes en meldingen voor On Hold API: Code Message 101 Onbekende client-gebruikersnaam of client-ID 103 Onbekende actie 104 Niet-ondersteunde parameter voor hervatten 401 Ontbrekend factuurnummer of workflownummer 402 Onbekend factuurnummer of workflownummer 403 De houdperiode is te lang vanwege gegarandeerde betaling (maximaal 14 dagen) 603 Redirect Billink API-fout 701 Order kan niet in de wacht worden gezet
  • [Resume Order API Fouten](https://ontwikkelaars.billink.nl/errors-fouten/resume-order.md): Samenvatting van Resume Order API-foutcodes De foutcodes van de Resume Order API richten zich vooral op de beschikbaarheid van gegevens en de validatie van de orderstatus. Veelvoorkomende problemen zijn: Ontbrekende of lege gegevens in het verzoek. Orders die niet in het systeem zijn gevonden. Orders die niet hervat kunnen worden vanwege hun huidige status. Code Message 400 Geen gegevens verzonden 400 Geen order gevonden 400 Order kan niet worden hervat!
  • [Order Info API Fouten](https://ontwikkelaars.billink.nl/errors-fouten/order-info.md): Samenvatting van Order Info API Foutcodes De foutcodes van de Order Info API hebben vooral betrekking op formuliervalidatie, toegangscontrole, sessiebeheer en serverfouten. Veelvoorkomende problemen zijn: Ontbrekende verplichte formuliervelden zoals billinkUsername. Toegang geweigerd vanwege onvoldoende permissies. Sessies die niet gevonden kunnen worden of zijn verlopen. Onverwachte serverfouten tijdens de verwerking. Code Message 400 Het formulier bevat de volgende fouten: 1) billinkUsername: Deze waarde mag niet leeg zijn. 403 Toegang geweigerd 404 Sessie niet gevonden 500 Er is iets misgegaan
  • [Message API Fouten](https://ontwikkelaars.billink.nl/errors-fouten/message.md): Samenvatting van Message foutcodes De Message API-foutcodes hebben vooral betrekking op authenticatie, het identificeren van bronnen en permissieproblemen bij het werken met het berichten­systeem. Veelvoorkomende problemen zijn: Ongeldige of onbekende client-gebruikersnaam of client-ID. Verwijzing naar een niet-bestaand workflow- of factuurnummer. Gebruik van een onjuiste HTTP-methode (bijvoorbeeld GET in plaats van POST). Pogingen om acties uit te voeren (zoals het loggen van een bericht) zonder de juiste toestemming. Alle beschikbare foutcodes en meldingen voor Message: Title Description 101 Onbekende client-gebruikersnaam of client-ID 401 Onbekend workflownummer 402 Onbekend factuurnummer 603 Fout in verzoek. Gebruik de POST-methode. 701 U bent niet gemachtigd om berichten aan het logboek toe te voegen, neem contact op
  • [Invoices](https://ontwikkelaars.billink.nl/errors-fouten/invoices-list.md): Samenvatting van Invoices endpoint foutcodes De Invoices foutcodes hebben voornamelijk betrekking op validatie, ontbrekende parameters, cliëntauthenticatie en onjuiste datumnotaties bij het ophalen van factuurgegevens. Veelvoorkomende problemen zijn: Verplichte velden zoals billinkID of billinkUsername ontbreken of zijn leeg. De verzonden data is geen geldige JSON-array. De datum heeft een onjuist formaat (moet dd-mm-jjjj zijn). Ongeldige kalenderdata worden opgegeven. Er wordt verwezen naar een niet-bestaande cliënt of hoofdcliënt. Alle beschikbare foutcodes en berichten voor de Invoices: Code Message 400 Er zijn geen gegevens verzonden 400 Geen geldige array aangeleverd 400 Veld billinkID is niet opgegeven 400 Veld billinkUsername is niet opgegeven 404 Cliënt is niet gevonden 404 Hoofdcliënt is niet gevonden 400 Veld date_from komt niet overeen met het patroon dd-mm-jjjj 400 Veld date_from is geen geldige datum 400 Veld date_to komt niet overeen met het patroon dd-mm-jjjj 400 Veld date_to is geen geldige datum
  • [Invoice Download](https://ontwikkelaars.billink.nl/errors-fouten/invoices-download.md): Overzicht van foutcodes voor de Download-endpoint De foutcodes voor de download-endpoint hebben voornamelijk te maken met ontbrekende of ongeldige invoergegevens, het niet kunnen vinden van de klant of hoofdklant, en problemen bij het genereren of ophalen van de vereiste PDF- of ZIP-bestanden. Veelvoorkomende problemen zijn onder andere: Verplichte velden zoals billinkID, billinkUsername, year of number ontbreken of zijn leeg. De ingediende data is geen geldige JSON-array. De opgegeven billinkID of billinkUsername komt niet overeen met een bestaande klant. Hoofdklant niet gevonden bij gebruik van gegroepeerde factuurlogica. Factuur niet gevonden op basis van de ingevoerde gegevens. Vereiste bestanden (PDF of HTML) ontbreken of kunnen niet uit HTML worden gegenereerd. Alle beschikbare foutcodes en foutmeldingen voor de download-endpoint: Code Message 400 Geen gegevens verzonden 400 Geen array opgegeven 400 Veld billinkID is niet opgegeven 400 Veld billinkUsername is niet opgegeven 400 Veld year is niet opgegeven 400 Veld number is niet opgegeven 400 Factuur niet gevonden 404 Klant niet gevonden 404 Hoofdklant niet gevonden 404 Kan pdf-bestand niet ophalen of genereren. Zie logbestand voor details
• [Billink merkactiva](https://ontwikkelaars.billink.nl/brand-assets/billink-merkativa.md): Welkom in onze merk toolkit. Hier kun je de logo’s vinden die je kunt gebruiken in jouw webshop. Plaats het Billink logo waar je ook de logo’s van andere betaalmethodes hebt staan. Het logo kun je o.a. plaatsen in de check-out, footer en bijvoorbeeld de productpagina en de landingspages. Tip: Implementeer de badges en logo's met directe link naar het bronbestand welke wij beschikbaar stellen. Lees meer.
• [Logo lockups](https://ontwikkelaars.billink.nl/brand-assets/logo-lockups.md): De logo's worden elk aangeboden in SVG (optimaal voor web-implementatie), AI, EPS, en 5 verschillende groottes PNG bestanden. Standaart oranje EPS / SVG / PNG / AI https://cdn.billink.nl/assets/Logov2/BILLINK_ORANGE_BILLINK_ORANGE.eps https://cdn.billink.nl/assets/Logov2/BILLINK_ORANGE.svg https://cdn.billink.nl/assets/Logov2/BILLINK_ORANGE.png https://cdn.billink.nl/assets/Logov2/BILLINK_ORANGE_BILLINK_ORANGE.ai Alternatief wit EPS / SVG / PNG / AI https://cdn.billink.nl/assets/Logov2/BILLINK_WHITE_BILLINK_WHITE.eps https://cdn.billink.nl/assets/Logov2/BILLINK_WHITE.svg https://cdn.billink.nl/assets/Logov2/BILLINK_WHITE.png https://cdn.billink.nl/assets/Logov2/BILLINK_WHITE_BILLINK_WHITE.ai Alternatief zwart EPS / SVG / PNG / AI https://cdn.billink.nl/assets/Logov2/BILLINK_BLACK_BILLINK_BLACK.ai https://cdn.billink.nl/assets/Logov2/BILLINK_BLACK_BILLINK_BLACK.eps https://cdn.billink.nl/assets/Logov2/BILLINK_BLACK.png https://cdn.billink.nl/assets/Logov2/BILLINK_BLACK.svg Billink One SVG / PNG https://cdn.billink.nl/assets/Logov2/BILLINK_ONE.png https://cdn.billink.nl/assets/Logov2/BILLINK_ONE.svg
• [Kleurcodes](https://ontwikkelaars.billink.nl/brand-assets/color-codes-1.md): Billink Primary #FF8D29 rgba(255,141,41) Billink Primary Light #FFEEDE rgba(255, 238, 222, 1) Billink Pastel Blue #9ABAE8 rgb(154, 186, 232) Billink Liliac #9577AD rgb(149, 119, 173) Billink Dark Taupe #16120D rgba(22, 18, 13)
• [Implementatie tips](https://ontwikkelaars.billink.nl/brand-assets/implementatie-tips.md): Verwijs direct naar de bron-afbeeldingen die hierboven weergegeven zijn en worden gehost op cdn.billink.nl. Maak bij voorkeur gebruik van de SVG bestanden ivm schaalbaarheid. We raden aan om de logo's te implementeren met een directe link naar de bron afbeelding zoals wij die hierboven beschikbaar stellen. We hebben hiervoor een zogenaamd CDN (Content Delivery Network) opgetuigd om laadtijden van slechts enkele milliseconden te kunnen garanderen. Het voordeel van een link naar de bronbestanden is dat je altijd gegarandeerd bent van de meest actuele weergave van de logo's en badges in lijn met de laatste merkstrategie van Billink.
• [Billink in je checkout](https://ontwikkelaars.billink.nl/brand-assets/billink-in-je-checkout.md): Om Billink duidelijk te laten weergeven bij de checkout, is het belangrijk om te vermelden dat de klant achteraf kan betalen. Dit staat centraal in hoe we als bedrijf naar buiten communiceren. Gebruik altijd de volgende tekst naast of achter het Billink-logo: Betaal achteraf met Billink Achteraf betalen met Billink Achteraf betalen Deze formuleringen zijn duidelijk en informeren de klant direct over de mogelijkheid om achteraf te betalen via Billink. Het is essentieel om deze teksten altijd in de checkout weer te geven. Voorbeeld:
• [Heb je een ander formaat nodig?](https://ontwikkelaars.billink.nl/brand-assets/heb-je-een-ander-formaat-nodig.md): Heb je een alternatief formaat nodig welke niet op deze pagina staat vermeld of heb je een andere vraag rond de implementatie van de logo's? Stuur een mail naar marketing@billink.nl .
• [Achteraf betalen brand assets](https://ontwikkelaars.billink.nl/achteraf-betalen/brand-assets.md): Deze toolkit bevat de assets en richtlijnen die nodig zijn om Achteraf betalen consistent te implementeren in je webshop. Toon de betaalbadge naast de andere beschikbare betaalmethoden in de checkout, zodat klanten de betaaloptie eenvoudig kunnen herkennen. De badge kan ook worden gebruikt op relevante contactmomenten binnen de customer journey, zoals productpagina's, landingspagina's en in de footer. Implementatietips Voor een optimale implementatie raden we aan om rechtstreeks naar de aangeleverde assets via de Billink CDN te verwijzen. Gebruik bij voorkeur SVG voor webimplementaties. Gebruik de officiële CDN-links om ervoor te zorgen dat altijd de meest recente assets worden gebruikt. Pas de aangeleverde bestanden niet aan. Maak geen eigen versies of exports van de assets. Behoud altijd de oorspronkelijke verhoudingen en kwaliteit. Achteraf betalen Toolkit Bekijk de Achteraf betalen Toolkit voor voorbeelden.
• [Betaalbadges](https://ontwikkelaars.billink.nl/achteraf-betalen/payment-badges.md): De betaalbadges zijn ontworpen voor gebruik in de checkout, naast de andere beschikbare betaalmethoden. De badges zijn beschikbaar in SVG- en PNG-formaat. Voor webimplementaties raden we aan om SVG te gebruiken voor optimale schaalbaarheid en een scherpe weergave op verschillende schermformaten en resoluties. Voorkeursbadge – standaard De betaalbadge met een zwarte achtergrond is de standaardvariant en heeft de voorkeur. Gebruik waar mogelijk altijd de standaardversie om een consistente en herkenbare implementatie te garanderen. Er is een brede variant beschikbaar voor layouts waarin de standaardbadge vanwege afmetingen of beperkte ruimte niet optimaal past. Gebruik de brede variant alleen wanneer deze beter binnen de beschikbare layout past. Standaard SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/SVG/achteraf-betalen-badge-default.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/PNG/achteraf-betalen-badge-default.png Breed SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/SVG/achteraf-betalen-badge-default-wide.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/PNG/achteraf-betalen-badge-default-wide.png Alternatieve badge – dark mode wit Voor donkere interfaces is een alternatieve badge met een effen witte achtergrond beschikbaar. Gebruik deze variant wanneer de standaardbadge onvoldoende contrast biedt met de achtergrond. Standaard SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/SVG/achteraf-betalen-badge-white.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/PNG/achteraf-betalen-badge-white.png Breed SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/SVG/achteraf-betalen-badge-white-wide.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/PNG/achteraf-betalen-badge-white-wide.png Alternatieve badge – dark mode transparant Voor donkere interfaces is ook een transparante variant beschikbaar. Deze versie maakt gebruik van witte contouren om voldoende zichtbaarheid tegen donkere achtergronden te garanderen. Gebruik deze variant alleen op achtergronden die voldoende contrast bieden. Standaard SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/SVG/achteraf-betalen-badge-transparent.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/PNG/achteraf-betalen-badge-transparent.png Breed SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/SVG/achteraf-betalen-badge-transparent-wide.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/badge/PNG/achteraf-betalen-badge-transparent-wide.png Light & dark mode Gebruik in light mode de standaardbadge met de zwarte achtergrond. Gebruik in dark mode een van de beschikbare dark-modevarianten. Selecteer de variant die voldoende contrast biedt met de achtergrond van de interface. Gebruik uitsluitend de officieel aangeleverde varianten. Maak geen eigen light- of dark-modeversies. Afmetingen & verhoudingen Schaal de betaalbadge altijd proportioneel en behoud de oorspronkelijke beeldverhouding. Rek de badge niet uit, snijd deze niet bij, roteer deze niet en wijzig de verhoudingen niet. Kleurgebruik De kleuren en visuele uitstraling van de betaalbadges staan vast en mogen niet worden aangepast. Gebruik altijd een van de officieel aangeleverde assets. Niet toegestaan: De achtergrond-, tekst-, contour- of merkkleuren wijzigen. De badge aanpassen aan je eigen merkidentiteit. Verlopen, effecten of transparantie toevoegen. De dekking (opacity) wijzigen. Afzonderlijke elementen verwijderen of aanpassen. De badge vervormen, roteren of bijsnijden. Eigen kleurvarianten maken.
• [Logo-lockups](https://ontwikkelaars.billink.nl/achteraf-betalen/logo-lockups.md): Logo-lockups zijn bedoeld voor merk- en contenttoepassingen, zoals FAQ-pagina's, landingspagina's en informatieve content. Gebruik voor implementatie in de checkout altijd de betaalbadges. Beschikbaar in SVG-, AI-, EPS- en PNG-formaat. Voor gebruik op het web wordt SVG aanbevolen. Voorkeursvariant – standaard SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/SVG/achteraf-betalen-default.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/PNG/achteraf-betalen-default.png AI — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/AI/achteraf-betalen-default.ai EPS — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/EPS/achteraf-betalen-default.eps Alternatieve variant – dark mode wit SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/SVG/achteraf-betalen-alternative-white.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/PNG/achteraf-betalen-alternative-white.png AI — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/AI/achteraf-betalen-alternative-white.ai EPS — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/EPS/achteraf-betalen-alternative-white.eps Alternatieve variant – dark mode transparant SVG — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/SVG/achteraf-betalen-alternative-transparent.svg PNG — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/PNG/achteraf-betalen-alternative-transparent.png AI — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/AI/achteraf-betalen-alternative-transparent.ai EPS — https://cdn.billink.nl/assets/achterafbetalen/v1/logo/EPS/achteraf-betalen-alternative-transparent.eps
• [Kleurcodes & typografie](https://ontwikkelaars.billink.nl/achteraf-betalen/color-codes-typography.md): Gebruik uitsluitend de aangeleverde kleurspecificaties. Kleuren die worden gebruikt binnen de Achteraf betalen-assets mogen niet worden gewijzigd of vervangen. Title Description Title Kleur HEX RGB Dark Taupe #16120B R22 G18 B11 Dark Grey #373737 R55 G55 B55 Typografie in de checkout Voor tekst die naast de betaalbadge wordt weergegeven, raden we aan om het bestaande sans-seriflettertype van de checkout of webshop te gebruiken. Zo blijft de betaalmethode visueel consistent met de andere beschikbare betaalmethoden. Als er een afzonderlijk lettertype moet worden ingesteld, gebruik dan een neutraal en goed leesbaar sans-seriflettertype, zoals: Arial Helvetica Roboto Open Sans Inter Gebruik geen decoratieve, handgeschreven of ongebruikelijke lettertypen.
• [Achteraf betalen in je checkout](https://ontwikkelaars.billink.nl/achteraf-betalen/in-your-checkout.md): De naam van de betaalmethode die aan de klant wordt getoond, moet overeenkomen met de taal van de webshop of checkout. Gebruik uitsluitend de volgende goedgekeurde benamingen: Nederlands (NL) – Achteraf betalen Engels (EN) – Pay later Duits (DE) – Später bezahlen Wanneer lokalisatie wordt ondersteund, moet de weergegeven naam van de betaalmethode zich dynamisch aanpassen aan de taalinstelling van de webshop of checkout.
• [Ander formaat nodig?](https://ontwikkelaars.billink.nl/achteraf-betalen/need-a-different-format.md): Heb je een alternatief formaat nodig welke niet op deze pagina staat vermeld of heb je een andere vraag rond de implementatie van de Achteraf betalen-assets? Stuur een mail naar marketing@billink.nl .
• [Contactgegevens](https://ontwikkelaars.billink.nl/contactgegevens.md): Wij kijken uit naar een succesvolle samenwerking. Mocht je toch niet helemaal uit de integratie komen helpen we je graag. Dit kan op werkdagen via support@billink.nl of via 010 - 414 14 73 Als je nog vragen hebt, kun je hier antwoorden vinden