Buckaroo eerste keer inrichten

TriplEforms 5.0

Gemaakt door Mark Duijkers, Gewijzigd op Tue, 23 May 2023 om 02:45 PM op Mark Duijkers

TABLE OF CONTENTS

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:


Wat?Waar te vinden?    BeschrijvingOpmerkingen
Secret Key    Te vinden onder Configuratie -> Beveiliging -> Secret Key    Door een digitale handtekening te gebruiken kunnen afzenders van informatie worden geverifiëerd. Zo kunnen wij verifiëren of een aangevraagde transactie van jou afkomstig is of niet en kun je controleren of de response die je ontvangt daadwerkelijk van Buckaroo afkomstig is. Geef hiervoor een geheime code ("secret key") op. Deze wordt gebruikt om een handtekening ("hash") te berekenen volgens het gewenste algoritme (zie ook pagina 'websites' onder je profiel). Deze handtekening kun je met de transactie meezenden, of je ontvangt deze met de aanroep vanaf de response-pagina of push-berichten.    

Let op: De Secret Key mag alleen cijfers en letters bevatten!



Website Key    
Te vinden onder Mijn Buckaroo -> Websites -> Algemeen -> Key    
Een unieke key per verbonden website.    



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>

Onderstaand zijn de betreffende attributen toegelicht:


AttribuutBeschrijving
paymentUrl

De basis url voor de Buckaroo API die je wilt gebruiken. De test-url is als volgt: ‘https://testcheckout.buckaroo.nl ’

websiteKey

De websiteKey van de website, bijvoorbeeld: ‘BdRkgw34d’

secretKey

De secretKey van het Buckaroo account, bijvoorbeeld: ‘K0D1S10NS3CR3TK3Y’

certificateThumbprint

Optioneel: De thumbprint van het certificaat om TLS1.2 te gebruiken.

publicOriginBuckarooOptioneel: Wanneer een load-balancer wordt gebruikt, is een vaste URL nodig waar de buckaroo op terug kan keren, bijvoorbeeld: ‘https://buckaroo.kodision.nl:8443 ’


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.


ParameterVerplichtOmschrijving
PaymentUrlNee

Hiermee kan de PaymentUrl, zoals die in de Web.config is ingesteld, worden overschreven.

WebsiteKeyNee

Hiermee kan de WebsiteKey, zoals die in de Web.config is ingesteld, worden overschreven.

SecretKeyNee

Hiermee kan de SecretKey, zoals die in de Web.config is ingesteld, worden overschreven.

CertificateThumbprintNee

Hiermee kan de CertificateThumbprint, zoals die in de Web.config is ingesteld, worden overschreven.

AmountJa

Een bedrag groter dan 0 in minor units van de opgegeven Currency. Bij "EUR" (Euro) zijn dit Euro-centen: €1,23 wordt dus 123.

CurrencyNee

De betaaleenheid waarin het bedrag is opgegeven. Dit dient een geldige ISO 4217 Alpha 3 currency te zijn. 


De default is "EUR" (Euro).


InvoiceJaEen verplicht veld waar informatie over een invoice meegestuurd kan worden


OrderJaEen uniek nummer, wat per request moet verschillen. Dit wordt in de code gebruikt om terug te keren in het formulier.


DescriptionJa

Een verplicht veld waar een beschrijving aan de betaling kan worden toegevoegd.



ServicesSelectableByClientJa

Een selectie van betaalmethodes die de klant kan gebruiken als string (komma gescheiden), bijvoorbeeld: ‘ideal, mastercard, visa’

CustomParametersJSONNee

Een object waar handmatig velden meegestuurd kunnen worden. Deze velden zijn dan ook in de asynchrone afhandeling beschikbaar.

PushURLJaHet nonInteractive scenario wat gebruikt zal worden voor de asynchrone afhandeling.


EnableExpiredCertificatesNee

Een binary waarde die op productie altijd op 0 moet staan. Klik hier voor meer informatie over de parameter en wanneer deze gebruikt kan worden.

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]
  }
}

Unformatted (enkele regel)

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

Dit object is te gebruiken wanneer er over het additionalparameters.list object heen geïtereerd wordt.


EnableExpiredCertificates

De code bekijkt of er een certificaat gevonden kan worden op basis van de Thumbprint. Vervolgens zal er gekeken worden of het certificaat nog actief/geldig is. Wanneer EnableExpiredCertificates op ‘1’ wordt gezet, zal de tweede check niet uitgevoerd worden. Dit kan ervoor zorgen dat TLS niet enabled is, en moet daarom alleen door support worden aangezet, ingeval van een verlopen certificaat (om downtime te voorkomen).


Result Parameters

Middels de result parameters is het mogelijk om ontvangen waardes te mappen naar TriplEforms variabelen. Hierdoor is het mogelijk om deze variabelen te gebruiken binnen scenario-flow of binnen een formulier. De waarde van de result parameter moet exact geschreven zijn als de naam van de result parameter.


Onderstaand zijn de Result Parameters omschreven.


Result Parameter    Omschrijving
PaymentStatus

De status van de betaling

TransactionIdHet ID van de betaling
Error

De error tekst wanneer er een foutmelding voorkomt

StatusCodeDe statuscode van de betaling
StatusCodeDescription

De statuscode beschrijving van de betaling

TransactionDetails

Het object waar alle informatie van de betaling in zit.


Betaalscenario

In de TriplEforms bestanden staan formulieren om een betaling te kunnen versturen. Hieronder is een flow diagram uitgewerkt voor een betaalscenario:



Webhooks - Asynchrone afhandeling

Het moment dat er een statusupdate beschikbaar is voor een betaling, zal Buckaroo een bericht sturen naar de geconfigureerde URL. Deze URL zal naar een NonInteractive scenario moeten wijzen. De webhook URL mag geen lokaal of relatief IP-adres zijn.


Hieronder een voorbeeld van een correcte URL:

https://buckaroo.kodision.nl:8443/NonInteractive/scNonInteractiveBuckaroo.aspx 


Webhook processor

De Buckaroo Webhook processor is beschikbaar via de Toolbox > Processors binnen een scenario:



De processor is ook beschikbaar via het menu (rechtermuisknop) binnen een scenario:



Als deze wordt aangeklikt zal onderstaande detailscherm worden geopend.


Met de parameters zijn de waardes die bij de Web.config zijn opgegeven te overschrijven. Dit betreft dus:

  • Payment Url
  • Website Key
  • Secret Key
  • Certificate Thumbprint
  • Enable expired certificates


Configuratie NonInteractive in Web.config

Om een non interactive scenario te gebruiken dient deze te worden ingesteld in de web.config (Classname met Namespace, Dll-naam, Version, Culture en PublicKeyToken):


<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>
Let op: Dit voorbeeld staat ook gedefinieerd in de Web.Example.config of web.example.config.


Bovenstaande configuratie gaat er van uit dat het scenario ‘scHandleBuckarooWebHook’ heet, maar de scenarionaam kan ook aangepast worden.


Scenario & Flow


Onderstaand is uitgelegd hoe de Buckaroo WebHook Processor fungeert binnen een scenario. Daarbij is ook informatie beschreven omtrent de bijbehorende flow.

Scenario

Let op: Onderstaande scenario (scHandleBuckarooWebHook) is een voorbeeldnaam voor het scenario. Dit kan elke willekeurige scenarionaam zijn.

Ten eerste dient er een Buckaroo WebHook Processor geplaatst te worden in een scenario. Dit dient het eerste element te zijn. Zorg ervoor dat de instellingen (parameters) gelijk zijn aan de instellingen op het originele scenario voor de Buckaroo Module. Indien de parameters niet ingevuld zijn, worden de waardes uit de Web.config gebruikt.


Flow

Binnen de namespace van de Buckaroo WebHook Processor (PBuckarooWebhook in onderstaande afbeelding), worden de gegevens geplaatst waar de flow op zou kunnen plaatsvinden. Onderstaand is een scenario uitgewerkt voor het afhandelen van een asynchroon scenario:



TransactionDetails object

Voor meer informatie, zie https://docs.buckaroo.io/docs/nl/transaction-status-get

Het TransactionDetails object is het object wat terugkomt nadat we de status van een betaling opvragen vanuit Buckaroo. Zie de documentatie Buckaroovoor meer informatie over welke gegevens terugkomen vanuit de Buckaroo API.



SSL Offloading

Als de TriplEforms applicatie draait op een omgeving waar een load balancer met SSL offloading actief is moet je de volgende appSetting in je web.config gebruiken om betalingen goed te laten verlopen:

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

Deze setting zorgt ervoor dat de origin url van het request niet op http, maar onder https komt te staan.



Was dit artikel nuttig?

Dat is fantastisch!

Hartelijk dank voor uw beoordeling

Sorry dat we u niet konden helpen

Hartelijk dank voor uw beoordeling

Laat ons weten hoe we dit artikel kunnen verbeteren!

Selecteer tenminste een van de redenen
CAPTCHA-verificatie is vereist.

Feedback verzonden

We stellen uw moeite op prijs en zullen proberen het artikel te verbeteren