Met de Twikey-integratie kun je SEPA-mandaten aanmaken voor sales waarvoor de klant een automatische incasso afgeeft. Zodra een sale wordt ondertekend, stuurt Salesdock de gegevens naar Twikey, krijgt een mandaat-link terug en plaatst die in de bevestigingsmail of op de offertepagina. De klant geeft vervolgens via zijn eigen bankomgeving toestemming.

Twee mandaat-trigger-scenario’s om eerst te kiezen

Voordat je in de instellingen duikt, is er één strategische vraag te beantwoorden: vanuit welke Salesdock-omgeving wil je dat het Twikey-mandaat wordt aangemaakt? Bij integraties tussen twee Salesdock-omgevingen (provider die sales pusht naar consumer) heb je daarin twee opties.

Hoe stel je het scenario in? Het verschil zit in één instelling op de consumer-omgeving: Maak een ontbrekend mandaat aan voor integratiepartners. Staat die op Nee, dan triggert alleen de provider. Staat die op Ja, dan triggert de consumer. Hebben beide kanten Twikey ingericht? Zet dan op de consumer-kant ook Controleer op de aanwezigheid van een bestaand mandaat aan, zodat de consumer eerst checkt of de provider al een mandaat heeft aangemaakt voor dezelfde IBAN en contracttemplate, en geen dubbele mandaten ontstaan.

Stap 1: De Twikey-app installeren

Ga naar Apps, zoek de Twikey-app op en installeer deze. Open vervolgens de app om de configuratie te starten.

De app heeft vier tabbladen: Settings, API settings, Sale data mapping en Status mapping. Hieronder lopen we ze in volgorde door.

Stap 2: Settings

In het tabblad Settings regel je het algemene gedrag van de integratie:

1. Automatische orderverwerking — bij Aan wordt het Twikey-mandaatverzoek automatisch aangemaakt zodra een sale is ondertekend. Het advies is om dit aan te zetten, behalve wanneer je werkt met de mandaatknop op de offertepagina (zie punt 7).
2. Leveranciers — selecteer voor welke leveranciers de Twikey-integratie geldt. Sales op andere leveranciers worden niet naar Twikey gestuurd.
3. Controleer statusupdates — bij Aanhaalt Salesdock periodiek mandaatstatussen op uit Twikey en synchroniseert deze terug op de sale. Statussen worden ieder uur opgehaald en daarnaast één keer per nacht (rond 00:05) als veiligheidsnet voor gemiste updates.
   • Synchroniseer tot 3 dagen terug — de nachtelijke check loopt tot drie dagen terug om gemiste updates op te halen.
   • Allowed statuses — welke Salesdock-statussen mogen worden overschreven door de synchronisatie. Sales die op een niet-toegestane status staan blijven onaangetast.
4. Annuleer geannuleerde sales bij Twikey — bij Aan wordt een actief mandaat in Twikey ook geannuleerd zodra de sale in Salesdock geannuleerd wordt.
5. E-mail mandaat button-label — de tekst op de knop in de bevestigingsmail die de klant naar Twikey leidt.
6. Extra veld om het mandaat-ID op te slaan — verplicht. Maak hiervoor eerst een tekstveld aan via Instellingen → Extra velden → Transactie en koppel dat aan de relevante producttypes. Selecteer het hier zodat Salesdock het Twikey-mandaat-ID per sale kan opslaan en vinden.
7. Toon mandaat-URL op de klantaanbiedingspagina — bij Javerschijnt er na het accepteren van een offerte een mandaatknop op de offertepagina. Pas wanneer de klant op die knop klikt, wordt de Twikey-API aangeroepen.
   • Werkt alleen voor offertes — niet voor directe orders.
   • In combinatie met deze instelling kun je Automatische orderverwerking uitzetten zodat het mandaat niet al direct bij ondertekening wordt aangemaakt.
8. Controleer op de aanwezigheid van een bestaand mandaat — bij Aan controleert Salesdock vooraf of de klant al een geldig, getekend mandaat heeft op dezelfde contracttemplate en IBAN. Als dat zo is, wordt er geen nieuw mandaat aangemaakt en wordt het bestaande mandaat-ID gekoppeld aan de sale. Vooral nuttig in scenario’s waarin zowel provider als consumer Twikey hebben en je dubbele mandaten wilt voorkomen.
9. Maak een ontbrekend mandaat aan voor integratiepartners — bepaalt of jouw omgeving (als consumer) ook mandaten aanmaakt voor sales die via een integratie binnenkomen. Zet je deze op Ja, dan triggert de consumer het mandaat. Zet je deze op Nee, dan blijft mandaatcreatie aan de providerkant.
10. Moet Twikey het mandaat versturen — alleen relevant als de vorige instelling op Ja staat. Bepaalt of Twikey zelf de mandaat-uitnodigingsmail naar de klant verzendt, of dat dit aan de Salesdock-bevestigingsmail wordt overgelaten.

Stap 3: API settings

Hier vul je de credentials van je Twikey-account in. Je krijgt deze van Twikey aangeleverd.

1. Modus — kies tussen Productie en Test. De host en API-token verschillen per modus, dus zorg dat je consistent bent met de bijbehorende credentials.
2. Host — de URL die Twikey aanlevert. Voor de testomgeving is dit doorgaans https://api.beta.twikey.com; voor productie krijg je een omgeving-specifieke URL.
3. API-token — te genereren in je Twikey-account.

Stap 4: Sale data mapping

In dit tabblad koppel je velden uit jouw flow aan de gegevens die Twikey verwacht. De velden 1 t/m 5 zijn altijd relevant; 6 t/m 10 zijn alleen nodig als je werkt met abonnementen.

1. Betaalwijze — koppel de productvraag waarmee je in de flow uitvraagt hoe de klant wil betalen. Sla op en geef daarna aan welke optie staat voor Automatische incasso. Salesdock roept Twikey alleen aan wanneer die optie is gekozen én de leverancier in stap 2 is geselecteerd.
2. Contracttemplate-ID— het Twikey-contracttemplate dat gebruikt moet worden voor zakelijke en consument-sales. Inrichten in drie stappen:
   • Ga naar Instellingen → Extra velden → Leveranciers en maak twee tekstvelden aan: één voor het zakelijke template-ID en één voor het consumenten-template-ID. Maak alleen wat je nodig hebt.
   • Ga naar Producten → Leveranciers, open de leverancier en vul de template-ID’s in.
   • Kom terug naar Sale data mapping en koppel hier Contracttemplate zakelijk en Contracttemplate consumenten aan de extra velden die je net hebt gemaakt. Salesdock kiest automatisch het juiste template op basis van het type sale (zakelijk of consument).
3. Accordering consument — als je deze aanvinkt, gebruikt Salesdock altijd het consumenttemplate, ook bij zakelijke sales. Bedoeld voor het scenario waarin een consument-IBAN wordt gebruikt voor een zakelijke sale en de klant daarvoor expliciet akkoord geeft.
4. Accordering zakelijk — spiegelinstelling van punt 3: forceert het zakelijke template, ongeacht het saletype.
5. BIC (optioneel) — koppel hier de productvraag voor de BIC, indien je die in de flow uitvraagt.

De volgende velden zijn alleen nodig voor abonnementen:

6. Plan — koppel hier het extra veld waarin je de Twikey-plan-waarde opslaat (bijvoorbeeld op leverancier- of productniveau). De waarde haal je op uit je Twikey-account.
7. Start van het abonnement — koppel een datum-productvraag, of gebruik de overstapdatum als die in de flow zit.
8. Aantal incasseringen — koppel een product-extraveld van het type meerkeuze (bijvoorbeeld ‘elke week’, ‘elke maand’, ‘elk kwartaal’). Na opslaan verschijnt er een output-mapping om elke meerkeuze-optie te koppelen aan de waarde die Twikey verwacht.
9. Looptijd — het aantal incasso’s waarna het abonnement automatisch stopt. Werkt op dezelfde manier als het vorige veld.
10. Abonnementskosten — bepaalt welk bedrag naar Twikey wordt gestuurd (bijvoorbeeld de totale maandkosten incl. btw, of de eenmalige kosten zonder btw).

Stap 5: Status mapping

Twikey rapporteert per mandaat twee statussen terug: Getekend (de klant heeft het mandaat in de bank getekend) en Geannuleerd. In dit tabblad koppel je deze aan een Salesdock-status zodat de sale automatisch op de juiste status komt zodra de klant in de bankomgeving heeft getekend of geannuleerd.

Tip: de statussen die je hier kiest moeten in de instelling Allowed statuses (Settings, punt 3) staan, anders worden ze niet automatisch overschreven door de synchronisatie.

Stap 6: Bevestigingsmail aanpassen

Open Instellingen → E-mails & SMS → Sale-bevestiging. In het variabelen-overzicht onder sale vind je twee Twikey-specifieke variabelen:

• sale.twikey_mandate_button — rendert een complete knop met de tekst die je bij E-mail mandaat button-label hebt ingesteld.
• sale.twikey_mandate_url — rendert alleen de URL, voor wanneer je zelf de knop wilt vormgeven.

Een eenvoudige template waarbij de mandaatknop alleen verschijnt als de klant voor automatische incasso heeft gekozen:

{{#productquestions.is.betaalwijze.Automatische incasso}}
Je hebt gekozen voor een automatische incasso. We hebben jouw toestemming
nodig om periodiek een bedrag van jouw rekening te incasseren. Klik op de
onderstaande knop om die toestemming te geven.

{{{sale.twikey_mandate_button}}}

{{/productquestions.is.betaalwijze.Automatische incasso}}

De productvraag-identifier betaalwijze en de antwoordoptie Automatische incasso kunnen op jouw omgeving anders heten — pas ze in de tag aan op wat in jouw flow staat.

Werk je alleen met offertes? Dan is de bevestigingsmail-stap niet noodzakelijk, mits je in stap 2 de instelling Toon mandaat-URL op de klantaanbiedingspagina hebt aangezet. De klant ziet de mandaatknop dan direct op de offertepagina nadat hij de offerte heeft geaccepteerd.

Synchronisatie en timing

Een paar tijdgerelateerde feiten die handig zijn om te weten als je gaat troubleshooten:

• Mandaat aanmaken gebeurt direct na het ondertekenen van de sale, of pas wanneer de klant op de mandaatknop op de offertepagina klikt — afhankelijk van wat je hebt ingesteld.
• Status-synchronisatie draait elk uur. Daarnaast loopt er om 00:05 een nachtelijke job die kijkt tot drie dagen terug, om eventueel gemiste statusupdates alsnog op te halen.
• Annulering wordt synchroon doorgevoerd: bij annulering van een sale die al een actief mandaat heeft, wordt het mandaat in Twikey direct ingetrokken (mits je dit hebt aangezet onder Annuleer geannuleerde sales bij Twikey).

Veelgestelde vragen

De klant heeft het mandaat getekend, maar de Salesdock-sale staat nog op de oude status. Wat nu?
Wacht maximaal een uur (de status-sync draait per uur) of trigger handmatig een sync. Staat de status na een nacht nog niet juist? Check dan dat de Twikey-status (Getekend / Geannuleerd) gekoppeld is aan een Salesdock-status én dat die Salesdock-status in Allowed statuses staat.

Er ontstaan dubbele mandaten omdat zowel provider als consumer er een aanmaken.
Activeer aan de consumer-kant Controleer op de aanwezigheid van een bestaand mandaat. De consumer doet dan eerst een lookup op IBAN + contracttemplate en gebruikt het bestaande mandaat als dat al getekend is.

De klant ontvangt twee mandaat-uitnodigingen.
Dit kan gebeuren als zowel Salesdock als Twikey zelf een uitnodiging stuurt. Zet ofwel de variabele uit de bevestigingsmail, ofwel de instelling Moet Twikey het mandaat versturen uit — niet allebei aan.

Hoe test ik de integratie zonder echte mandaten aan te maken?
Zet onder API settings de Modus op Test en gebruik je test-credentials. Mandaatverzoeken gaan dan naar de Twikey-test-omgeving en raken je productie niet.