1. Inleiding Wij heten u van harte welkom als gebruiker van de Buckaroo Payment Engine. Deze handleiding beschrijft hoe u op eenvoudige wijze vanaf uw website een koppeling kunt maken met de Buckaroo Payment Engine voor betalingen via iDEAL. Met iDEAL kunnen uw klanten direct vanaf uw webwinkel betalen in de voor hun vertrouwde internetbankier omgeving van hun bank. iDEAL wordt momenteel ondersteund door enkele grote Nederlandse banken. Op onze website (www.buckaroo.nl) kunt u zien welke banken dat momenteel zijn. Het implementeren van een directe koppeling met iDEAL vereist een aanzienlijke kennis inzake XML, PKI en andere webtechnologie. Wij hebben daarom voor u een eenvoudige interface ontwikkeld op onze internetkassa, zodat het iDEAL-betaalmechanisme op eenvoudige wijze binnen uw webwinkel kunt implementeren. De iDEAL-interface met de internetkassa van Buckaroo werkt op eenzelfde wijze als de Payment Engine voor creditcards. Mochten er in deze implementatiehandleiding punten staan die voor u onduidelijk zijn, dan wel in uw ogen niet kloppen, dan verzoeken wij u ons dit te melden op [email protected].
2. Algemeen 2.1 Payment-processing met iDEAL Het verwerken van betalingen met iDEAL is een complex proces. Er zijn meerdere stappen nodig om de betaling vanaf uw website uit te voeren. De iDEAL-gateway van de Buckaroo Payment Engine vereenvoudigt dit proces voor een merchant substantieel. De iDEAL-gateway verzorgt de communicatie voor u naar de bank en leidt de betaler terug naar uw webwinkel nadat de transactie is verwerkt. Afhankelijk van het resultaat van de transactie, kan dit een succespagina (bij succesvolle betaling) zijn of een andere pagina (afwijzing of weigering). In Figuur 1: implementatie iDEAL Gateway is schematisch weergegeven hoe de implementatie van deze gateway tot stand komt. Figuur 1: Implementatie iDEAL Gateway
3. Beveiliging Voor er in gegaan word op de technische aspecten van de koppeling, volgt hier eerst een kleine uiteenzetting van enkele aspecten inzake de beveiliging van uw transacties. 3.1 SSL Het netwerkverkeer verloopt volledig via SSL-verbindingen. Dit betekent dat alle verkeer versleuteld wordt verzonden. De SSL-beveiliging wordt weergegeven door het bekende slotje dat wordt weergegeven in de statusbalk van uw webbrowser. Deze beveiliging wordt vanuit de webservers van Buckaroo geregeld. U hoeft hiervoor geen actie te ondernemen. 3.2 Merchant-key In het kader van uw aansluiting heeft u van ons één of meer merchant-keys ontvangen. Per koppeling (of website) ontvangt u een nieuwe key. Deze key is essentieel bij het aanbieden van een transactie omdat deze de unieke verbinding legt tussen de betreffende transactie en uw account als merchant. Indien u dus over meerdere merchant-keys beschikt, worden de transacties dus per koppeling apart geregistreerd. U kunt uw MasterCard/ Visa aansluitnummers op deze manier dus voor meerdere websites gebruiken. 3.3 Digitale handtekening De digitale handtekening wordt gebruikt om de authenticiteit van transacties te verifiëren. Hiermee wordt voorkomen dat derden in uw naam transacties kunnen versturen. De digitale handtekening is een unieke code die wordt berekend op basis van enkele transactiegegevens en een “shared secret key”. U, als merchant, en de BPE zijn de enigen die deze “secret key” kennen. Alleen u en de BPE kunnen dus de juistheid van de digitale handtekening vaststellen. De “shared secret key” kunt u zelf instellen op de Buckaroo Payment Plaza, onder het kopje ‘configuratie’. Bij de berekening van de digitale handtekening dient gebruik te worden gemaakt van het MD5 encryptie algoritme. Voer dit algoritme uit op enkele specifieke transactiegegevens in combinatie met de shared secret key, en u krijgt de digitale handtekening als output. Het toepassen van de digitale handtekening werkt als volgt: De afzender van het bericht berekent de digitale handtekening en geeft deze in het bericht mee in het daarvoor bestemde veld. De ontvanger berekent eveneens de digitale handtekening en vergelijkt deze met de meegezonden waarde. Indien de berekening en de meegezonden waarde gelijk zijn, kan het bericht worden geaccepteerd.
Er zijn momenteel 2 berichten waarop de digitale handtekening wordt toegepast: 1. Bij het aanbieden van transacties (‘Request’). De digitale handtekening (DH) wordt als volgt berekend: DH = MD5(MerchantKey + InvoiceNumber + Amount + Currency + Modus + SecretKey)
MerchantKey = de merchant-key die u heeft ontvangen voor de koppeling (veld bpe_merchant) InvoiceNumber = een factuurnummer dat u met de transactie kunt meegeven (veld bpe_invoice) Amount = Het bedrag in centen (veld bpe_amount) Currency = De gebruikte valuta, momenteel alleen EUR (veld bpe_currency) Modus = Is het een Testbetaling (1) of een echte transactie (0) (veld bpe_mode) SecretKey = De geheime code die u t.b.v. de versleuteling heeft opgegeven 2. Bij het ontvangen van het verwerkingsresultaat van transacties (‘Response’). De digitale handtekening (DH) wordt als volgt berekend: DH = MD5(TransactionKey + Timestamp + MerchantKey + InvoiceNumber + Reference + Currency + Amount + Result + Modus + SecretKey)
TransactionKey = De unieke code die door de BPE aan de transactie is toegekend Timestamp = Datum en tijd van de transactie (veld bpe_timestamp) MerchantKey = de merchant-key die u heeft ontvangen voor de koppeling InvoiceNumber = Een factuurnummer dat u met de transactie kunt meegeven (veld bpe_invoice) Reference = De referentiecode die u met de transactie meegeeft (veld bpe_reference) Currency = De gebruikte valuta (momenteel alleen EUR) (veld bpe_currency) Amount = Het bedrag in centen (veld bpe_amount) Result = De statuscode van de transactie (veld bpe_result)
Modus = Is het een Testbetaling (1) of een echte transactie (0) (veld bpe_mode) SecretKey = De geheime code die u t.b.v. de versleuteling heeft opgegeven NB: Toepassing van de digitale handtekening is verplicht. De digitale handtekening wordt zowel op het aanleveren van berichten (transacties / batches) door merchants aan de BPE toegepast, als op responses van de BPE aan de systemen van de merchant. Met name in het laatstgenoemde geval voorkomt het dat hackers valse betalingsbevestigingen naar uw website kunnen sturen, en daarmee wellicht op uw website een orderbevestiging genereren zonder dat de betaling heeft plaatsgevonden. Het gebruik van het MD5-encryptiealgoritme verschilt per ontwikkelplatform. De meeste talen (zoals PHP en ASP.NET) hebben standaardimplementaties van het MD5-algoritme. Voor andere talen als classic ASP kunt u op internet implementaties van het MD5algoritme vinden.
Hieronder vindt u een voorbeelden van het gebruik van MD5 in de meest gangbare platformen c.q. talen.
Taal PHP VB.NET
Voorbeeldcode digitalSignature = Md5(inputString); Dim strData As String = "Hier uw merchant- en transactiegegevens" Dim objMD5 As New System.Security.Cryptography.MD5CryptoServiceProvider Dim arrInput() As Byte Dim arrHash() As Byte 'Converteer de input naar bytes arrInput = System.Text.Encoding.UTF8.GetBytes(strData) 'Bereken een hash over de input arrHash = objMD5.ComputeHash(arrInput) 'Geheugen vrijmaken objMD5 = Nothing
'Bouw een string op van de hash output Dim objStringBuilder As New System.Text.StringBuilder(arrHash.Length) For i As Integer = 0 To arrHash.Length - 1 objStringBuilder.Append(arrHash(i).ToString("x2") Next
'Lees de digitale handtekening uit als string Dim digitalSignature As String = objStringBuilder.Tostring()
C#
string strData = "Hier uw merchant- en transactiegegevens"; System.Security.Cryptography.MD5CryptoServiceProvider objMD5 = new System.Security.Cryptography.MD5CryptoServiceProvider(); byte[] arrInput; byte[] arrHash; //Converteer de input naar bytes arrInput = System.Text.Encoding.UTF8.GetBytes(strData); //Bereken een hash over de data arrHash = objMD.ComputeHash(arrInput); //Geheugen vrijmaken objMD5 = null; //Bouw een string op van de hash output System.Text.StringBuilder objStringBuilder = new System.Text.StringBuilder(arrHash.Length); for(int i=0; i<arrHash.Length; i++) { objStringBuilder.Append(arrHash[i].ToString("x2"); } //Lees de digitale handtekening uit als string string digitalSignature = objStringBuilder.ToString();
3.4 Blokkeren transacties o.b.v. IP-adres Andere beveiligingsmaatregelen betreffen het blokkeren/ weren van ongewenste transacties. Hiervoor beschikt de BPE over verschillende mogelijkheden. Zo is er ondermeer een zwartboek voor IP-adressen. Bij transacties middels de SSLpagina’s wordt automatisch het IP-adres van de pc van de klant achterhaald. Bij transacties middels de XML-interface kunt u het IP-adres van de klant zelf meegeven (onze servers achterhalen het adres van uw server). Er is een globale lijst van IP-adressen die geldt voor het gehele BPE-systeem. Deze lijst bevat bekende IP-adressen van enkele notoire fraudeurs. Deze lijst wordt door Buckaroo onderhouden. Ook kunt u zelf een eigen zwartboek onderhouden. U kunt per merchant-key een lijst onderhouden, of IP-adressen blokkeren voor uw gehele account (dus voor al uw merchant-keys). U kunt IP-adressen toevoegen via de “Configuratie”-pagina op de Buckaroo Payment Plaza. Kies Blokkeringen van het Type “IP-adres”. Let hierbij goed op de correcte notatie van het IP-adres: a.b.c.d waarbij a,b,c en d getallen zijn tussen 0 en 255. Als u slechts een gedeelte van een IP-adres invult, dan wordt de gehele range die met deze waarde begint geblokkeerd. Ook kunt u IP-adressen toevoegen middels de optie “Blokkeer IP” op de detailpagina met de transactiegegevens van een specifieke transactie. Het IP-nummer van de klant die deze transactie heeft gedaan wordt dan voor al uw koppelingen geblokkeerd. Buckaroo voert regelmatig analyses uit op het gedrag van betalers. Indien hieruit onregelmatigheden naar voren komen, zullen we in overleg met u voorstellen om IPadressen te blokkeren. 3.5 Invoice-check Met elke transactie kunt u het nummer meegeven van de factuur waarvan de betaling moet plaatsvinden. Een controlemechanisme zorgt er dan voor dat elke factuur slechts eenmaal kan worden betaald. Daarmee kan enerzijds worden voorkomen dat klanten dubbele betalingen doen (dit kwam in sommige situaties wel eens voor) en daarmee onnodige refunds, anderzijds kunt u ongewenste betaalpogingen weren. Dit laatste kan worden bewerkstelligd door in de configuratie aan te geven dat voor uw transacties het gebruik van een factuurnummer verplicht is. In dat geval moet het Invoice-veld (zie beschrijving velden SSL-pagina’s in latere paragrafen) een waarde bevatten, anders wordt de transactie geweigerd. Als het Invoice-veld gevuld is, wordt gecontroleerd of er reeds een succesvolle transactie voor dit factuurnummer heeft plaatsgevonden. Is dit het geval, dan wordt de transactie afgewezen, en de klant geïnformeerd. Ook kunt u het maximale aantal betaalpogingen per factuur instellen. Ook deze instelling is alleen actief wanneer het Invoice-veld een waarde bevat. De instellingen voor de Invoice-check kunt u configureren via de “Configuratie”-pagina op de Buckaroo Payment Plaza. Kies Blokkeringen van het Type “Factuur”.
4. Aansluiting 4.1 Koppeling met de iDEAL-gateway. De eenvoudigste manier om uw website met de betaalmogelijkheden van de Buckaroo Payment Engine (BPE) uit te breiden, is door een koppeling te maken met de betaalpagina’s op de BPE-server. Implementeer op uw eigen website, op de pagina waarop uw klant moet gaan betalen, een link naar de SSL-pagina’s van de BPE. Maak daarbij gebruik van de HTTP POSTmethode (in HTML form-submit) om de benodigde gegevens voor de betaling aan de BPE over te dragen. Het gebruik van de GET-methode (middels querystring) is voor de iDEAL-gateway niet mogelijk. Gebruik de volgende URL voor de SSL-interface: -
N.B.: bij iDEAL betalingen zijn alleen alfanumerieke karakters (A t/m Z en 0 t/m 9) toegestaan, en leestekens. Speciale tekens zoals äáàëéèöóò zijn niet toegestaan. Let erop dat u deze tekens niet gebruikt, zowel bij het berekenen van de digitale handtekening als het doorsturen van variabelen naar de BPE. N.B.: het is niet verplicht om op uw eigen webomgeving een SSL-certificaat te hebben. Wij raden dit echter wel aan. Als u geen eigen SSL-certificaat gebruikt, wordt een consument na betaling doorgestuurd van de beveiligde Buckaroo-betaalpagina’s naar een onbeveiligde pagina op uw webomgeving. De meeste browsers geven een waarschuwing als de gebruiker een beveiligde verbinding verlaat.
Voorbeeld 2: keuzeoptie voor creditcard of iDEAL, met voorgeselecteerde bank, digitale handtekening en eigen variabelen. Ook in dit voorbeeld worden de SSL-pagina’s opgeroepen in het venster waarin de webshop getoond wordt. Bij de iDEAL-gateway kunnen tevens een aantal (geen limiet) eigen velden worden meegegeven, die na de transactieverwerking door de BPE aan de returnpagina weer worden teruggegeven. In dit voorbeeld zijn dat de velden cVar1 t/m cVar6. Deze velden en hun waarden worden ongewijzigd door het proces gevoerd.
Voorbeeld 2 <script language=”JavaScript”> function pay(){ if (!document.pform.pchoice[0].checked && !document.pform.pchoice[1].checked){ alert(“Kies eerst de gewenste betaalmethode”); return; } if (document.pform.pchoice[1].checked && document.pform.BPE_Issuer.value==”X”){ alert(“U kunt uitsluitend met iDeal betalen\nals u bankiert bij één van de genoemde banken.\nSelecteer creditcard of neem contact met ons op…”); document.pform.pchoice[0].checked=true; return; } if (document.pform.pchoice[0].checked){ document.pform.action=”https://payment.buckaroo.nl/sslplus/request_for_authorization.asp” } if (document.pform.pchoice[1].checked){ document.pform.action=”https://payment.buckaroo.nl/gateway/ideal_payment.asp” } document.pform.submit(); }
Toelichting Er worden 2 betaalopties getoond. De keuze kan worden gemaakt middels het aanklikken door de consument van de gewenste betaalwijze. Voor iDEAL is een <select>-tag opgenomen voor het voorselecteren van de gewenste bank. Door op de button “Betaal” te klikken, wordt het Javascript geactiveerd dat voor het versturen van de parameters naar de iDEAL-gateway zorg draagt. Eerst wordt de input van de klant gevalideerd. Vervolgens wordt het betaalscherm getoond, afhankelijk van de gekozen betaalwijze. Ook wordt, afhankelijk van de gekozen betaalwijze, de actieparameter van het
