TABLE OF CONTENTS

• Inleiding
• Buckaroo account
• Configuratie
  • Buckaroo Portal
  • TriplEforms Configuratie
    • Licentie
    • Configuratie binnen TriplEforms
      • Project.tfProject
      • Web.config
• Module gebruiken binnen een scenario
  • Properties
    • CustomParametersJSON
    • EnableExpiredCertificates
  • Result Parameters
  • Betaalscenario
• Webhooks - Asynchrone afhandeling
  • Webhook processor
  • Configuratie NonInteractive in Web.config
  • Scenario & Flow
    • Scenario
    • Flow
      • TransactionDetails object
• SSL Offloading

Inleiding

De Buckaroo module is een betaalmodule voor TriplEforms die gebruik maakt van de Buckaroo payments API. Hiermee kunnen betalingen worden uitgevoerd worden door gebruikers van een TriplEforms-formulier met allerlei betaalmogelijkheden, zoals IDEAL, Mastercard en Visa.

Buckaroo account

Voordat je kunt beginnen met het testen/gebruiken van de Buckaroo module, heb je een Buckaroo account nodig. Op Bitwarden staat een Kodision test account.

Let op: op dit account zijn niet alle betaalwijzen beschikbaar.

Je krijgt vanuit Buckaroo de volgende gegevens bij het account:

Configuratie

Onderstaand is informatie te vinden over het configureren van de Buckaroo Module.

Buckaroo Portal

In het Buckaroo portal moeten een aantal instellingen goed gezet worden, wanneer dit niet goed staat, zal de module niet (correct) werken.

Instellingen onder Mijn Buckaroo -> Websites

• Algemeen
  • Gebruik betaalpagina -> Ja
• Redirect
  • Gebruik Get in plaats van POST voor redirects -> Ja
  • Overige velden mogen leeg zijn, kan als fallback gebruikt worden
• Push instellingen
  • Vertraagde en push response
    • Push response aanzetten -> Ja
    • Rest niet aanvinken
  • Push URI Succes/Pending
    • Fallback als module niet correct is ingevuld, moet naar NonInteractive wijzen
  • Gebruik HTTP-Method -> POST
  • Push type -> BPE3.0
  • Hash-methode -> SHA256
  • BPE3.0 return-velden -> Kleine letters
  • Selecteer push contenttype -> JSON
  • Overige velden mogen leeg gelaten worden
• 3.0 Instellingen
  • Mogen allemaal leeg / op defaults
  • 
    

Instellingen onder Mijn Buckaroo -> Abonnementen

• Onder ‘Betaalmethoden’ zijn de actieve betaalmethoden beschikbaar. Op een test account is het niet mogelijk om er een toe te voegen, of te verwijderen.

Instellingen onder Configuratie -> Beveiliging

• Secret Key
  • Vul een unieke secret key voor een hash in (hoe langer hoe veiliger)
• Certificaten
  • Download of upload een certificaat voor TLS1.2 server-to-server
  • Let op: De certificaten die Buckaroo op een testaccount genereert, zijn niet compleet! Het is beter om een eigen certificaat te gebruiken.

Instellingen onder Weergave Betaalpagina

Hier kan de betaalpagina gestyled worden naar behoefte van de klant.

TriplEforms Configuratie

Licentie

De Buckaroo Module zit achter een licentie categorie binnen TriplEforms en is dus niet bruikbaar, indien de module niet gelicenseerd is. Alleen een medewerker van Kodision kan de betreffende licentie uitbreiden. Het is dus noodzakelijk dat de module eerst gelicenseerd wordt, voordat de verdere configuratie stappen uitgevoerd worden.

Configuratie binnen TriplEforms

Er zijn twee stappen benodigd om de Buckaroo Module te kunnen gebruiken binnen een TriplEforms scenario. De stappen zijn:

• Project.tfProject: De module toevoegen aan de TriplEforms-editor
• Web.config: De basis configuratie voor de Buckaroo Module toevoegen aan de Web.config

Project.tfProject

De module dient te worden geïnstalleerd in het TriplEforms-project door het volgende toe te voegen aan het Project.tfProject-bestand. Dit kan op twee manieren:

• Via de TriplEforms Editor
• Handmatig via Notepad++

TriplEforms Editor

Voer onderstaande stappen uit om de module toe te voegen via de TriplEforms Editor:

Open de Project.tfProject-file binnen de Editor. Dubbelklik in de Solution Explorer op Project.

Maak een nieuwe module aan onder Modules en noem deze Buckaroo Payments.

Vul onderstaande gegevens in:

Handmatig  

Een alternatieve manier t.o.v. de TriplEforms Editor is het handmatig toevoegen van XML aan het Project.tfProject-bestand via Notepad++. Voeg onderstaande XML toe binnen de <ef:modules>-tag:

<ef:module id="Buckaroo Payments" type="usercontrol" url="~/Buckaroo/Buckaroo.ascx" progressWeight="10">
  <ef:description>The Buckaroo payment user control.</ef:description>
  <ef:parameters>
    <ef:parameter name="PaymentUrl" mandatory="false" description="The base url for the Buckaroo api. Defaults to the url configured in the web.config."/>
    <ef:parameter name="WebsiteKey" mandatory="false" description="The website key provided by buckaroo for each website URL. Defaults to the website key in the web.config."/>
    <ef:parameter name="SecretKey" mandatory="false" description="The secret key that is configured in the buckaroo security page. Defaults to the secret in the web.config."/>
    <ef:parameter name="CertificateThumbprint" mandatory="false" description="The thumbprint of the certificate used to ensure mTLS with Buckaroo. Defaults to te thumbprint set in the web.config."/>
    <ef:parameter name="Amount" mandatory="true" description="The amount in minor units, e.g. in cents."/>
    <ef:parameter name="Invoice" mandatory="true" description="The invoice description."/>
    <ef:parameter name="Order" mandatory="true" description="The orderReference used by the code to find its session."/>
    <ef:parameter name="Description" mandatory="true" description="The description of the payment."/>
    <ef:parameter name="ServicesSelectableByClient" mandatory="true" description="The Service to to use for this payment e.g. ideal,mastercard,visa"/>
    <ef:parameter name="Currency" mandatory="false" description="The order currency as ISO 4217 Alpha 3. For example &quot;EUR&quot;. Defaults to &quot;EUR&quot;"/>
    <ef:parameter name="CustomParametersJSON" mandatory="false" description="Valid JSON block, see readme for more information."/>
    <ef:parameter name="PushURL" mandatory="true" description="Overwrite for the pushUrl configured in the buckaroo site. This should point to your nonInteractive scenario."/>
    <ef:parameter name="EnableExpiredCertificates" mandatory="false" description="In prod, always use 0! Should only be 1 in case of prod issues!"/>
  </ef:parameters>
  <ef:results>
    <ef:result name="PaymentStatus" description="The status of the payment."/>
    <ef:result name="TransactionId" description="The transaction ID."/>
    <ef:result name="Error" description="The error text when an error occurs."/>
    <ef:result name="StatusCode" description="The status code."/>
    <ef:result name="StatusCodeDescription" description="The description of the status code."/>
    <ef:result name="TransactionDetails" description="The transaction details object"/>
  </ef:results>
</ef:module>

Web.config

Voer onderstaande zaken uit om de Buckaroo Module in te stellen in de Web.config.

<configuration>
 <kodision.tripleforms...>
  <buckaroo paymentUrl="..." websiteKey="..." secretKey="..." certificateThumbprint="..."/>
 </kodision.tripleforms>
</configuration>

Optioneel:

appSettings>
  <add key="publicOriginBuckaroo" value="…"/>
</appSettings>

Module gebruiken binnen een scenario

Voordat er aan de slag gegaan kan worden met de module, zorg dat de configuratie uitgevoerd is. 

De module is vanuit de Toolbox onder de categorie Modules toe te voegen aan een scenario. Vervolgens is het mogelijk om de eigenschappen van de Buckaroo Module te bewerken.

Properties

Onderstaand pop-up dialoog wordt getoond, indien de properties van de Buckaroo Module bewerkt worden. Het is mogelijk om de pop-up te resizen.

Parameters

Onderstaand zijn de parameters beschreven die benodigd zijn voor de werking van de Buckaroo Module. Daarbij is beschreven of een parameter verplicht is of niet.

Let op: De eerste vier parameters zijn al in de web.config ingesteld. Via de parameters is het mogelijk om deze reeds geconfigureerde parameters te overschrijven.

CustomParametersJSON

Voor meer informatie, zie: https://docs.buckaroo.io/docs/custom-variables

De CustomParametersJSON parameter wordt in de code omgezet naar een ‘additional parameter’ object. In dit object kunnen velden zitten die in de asynchrone afhandeling gebruikt moeten worden (bijvoorbeeld een aanvraagnummer). In deze parameter moet een valide JSON gezet worden.

Houdt hierbij rekening met de volgende zaken:

De JSON moet ge-escaped worden door TriplEforms functies op de juiste plekken. Deze functies zijn:

• [*BO]
• [*BC]

De JSON moet op één line staan. Dit betekend dus dat de JSON niet netjes geformat is, zoals standaard is binnen de Script Editor binnen TriplEforms.

Zie hieronder een voorbeeld van een werkend CustomParametersJSON object. Dit object is voor demonstratie wel geformatteerd, maar in werkelijkheid moet dit op één enkele regel staan. De one-liner is te zien in het tweede voorbeeld:

Formatted

{
  "AdditionalParameters": {
    "AdditionalParameter": [*BO]
      {
        "Name": "Email",
        "Value": "[#fBuckaroo.Email]"
      },
      {
        "Name": "Aanvraagnummerstring",
        "Value": "[#globals.aanvraagnummer]"
      }
    [*BC]
  }
}

{"AdditionalParameters":{"AdditionalParameter":[*BO]{"Name": "Email","Value": "[#fBuckaroo.Email]"},{"Name": "Aanvraagnummerstring", "Value": "[#globals.aanvraagnummer]"}[*BC]}}

<kodision.tripleforms>
  <noninteractive>
    <add scenarioId="scHandleBuckarooWebHook" requestValidatorType="Kodision.TriplEforms.Engine.Modules.BuckarooWebHookValidator, Kodision.TriplEforms.Engine, Version=5.0.0.0, Culture=neutral, PublicKeyToken=3293b934dd649f43"/>
  </noninteractive>
</kodision.tripleforms>

<add key="publicOriginBuckaroo" value="--ENTER-APPLICATION-ROOT-URL-WITH-SCHEMA-HERE---" />