Stripe koppelen | Helpcentrum

Wat je nodig hebt

De rol Admin of Member in je organisatie. Viewers hebben geen toegang tot Koppelen. Zie Wie mag koppelen?.
Tweestapsverificatie (2FA) op je APIboard-account.
Een vrije plek in je pakket: Proefperiode en Basis 3 koppelingen, Team 7, Pro 10 (plus eventueel een gekochte extra koppeling).
Toegang tot het Stripe-dashboard met het recht om API-sleutels aan te maken.

Verbinden

Ga in APIboard naar Koppelen > Koppelingen.
Zoek Stripe bij Beschikbare koppelingen (of typ de naam in het zoekveld) en klik op de kaart. Er opent een venster dat je stap voor stap begeleidt.
Ga in Stripe naar Ontwikkelaars en open API-sleutels.
Kies Restricted key aanmaken en geef aan dat de sleutel voor een andere website is. Vul als link https://www.apiboard.nl in.
Geef de sleutel de naam APIboard, maak hem aan en kopieer hem. Stripe bepaalt in deze route zelf welke rechten de sleutel krijgt; je hoeft niets aan te vinken.
Plak de sleutel in het veld Restricted key in APIboard. Vul eventueel een naam voor de koppeling in.
Klik op Koppelen.
APIboard haalt direct de eerste gegevens op (Data wordt opgehaald…). Daarna zie je Verbonden met Stripe, met de dashboards die klaarstaan. Op Koppelen > Koppelingen staat de pil Bezig met ophalen… tot de eerste volledige ronde klaar is; daarna staat er Actief.

APIboard leest alleen. Er wordt nooit iets in je Stripe-account gewijzigd. Een secret key (begint met sk_) of publishable key (begint met pk_) werkt niet en wordt geweigerd: alleen een restricted key (rk_live_ of rk_test_) is toegestaan.

Testmodus

Een restricted key voor de testmodus (rk_test_) werkt ook. De koppeling krijgt dan de toevoeging (testmodus) achter de naam. Testmodus en live van hetzelfde Stripe-account zijn twee aparte koppelingen en tellen elk mee voor de koppelingenlimiet van je pakket. Zo kun je eerst met testgegevens kijken hoe de dashboards eruitzien.

Account kiezen

Er is geen keuzescherm: één sleutel hoort bij één Stripe-account. Heb je meer Stripe-accounts, koppel ze dan elk met een eigen sleutel (binnen de koppelingenlimiet van je pakket). Hetzelfde account kun je niet twee keer koppelen. Onderliggende accounts van Stripe Connect worden niet opgehaald.

Welke gegevens je krijgt

Onderwerp	Tabellen
Klanten en aanbod	Klanten, Producten, Prijzen, Kortingsbonnen, Promotiecodes
Abonnementen	Abonnementen, Abonnementsregels
Facturen	Facturen, Factuurregels, Creditnota’s, Creditnotaregels
Betalingen	Betalingen, Terugbetalingen, Geschillen
Geldstroom	Uitbetalingen, Saldotransacties (met de Stripe-kosten per transactie)

Bedragen staan in hoofdeenheden (euro’s, niet in centen), ook voor valuta’s zonder decimalen zoals de yen. Statussen en soorten komen ook als leesbare tekst mee (de kolommen met _label). Metadata die je zelf in Stripe bij klanten, producten, prijzen, abonnementen, facturen en betalingen zet, is te gebruiken in de API, de AI-koppeling en de Datawerkbank. Je vraagt de gegevens op via de API en ziet ze in de Datawerkbank. Alle tabellen en velden staan in de API-documentatie van Stripe.

MRR in Studio

In de Studio-dashboards Abonnementen en Geldstroom zie je onder meer je MRR, ARR, het aantal actieve abonnementen, nieuw en opgezegd per maand en je Stripe-kosten. APIboard rekent de MRR bij het openen van het dashboard uit, op basis van de gegevens van dat moment:

Alleen abonnementen met de status Actief of Achterstallig tellen mee, en alleen als de incasso niet is gepauzeerd.
Per abonnementsregel telt het maandbedrag van de prijs maal het aantal. Jaarprijzen worden door 12 gedeeld, weekprijzen en dagprijzen naar een maand omgerekend, en een prijs per meerdere maanden (bijvoorbeeld per kwartaal) wordt door dat aantal gedeeld.
Korting die op dat moment geldt, gaat eraf. Een tijdelijke korting verdwijnt uit de MRR zodra die afloopt.
Een proefperiode zonder betaling telt niet mee zolang het abonnement niet actief is.

Studio toont bedragen altijd met het euroteken. Heb je abonnementen in een andere valuta (bijvoorbeeld dollars), dan klopt het bedrag, maar staat er in Studio toch een euroteken. Het dashboard heeft een valutafilter om één valuta tegelijk te bekijken.

Hoe vaak vernieuwd

APIboard houdt wijzigingen bij via de gebeurtenissen die Stripe bewaart: nieuwe en gewijzigde klanten, abonnementen, facturen, betalingen en uitbetalingen komen elke ronde binnen. Voor elk gewijzigd object haalt APIboard daarna de actuele stand op, zodat je niet met een verouderde momentopname werkt. Saldotransacties (de kosten en uitbetalingsregels) hebben geen gebeurtenissen en worden elke ronde apart aangevuld. Elke ronde controleert APIboard ook kort of er gebeurtenissen ontbreken. Is dat zo, dan vult APIboard de betreffende tabel automatisch aan en krijgt het platform een melding.

De eerste vulling van gegevens met een datum (zoals facturen en betalingen) begint op 1 januari van het jaar dat bij je pakket hoort: Proefperiode en Basis dit kalenderjaar, Team ook vorig jaar, Pro ook twee jaar terug. Klanten, producten, prijzen en abonnementen worden altijd volledig opgehaald. Wat al is opgehaald, verwijdert APIboard niet als je pakket kleiner wordt.

Hoe vaak dat gebeurt, hangt af van je pakket (Proefperiode, Basis, Team of Pro): zie Hoe vaak worden gegevens vernieuwd?.

Wat we niet ophalen

Wijzigingen terugschrijven: APIboard leest alleen.
Kaartgegevens en betaalmethoden, behalve het soort betaalmethode, het kaartmerk en het land van de kaart.
Stripe Connect (onderliggende accounts, transfers en applicatiekosten), Issuing, Terminal, Treasury, Climate en Identity.
Checkout-sessies, betaallinks, offertes, abonnementsplanningen, losse factuurregels, belastingtarieven, Radar-reviews, bestanden en rapportages.
Betaalpogingen (payment intents) als eigen tabel: het nummer staat wel op de betaling.

Goed om te weten

Verwijderde rijen. Verwijdert iemand in Stripe een klant, product, prijs, kortingsbon of conceptfactuur, dan markeert APIboard die rij als verwijderd bij de bron; er wordt nooit iets echt gewist. Betalingen, uitbetalingen, abonnementen en creditnota’s verwijdert Stripe niet.
Opgezegde abonnementen blijven staan, met de datum van opzeggen en, als Stripe die kent, de reden en de opmerking van de klant.
Opnieuw verbinden vervangt alleen je sleutel. De koppeling, alle opgehaalde gegevens en de syncstand blijven staan, de status gaat terug naar Actief en de volgende synchronisatie haalt alleen wijzigingen op. Gebruik een sleutel van hetzelfde Stripe-account en dezelfde modus. Je vindt Opnieuw verbinden (pijlicoon) in het zijpaneel dat opent als je op de kaart van de koppeling klikt.
Een koppeling verwijderen (Koppeling verwijderen) wist ook alle opgehaalde gegevens. Dat kan niet ongedaan worden gemaakt.
APIboard laat tijd tussen de aanroepen en verdeelt een grote eerste vulling over meerdere runs, zodat je Stripe-account niet onnodig belast wordt.

Bronbeperkingen

MRR-historie. De MRR per maand in het verleden is berekend met de regels die een abonnement nu heeft. Stripe bewaart geen geschiedenis van prijswijzigingen, dus een abonnement dat in de loop van de tijd van prijs wisselde, telt in het verleden met zijn huidige prijs.
Btw. Heb je prijzen die inclusief btw zijn ingesteld, dan telt de MRR dat bedrag inclusief btw, omdat Stripe de btw per prijs niet apart doorgeeft.
Staffel- en gebruiksprijzen. Abonnementen met staffelprijzen of prijzen per verbruik tellen alleen hun vaste regels mee in de MRR. De dashboards tonen daar een toelichting bij.
Valuta. Bedragen in andere valuta dan euro’s kloppen als bedrag, maar Studio toont altijd het euroteken.
Uitbetalingen en saldotransacties. Een saldotransactie hoort alleen bij zijn uitbetaling als Stripe de uitbetaling automatisch deed. Bij handmatige uitbetalingen blijft die koppeling leeg. Saldotransacties die nog in behandeling zijn, worden eenmalig opnieuw gelezen zodra ze beschikbaar zijn.
Testklokken. Objecten die bij een Stripe-testklok (test clock) horen, staan niet in de lijsten van Stripe en komen alleen binnen via gebeurtenissen.
Ouderdom van gebeurtenissen. Stripe bewaart gebeurtenissen 30 dagen. Was je koppeling langer dan 29 dagen onderbroken (bijvoorbeeld een ingetrokken sleutel), dan leest APIboard na herstel alle tabellen opnieuw in, binnen de periode die bij je pakket hoort.

Problemen oplossen

Gebruik een restricted key met alleen leesrechten, geen secret key. Je hebt een sleutel geplakt die begint met sk_ of pk_. Maak in Stripe een restricted key aan zoals bij Verbinden en plak die.
Dit is geen Stripe restricted key. De sleutel begint niet met rk_live_ of rk_test_. Controleer of je de hele sleutel hebt gekopieerd, zonder spaties.
Deze Stripe-sleutel is ongeldig of ingetrokken. De sleutel is verkeerd gekopieerd of in Stripe verwijderd. Maak een nieuwe aan en gebruik zo nodig Opnieuw verbinden.
Geef de sleutel leesrecht op Events. Dit zie je alleen als de sleutel zonder de aanbevolen route is aangemaakt met minder rechten. Zonder Events kan APIboard niet bijhouden wat er wijzigt. Maak de sleutel opnieuw aan voor een andere website, met link https://www.apiboard.nl.
Een tabel is leeg of niet beschikbaar. Bij een sleutel met beperkte rechten staan tabellen waar de sleutel niet bij mag als niet beschikbaar. Maak een nieuwe sleutel zoals bij Verbinden en gebruik Opnieuw verbinden.
Dit Stripe-account is al gekoppeld. Wat je probeert te koppelen, staat al in je organisatie. Zoek het op onder Koppelen > Koppelingen. Let op: testmodus en live zijn aparte koppelingen.
Stripe is tijdelijk niet bereikbaar. Probeer het later opnieuw.
Viewers kunnen geen koppelingen beheren. Je hebt de rol Viewer. Vraag een Admin van je organisatie om je de rol Member te geven, of om de koppeling te maken.
Je hebt je koppelingen-limiet bereikt voor je pakket. Kies Bekijk abonnementen om te upgraden, of koop een extra koppeling.
De pil Fout bij de koppeling. Een synchronisatie is mislukt of de sleutel is ingetrokken. APIboard probeert het bij een tijdelijke fout later zelf opnieuw; bij een ingetrokken sleutel gebruik je Opnieuw verbinden.