Wij gebruiken cookies om er voor te zorgen dat wij u de beste gebruikerservaring kunnen bieden op deze website. Als u verdergaat zonder uw instellingen te wijzigingen, gaan wij ervan uit dat u akkoord gaat met het ontvangen van alle cookies op de Buckaroo website. Als u dat wenst, kan u uw cookie instellingen op elk moment wijzigen. Meer informatie
Dit bericht niet meer tonen
Beste Payment Service Provider van 2014, 2015 én 2016

HTML Basis koppeling

Hieronder een samenvatting van de aandachtsgebieden voor het opzetten van een HTML koppeling met Buckaroo.

Basis

Om een minimale koppeling met de SSL gateway te maken zijn de volgende velden verplicht:

Naam Omschrijving
Brq_websitekey De unieke key van de website waarvoor de betaling verricht wordt.
Brq_amount Het te betalen bedrag, formaat: 12.34 (gebruik altijd een punt als decimaalscheidingsteken)
Brq_currency De valutacode (bijv. EUR, USD, GBP). Let op dat de opgegeven valuta
ondersteund wordt door de opgegeven betaalmethode.
Brq_invoicenumber Het unieke factuurnummer dat vermeld wordt bij de betaling.
Dit is een vrij tekstveld van maximaal 255 tekens.
Brq_signature De digitale handtekening. Voor de berekening hiervan zie Digitale handtekening SSL/HTML.

Deze en andere velden moeten via een POST form naar de gateway gestuurd worden, GET verzoeken worden niet ondersteund. Wanneer alleen deze velden naar de gateway gestuurd worden, krijgt de betaler een Buckaroo scherm met alle afgenomen betaalmethodes te zien. Het is ook mogelijk om de keuze voor betaalmethode in de webshop te maken i.p.v. op het Buckaroo scherm. Extra informatie over deze mogelijkheid is terug te vinden op de pagina Pro koppeling SSL/HTML. Na afronding kan de klant alleen teruggestuurd worden naar de webshop indien de redirect URLs ingevuld zijn in de Buckaroo Payment Plaza. De instellingen zijn per website key te configureren. Het is belangrijk hiervoor een HTTPS pagina voor te gebruiken om beveiligingswaarschuwingen te voorkomen.
Return URLs per Websitekey.JPG

Voorbeeld

Hieronder staat een voorbeeld van een basis koppeling zonder additionele velden. Op deze manier wordt de klant doorgezet naar de gateway van Buckaroo en kan voor alle betaalmethodes kiezen die de merchant bij Buckaroo afneemt. De redirect URL's moeten ingesteld worden in de Buckaroo Payment Plaza. Indien dit niet is gebeurd, wordt de consument niet teruggestuurd naar de webshop. Bij de berekening van de signature is als secret key "Secretkey" gebruikt.
Voorbeeld:
brq_websitekey = aBcDe123
brq_amount = 12.34
brq_currency = EUR
brq_invoicenumber = inv0001
brq_signature = 365a9d761e647317688e91475ea6bb55e9c19ae4

Beveilingswaarschuwing HTTPS

Uitleg

Checkout.JPG

De Buckaroo betaalomgeving is in zijn geheel voorzien van SSL certificaten. Dit is zichtbaar aan het "hangslot" dat wordt getoond op de webpagina's en aan de URL die begint met HTTPS in plaats van HTTP. Buckaroo adviseert om zowel de checkout in de webshop als ook de terugkeer pagina op te nemen in een HTTPS beveiligde omgeving.Met deze werkwijze zijn de gegevens onleesbaar wanneer ze op het internet worden onderschept.

Waarschuwing

Wanneer de consument na betaling terugkeert naar de webshop van de Merchant kan een waarschuwing worden weergegeven. De consument wordt dan gewaarschuwd voor een overgang van de beveiligde Buckaroo omgeving naar de onbeveiligde bedankt-pagina van webshop.

HTTPS afhandeling.jpg

Maatregel

Om te voorkomen dat de foutmelding wordt weergegeven is het van belang om de bedanktpagina te beveiligen met een SSL certificaat. De bedankt-pagina moet dan dus van http://return.merchantnaam.nl worden gewijzigd naar https://return.merchantnaam.nl.
Om te controleren of de return URL werkt, kan deze uit het aanbiedingsbericht aan Buckaroo worden gehaald en in een browser worden geplaatst. Wanneer de URL niet werkt, dient van deze pagina te worden gecontroleerd of deze wel HTTPS is.
Hieronder is het voorbeeld getoond van een foutmelding op een URL. Om een idee te krijgen van hoe een computer reageert op een onveilige langdingspagina, druk op de volgende link:
https://www.xxxxxxx.nl/checkout/payment_success.
De kras door HTTPS op de pagina die wordt getoond geeft aan dat deze pagina niet beveiligd is.

Vooral bij de Safari browser op het iPAD en iPHONE platform kan een onbeveiligde bedankt-pagina problemen opleveren. Niet in alle gevallen wordt de optie getoond om door te kunnen gaan. Dit leidt tot onafgemaakte betalingen en dus conversie verlies.

Voorbeeld van een waarschuwingen:
Onveilig melding.JPG Beveiliging waarschuwing redirect.jpg

Payment response

Zodra de klant de betaling heeft afgerond, wordt hij via Buckaroo teruggestuurd naar de webshop. Buckaroo geeft extra informatie mee, waardoor de webshop de laatst bekende informatie ontvangt. Deze gegevens worden via POST verzonden.

Element Omschrijving optioneel
brq_payment De key van de Payment. Deze waarde wordt alleen terug gestuurd als de transactie tot een daadwerkelijke betaling heeft geleid. Ja
brq_payment_method De servicecode van de methode waarmee de betaling is uitgevoerd.
brq_statuscode De statuscode van de transactie Nee
brq_statuscode_detail Een detail status code welke een extra uitleg geeft over de huidige status code. Ja
brq_statusmessage Een bericht over de status code Ja
brq_invoicenumber Het invoicenummer dat in het verzoek is opgegeven Nee
brq_amount_credit Het creditbedrag dat in het verzoek is opgegeven, als het is opgegeven. Ja
brq_amount Het bedrag dat in het verzoek is opgegeven, als het is opgegeven. Ja
brq_currency De valuta van de transactie (bijv. EUR, USD, GBP). Nee
brq_timestamp De tijd waarop de betaling zijn huidige status heeft ontvangen. Nee
brq_service_[servicecode]_[parametername] Output parameters voor de gevraagde services. Zie hiervoor de service handleiding voor een lijst van parameters. Ja
cust_[parametername] De voorgedefiniëerde custom variabelen welke zijn meegestuurd met het originele verzoek. Ja
add_[parametername] De additionele variabelen welke zijn meegestuurd met het originele verzoek. ja
brq_transactions Een of meer transactie keys. Een key als er een onderliggende transactie is aangemaakt voor de betaling. Meerdere als er meerdere onderliggende transacties zijn die gelinkt zijn aan de betaling. Nee
brq_transaction_method De service waarmee de transactie is uitgevoerd (alleen wanneer een transactie is verwerkt). Nee
brq_transaction_type De transactie type code van de transactie (alleen wanneer een transactie is verwerkt). Nee
brq_mutationtype Het mutatie type van de transactie, dit kan 'collecting','processing','informational' of 'notset' zijn. Ja
brq_signature De digitale handtekening. Voor de berekening hiervan zie Digitale handtekening SSL/HTML. Nee

Het is niet altijd mogelijk tijdens het betaalproces al de definitieve status code van een transactie door te geven. Ook is het mogelijk dat een betaalproces door een consument onderbroken wordt, waardoor de status ook niet in de normale flow van het betaalproces teruggegeven wordt aan de webshop. Om in deze gevallen toch de status van de transactie te ontvangen, kan er gebruik gemaakt worden van de push. Deze stuurt de status zodra die bekend is bij ons, automatisch door naar de webshop.

Mocht de push mislukken, dan wordt het versturen automatisch nog enkele keren geprobeerd, steeds met een grotere wachttijd tussen elke poging. Na ongeveer 2 dagen, zal het de push niet meer opnieuw geprobeerd worden.

Let op: Het is mogelijk dat een push vaker dan 1 keer uitgevoerd wordt. Houd hier dus rekening mee in het afhandelen van het push-bericht en maak niet automatisch op elke geslaagde push een nieuwe order aan.

Push instellingen in de Plaza

De push kan per website (oftewel merchantkey) ingesteld worden in de Buckaroo Payment Plaza. Ga naar Profiel > Websites > Push instellingen. In deze lijst kunt u kiezen voor welke website(s) de push ingesteld moet worden.

PushInstellingen.PNG

Standaard Push Instellingen

De standaard instellingen van Vertraagde en push response zijn als volgt:

PushInstellingen2.PNG

Verder dienen er URL's ingevuld te worden bij Push URI Success en Push URI Failure. Dit zijn de URL's waar de push berichten heen worden gestuurd.

Opmerking: Buckaroo adviseert om een e-mail adres in te vullen bij E-Mail push mislukt. Deze staat onderaan het scherm van de Push Instellingen. Naar dit e-mail adres wordt een mail gestuurd bij eventuele problemen bij het uitvoeren van de push.

Detailbeschrijving van alle instellingen

Instelling Functie
Activeer Vertraagde Response. Dit activeert het sturen van een PUSH buiten het betaalproces. De klant is dan al niet meer bezig met het doen van de betaling in de Buckaroo schermen.
Activeer Push Response. Dit activeert het sturen van PUSH berichten tijdens het betaalproces (alleen in de SSL gateways). De Buckaroo Payment Engine stuurt een bericht net voordat de klant terugkeert naar de webshop.
Deactiveer auto-redirect via browser Als dit aangezet wordt, wordt de klant niet meer automatisch teruggestuurd naar de webshop. De klant dient eerst op de "Terug naar webshop" knop te drukken. Deze optie kan alleen geactiveerd worden als de optie "Activeer Push Response." is geactiveerd.
Activeer Push van Refunds. Dit activeert het sturen van PUSH berichten voor refunds. Refunds kunnen om verschillende redenen nog wel eens mislukken. Door deze optie aan te zetten, krijgt u terugkoppeling over voltooide refunds.
URI succes Naar deze URL worden de PUSH berichten gestuurd als de transactie geslaagd is.
URI failure Naar deze URL worden alle overige PUSH berichten gestuurd. Dit geldt voor een transactie die een pending status heeft of mislukt is.
Gebruik HTTP-Method Dit bepaalt welke HTTP-Method gebruikt wordt om de PUSH uit te voeren. Er is de keuze uit:
  • GET: Gebruik HTTP-GET om de PUSH uit te voeren. Alle gegevens worden aan de URL toegevoegd.
  • POST: Gebruik HTTP-POST om de PUSH uit te voeren. De gegevens worden in de POST data meegestuurd naar de URL.
Mailadres alerts Wanneer de PUSH om wat voor reden dan ook niet uitgevoerd kan worden, krijgt dit emailadres een bericht met de status van de transactie. Zodoende bent u altijd op de hoogte van status veranderingen, ook bij een tijdelijke storing. Om het bericht naar meerdere email adressen te sturen, geeft u meerdere adressen op, gescheiden met een punt-komma:;


Push response

Naast de reguliere response kan een betaling ook via asynchrone push response worden teruggemeld. Deze methode is handig wanneer het betalingsproces wordt onderbroken. Bijvoorbeeld: de consument sluit de browser alvorens hij terugkeert naar de webshop.
De methode meldt ook de status van betalingen die niet direct zijn voltooid, zoals overschrijvingen en machtigingen.

Let op: Daar waar de payment response informeert over de betaling en de transactiestatus, informeert de push response alleen over de transactiestatus.

Parameters bij een httppost

Element Omschrijving optioneel
brq_payment De key van de Payment. Deze waarde wordt alleen terug gestuurd als de transactie tot een daadwerkelijke betaling heeft geleid. Ja
brq_payment_method De servicecode van de methode waarmee de betaling is uitgevoerd.
brq_statuscode De statuscode van de transactie Nee
brq_statuscode_detail Een detail status code welke een extra uitleg geeft over de huidige status code. Ja
brq_statusmessage Een bericht over de status code Ja
brq_invoicenumber Het invoicenummer dat in het verzoek is opgegeven Nee
brq_amount_credit Het creditbedrag dat in het verzoek is opgegeven, als het is opgegeven. Ja
brq_amount Het bedrag dat in het verzoek is opgegeven, als het is opgegeven. Ja
brq_currency De valuta van de transactie (bijv. EUR, USD, GBP). Nee
brq_timestamp De tijd waarop de betaling zijn huidige status heeft ontvangen. Nee
brq_service_[servicecode]_[parametername] Output parameters voor de gevraagde services. Zie hiervoor de service handleiding voor een lijst van parameters. Ja
cust_[parametername] De voorgedefiniëerde custom variabelen welke zijn meegestuurd met het originele verzoek. Ja
add_[parametername] De additionele variabelen welke zijn meegestuurd met het originele verzoek. ja
brq_transactions Een of meer transactie keys. Een key als er een onderliggende transactie is aangemaakt voor de betaling. Meerdere als er meerdere onderliggende transacties zijn die gelinkt zijn aan de betaling. Nee
brq_transaction_method De service waarmee de transactie is uitgevoerd (alleen wanneer een transactie is verwerkt). Nee
brq_transaction_type De transactie type code van de transactie (alleen wanneer een transactie is verwerkt). Nee
brq_mutationtype Het mutatie type van de transactie, dit kan 'collecting','processing','informational' of 'notset' zijn. Ja
brq_signature De digitale handtekening. Voor de berekening hiervan zie Digitale handtekening SSL/HTML. Nee

Belangrijk: De samenstelling van een payment response is afhankelijk van de betalingswijze en de status van de betaling. Bijvoorbeeld: de gegevens van de rekeninghouder worden alleen geretourneerd wanneer de betaling is voldaan. Daarom is het aanbevolen om een flexibele aanpak van het werken met de betaling reacties te gebruiken. Ga niet van een vaste set van terugkeer parameters uit.

Opbouw JSON push

{

  "Transaction":{  
     "Key":"416BxxxxxxxxxxxxxxxxxxD8D0B41207",
     "Invoice":"invoice1234",
     "ServiceCode":"ideal",
     "Status":{  
        "Code":{  
           "Code":190,
           "Description":"Succes"
        },
        "SubCode":{  
           "Code":"S060",
           "Description":"De consument is teruggekeerd, transactiebevestiging succesvol."
        },
        "DateTime":"2017-07-26T13:16:29+02:00"
     },
     "IsTest":false,
     "Order":null,
     "Currency":"EUR",
     "AmountDebit":0.01,
     "TransactionType":"C021",
     "Services":[  
        {  
           "Name":"ideal",
           "Action":null,
           "Parameters":[  
              {  
                 "Name":"consumerIssuer",
                 "Value":"Rabobank"
              },
              {  
                 "Name":"transactionId",
                 "Value":"115xxxxxxxxxx366"
              },
              {  
                 "Name":"consumerName",
                 "Value":"V.N. Achternaam"
              },
              {  
                 "Name":"consumerIBAN",
                 "Value":"NL05RABO0xxxxxxxx0"
              },
              {  
                 "Name":"consumerBIC",
                 "Value":"RABONL2U"
              }
           ],
           "VersionAsProperty":2
        }
     ],
     "AdditionalParameters":null,
     "MutationType":1,
     "RelatedTransactions":null,
     "IsCancelable":false,
     "IssuingCountry":null,
     "StartRecurrent":false,
     "Recurring":false,
     "CustomerName":"V.N. Achternaam",
     "PayerHash":"bbab3fe36xxxxxxa5cbbdc6e10de7d4d4204f3f44309c3da9c2a83e98",
     "PaymentKey":"7820A86xxxxxxxxxxxxxxxxx9FF56339B7D"
  }

}

Handmatige Push

Wanneer de PUSH is ingesteld, is het ook mogelijk de PUSH handmatig vanuit de Buckaroo Payment Plaza uit te voeren.

TransactieDetails-Push.png

Individuele Push Status

Zoek de transactie waarvan de status nogmaals moet worden gepushed op in het transactie scherm en klik erop. De transactie details verschijnen. Door op de grijze knop Acties te drukken, kan de status (nogmaals) naar de webshop gestuurd worden door te kiezen voor Push-status. Wanneer de betreffende transactie als test transactie is ingediend, kan bij het afronden van de transactie een status gekozen worden. Op deze manier kan de afhandeling van verschillende statussen getest worden in de webshop. Daarnaast hebben sommige betaalmethoden test scenario's, zoals Overboeking, SEPA Direct Debit en iDEAL. Op deze manier kunnen ook verschillende scenario's en push berichten getest worden.

Bulk Push Status

Bulk Push Status.PNG
Het is ook mogelijk om een Bulk Push status update te versturen. Dat is met name van toepassing wanneer de Push ontvanger, of de verbinding daar naartoe, een tijd lang niet beschikbaar was voor ontvangst van de updates. Kies, voor het uitvoeren van de Bulk functionaliteit, het transactieoverzicht en vul het filter zo dat daarmee de transacties worden geselecteerd die voor de statusupdate push in aanmerking komen. Kies dan voor Acties en vervolgens Bulk Push Status.
Wanneer er een waarschuwing verschijnt kan een grote en daarmee tijd consumerende selectie, af worden gebroken. Het scherm dat zich opent laat alle transacties zien die er voor de bulk push status in aanmerking komen. Individuele transactie kunnen uit de selectie worden verwijderd door het groene vinkje weg te laten. In het invulscherm aan de rechterzijde kunnen aanvullende transacties worden toegevoegd. De selectiecriteria staan maximaal 1000 transacties toe om de push naar toe te versturen. Dit om overbelasting van alle betrokken servers in de keten te voorkomen.

Aandachtspunten

Mislukte PUSH

De PUSH service roept de ingestelde PUSH url aan. Dit zal een script zijn op uw webshop. Dit kan ook een normale pagina zijn die in de browser te openen is. De PUSH wordt beschouwd als gelukt wanneer er een HTTP 200 wordt ontvangen. Wanneer het aanroepen van de URL in een foutcode resulteert, dan interpreteert de PUSH service dit als dat de PUSH mislukt is. Er wordt een waarschuwings email gestuurd naar een in te stellen adres. Het PUSH bericht wordt later nogmaals verstuurd. Als na een aantal pogingen het bericht nog steeds niet met succes verstuurd is, kan er een afsluitende email gestuurd worden en worden er geen verdere pogingen gedaan om de PUSH te sturen. Wanneer dit plaatsvindt, is het altijd nog mogelijk de PUSH handmatig te doen, zie hiervoor de handmatige push. Een lijst van HTTP status codes kan op Wikipedia worden gevonden.

Herhalingen van de Push berichten

Indien de Push berichten niet succesvol worden bevestigd, zullen er nieuwe pogingen worden ondernomen. Dit kan voorkomen wanneer een Push-notificatie niet wordt geaccepteerd of wanneer de zogenaamde listener niet actief is. De frequent waarmee de Push-notificatie opnieuw wordt aangeboden is: 5 min + 10 min + 15 min + 30 min + 1 uur + 2 uur + 4 uur + 8 uur + 8 uur + 24 uur + 24 uur. Dus in totaal 11 pogingen. Voor het waarschuwingsbericht bij de eerste mislukking van de Push en voor het sluitbericht bij de laatste Push kan er een e-mail worden ingesteld in de Plaza.

Dubbele PUSH

Om verschillende redenen is het mogelijk dat een PUSH dubbel of vaker uitgevoerd wordt. Dit kan veroorzaakt worden door een consument die heen en weer klikt in de betaalschermen. Het kan ook gebeuren dat bij het uitvoeren van de PUSH de PUSH server geen correct antwoord krijgt van de webshop en daarom op een later moment nogmaals de PUSH zal proberen. Let er daarom op dat uw systeem vaker dan 1x een PUSH bericht kan ontvangen. De timestamp van de PUSH zorgt ervoor dat onderscheid kan worden gemaakt tussen de verschillende berichten over dezelfde transactie en deze daarmee zijn deze in een vloeiende tijdslijn te plaatsen.

PUSH volgorde

Doordat een mislukte PUSH met een vertraging opnieuw aangeboden wordt, is het mogelijk dat verschillende PUSH berichten elkaar kruisen. Zo kan voorkomen dat een PUSH met een tijdelijke pending status van een transactie verstuurd wordt, nadat de definitieve geslaagde of mislukte status verstuurd is.
Om hier tegen te beschermen moet de meegestuurde timestamp gecontroleerd worden. De status uit een PUSH bericht met een eerdere timestamp mag niet de status overschrijven die gezet is door een PUSH bericht met een latere timestamp.

Vragen?

Mocht u nog vragen hebben:

Zie onze FAQ voor veelgestelde vragen.

Trefwoorden: herhaal ; frequentie ; push ; repush ; bulk ;

Om te zorgen dat we de afzender van de transactie kunnen verifiëren en zeker te zijn dat het bericht onderweg niet aangepast is, maakt Buckaroo gebruik van een digitale handtekening bij elke transactie.

Deze handtekening bestaat uit een hash van alle velden uit het bericht, aangevuld met een secret key.
De secret key is instelbaar op de Payment Plaza onder Profiel > Beveiliging.

De berekening

De berekening van de handtekening werkt als volgt:

  1. Maak een lijst met alle velden in het payment request beginnend met brq_, add_ of cust_, behalve brq_signature, in het volgende formaat:
    brq_veldnaam=Waarde
  2. Sorteer deze velden op alfabetische volgorde op basis van de veldnaam (brq_amount komt vóór brq_websitekey).
    Let op: sortering moet niet-hoofdlettergevoelig gebeuren (brq_active komt vóór BRQ_AMOUNT). Hoofdletters in de veldnamen moeten wel behouden blijven.
    Bijvoorbeeld: BRQ_AMOUNT=1.00brq_currency=EURbrq_websitekey=asdfasdfsecret
  3. Voeg al deze waardes samen, geformateerd zoals genoemd in punt 1, in een string. Gebruik geen scheidingstekens of witruimtes.
    Bijvoorbeeld: BRQ_AMOUNT=1.00brq_currency=EURbrq_websitekey=asdfasdfsecretkey
  4. Voeg hier de pre-shared secret-key toe aan het eind van deze string.
  5. Bereken van deze string een hash met het SHA-1 algoritme. Voer de hash uit in hexadecimaal formaat.

Let op Bij de return en de push moeten de gegevens volledig ge-decode zijn, voordat de signature kan worden berekend.

Het gebruik van het SHA1-encryptiealgoritme verschilt per ontwikkelplatform. De meeste talen (zoals PHP en ASP.NET) hebben standaardimplementaties van het SHA1-algoritme. Voor andere talen als classic ASP kunt u op internet implementaties van het SHA1-algoritme vinden.

SHA-1 voorbeelden

PHP

<source lang="php">$signature3 = sha1($requestFields);</source>

C#/.NET

<source lang="csharp">

using System.Text; using System.Security.Cryptography;

string message = "string that needs to be hashed";

SHA1CryptoServiceProvider sha1Provider = new SHA1CryptoServiceProvider();

//convert input to byte array byte[] messageArray = Encoding.UTF8.GetBytes(message);

//calculate hash over byte array byte[] hash1 = sha1Provider.ComputeHash(messageArray);

//convert byte array to string by printing each hex value. foreach (byte b in hash1) {

   builder.Append(b.ToString("x2"));

} //get the result from the string builder object. String Result = builder.ToString(); <source></source>

Gateway URLs

De URLs voor de HTML gateway zijn:
Live: https://checkout.buckaroo.nl/html/
Test: https://testcheckout.buckaroo.nl/html/

Testen

Voor het testen van betalingsverzoeken heeft Buckaroo een aparte testomgeving beschikbaar.
Zie de paragraaf Gateway URLs voor het adres hiervan. Betalingsverzoeken naar de testomgeving leiden niet tot een geldstroom maar bieden de mogelijkheid om de communicatie te testen.

In de oude versie van de internetkassa was het mogelijk een payment request in testmodus aan te bieden. Op deze manier werd de betaling niet daadwerkelijk verwerkt maar kon wel de communicatie getest worden. Deze testmodus is in de nieuwe Payment Engine niet meer beschikbaar.
NB: alle payment requests naar de live-omgeving worden als live behandeld!