Basisconcepten

Authenticatie

Alle API-verzoeken moeten een geldig sessietoken bevatten in de Authorization-header. Dit token kan worden verkregen via het login-endpoint en blijft 24 uur geldig. Het is aan te raden om de login-aanroep te activeren wanneer het eigenlijke verzoek een 401 Unauthorized-antwoord retourneert. Deze aanpak vereenvoudigt tokenbeheer doordat een nieuw token alleen wordt aangevraagd wanneer dat nodig is.

Feeds

Statuswijzigingen komen veel vaker voor bij overeenkomsten, facturen en transacties dan bij reguliere eenmalige betalingen. Aangezien geen enkel event gemist mag worden en meerdere webhooks mogelijk niet in de juiste volgorde aankomen door netwerklatentie, biedt Twikey "feeds" of wachtrijen aan, die in feite een lijst zijn van events die nog niet ontvangen zijn.

Elke datafeed (of wachtrij van events) bevat het laatste volgnummer (X-LAST) waarmee clients kunnen hervatten vanaf een specifiek punt in de eventstroom (via de request-header X-RESUME-AFTER). Dit mechanisme is bijzonder nuttig voor foutherstel of bij het opnieuw verbinden na een onderbreking (en ook erg handig bij het testen).

De feed dient gelezen te worden totdat er geen items meer over zijn. Het cruciale punt is totdat er geen verdere updates beschikbaar zijn. Dit garandeert dat elke update correct wordt verwerkt en dat er niets gemist wordt.

Vermijd dat meerdere clients in het netwerk dezelfde feed tegelijkertijd benaderen met dezelfde API-sleutel, aangezien dit kan leiden tot race conditions en inconsistente data. Als gelijktijdige toegang noodzakelijk is, overweeg dan een van de volgende benaderingen:

  • Gebruik afzonderlijke API-sleutels: wijs een unieke API-sleutel toe aan elke client. Extra sleutels kunnen worden gegenereerd vanuit het Twikey-instellingenmenu.
  • Implementeer een master-client-patroon: wijs een enkele client aan als master om de feed op te halen. Andere clients lezen data uit een gedeelde datastore die door de master wordt beheerd.

Aangezien beveiliging essentieel is voor betalingen, heeft Twikey besloten om geen details over betalingen door te geven in webhooks, maar deze alleen beschikbaar te stellen in verzoeken die vanuit de integratie komen. Specifieke "detail"-aanroepen over een object zijn mogelijk, maar aangezien deze slechts een momentopname zijn van het object op dat moment (en mogelijk al gewijzigd zijn tegen de tijd dat het verwerkt is), zijn er rate-limits ingesteld om overmatig gebruik te voorkomen.

Include-parameters Sommige feeds ondersteunen include-parameters om aanvullende details in het antwoord op te vragen. De beschikbare includes varieren per feed en zijn gedocumenteerd in de API-referentie. Standaard retourneren feeds een compact antwoord om de payload-grootte te minimaliseren.

Webhooks vs Polling

Twikey ondersteunt 2 soorten integraties.

Bij een push-fetch-architectuur informeert Twikey over een event via een webhook. Deze webhook kan als trigger worden gebruikt om alle events uit de feed (of wachtrij) op te halen en interne systemen bij te werken.

Opmerking: Webhooks dienen alleen als notificaties en moeten dienovereenkomstig worden behandeld. Om dubbele leveringen door timeouts of retries te voorkomen, is het van belang dat alle interne bedrijfslogica asynchroon wordt afgehandeld.

Het alternatief is een pull-architectuur, waarbij clients periodiek updates ophalen bij Twikey om de laatste status binnen Twikey te verkrijgen. Deze architectuur is geschikt voor situaties waarin geen inkomende webhooks zijn toegestaan. Het nadeel is echter dat er een vertraging is tussen het moment waarop een event plaatsvindt in Twikey en het moment waarop het event ontvangen wordt.

Hybride oplossingen waarbij hooks worden gecombineerd met terugkerende pulls zijn uiteraard ook mogelijk.

Idempotentiesleutels

Wanneer een verzoek mislukt door een netwerkprobleem, kan het onduidelijk zijn of het verzoek de server heeft bereikt of niet. Opnieuw proberen zonder voorzorgsmaatregelen kan leiden tot dubbele bewerkingen. Idempotentiesleutels lossen dit op door te garanderen dat een verzoek met dezelfde sleutel slechts eenmaal wordt verwerkt.

Twikey ondersteunt de standaard idempotentie-header voor creatieendpoints van transacties, terugbetalingen en abonnementen.

Idempotency-Key: "your unique reference"

Hoe het werkt:

  • Eerste verzoek: wordt normaal verwerkt. Het antwoord wordt opgeslagen en gekoppeld aan de sleutel.
  • Dubbel verzoek tijdens verwerking: retourneert 409 Conflict, wat aangeeft dat het oorspronkelijke verzoek nog wordt verwerkt.
  • Dubbel verzoek na voltooiing: retourneert het oorspronkelijke antwoord (dezelfde HTTP-statuscode en body), ongeacht of het oorspronkelijke verzoek geslaagd of mislukt is.

Een idempotentiesleutel kan slechts eenmaal per endpoint worden gebruikt. Nadat een antwoord is geretourneerd voor een bepaalde sleutel, retourneert elk volgend verzoek met dezelfde sleutel dat opgeslagen antwoord.

Vervaltijd van sleutels: Idempotentiesleutels vervallen na 24 uur. Na het vervallen kan dezelfde sleutel opnieuw worden gebruikt.

Merk op dat veel Twikey-bewerkingen al impliciet idempotent zijn. Bijvoorbeeld, het meerdere keren annuleren van hetzelfde mandaat heeft geen nadelig effect.

Foutafhandeling

API-fouten vallen in twee hoofdcategorieen:

  1. Clientfouten (HTTP 400):

    Deze treden op door problemen in het verzoek en worden gecommuniceerd via een 400 Bad Request-antwoord. Een ApiError-header wordt meegestuurd met verdere details over het probleem. Het foutbericht is gelokaliseerd op basis van de Accept-Language-header. Als deze header niet wordt meegegeven, is het bericht standaard in het Engels.

  2. Serverfouten (HTTP 500):

    Deze duiden op een interne fout aan de serverzijde. Hoewel zeldzaam, wijzen ze op een onverwachte fout in de API. In de meeste gevallen is het team al op de hoogte van dergelijke incidenten wanneer ze zich voordoen.