Integratiehandleiding Rabo OmniKassa

Transcriptie

1 Integratiehandleiding Rabo OmniKassa Versie januari

2 INHOUD 1. Inleiding Betaalstappen Beschrijving protocol POST velden De syntax van veld Data De syntax van veld Seal Hoe wordt een betaling geïmplementeerd? Betalingsverzoek Velden van het betalingsverzoek Voorbeeld In geval van fouten Respons op betaling Handmatige respons Automatische respons Probleemoplossing voor het niet ontvangen van responsen Rabo OmniKassa Foutbeheer geen afsluitend veld in de respons Hoe wordt een bericht afgesloten? (SEAL) Waarom een bericht afsluiten? Methode die gebruikt wordt voor afsluiten bericht Voorbeelden codering Java Php net Hoe te testen? Testen ideal transactie Testen MiniTix transactie Testen card transactie

3 6.4 Testen acceptgiro /incasso /rembours transactie Hoe live te gaan? (GO LIVE) Identificatie ondernemers Pre live testen Productie/go live Beschrijving berichten Betalingsverzoek Verplichte velden Optionele velden Responsen (automatisch en handmatig) Gegevenswoordenboek Conventie formaat Beschrijving velden Valutacodes en bedragen Talen van klanten Betaalmethoden De responscode van de Rabo OmniKassa Acceptatiegegevens ideal Acceptatiegegevens MiniTix Acceptatiegegevens Incasso, AcceptGiro, Rembours

4 1. INLEIDING Dit document geeft uitleg over de uitwisselingen die plaatsvinden tussen de site van de ondernemer en de Rabo OmniKassa server met behulp van de redirect connector gateway van de Rabo OmniKassa. Deze connector beoogt de implementering van de zijde van de ondernemer zo eenvoudig als mogelijk te laten verlopen en bestaat uit betalingsverzoeken en responsen die in de vorm van HTTP(S) posts gedaan worden naar en van de Rabo OmniKassa betaalserver. Vereisten Technisch Om een client voor de redirector connector te ontwikkelen, is kennis van één van de talen nodig die meestal gebruikt worden voor web programmeren, zoals Java, PHP of.net. Beveiliging Het platform voor betalingen voldoet aan PCI DSS (Payment Card Industry Data Security Standard) een beveiligingsstandaard opgezet door o.a. VISA en MASTERCARD). Met de Rabo OmniKassa oplossing hoeft de ondernemer het PAN (Primary Account Number) dat voor betalingen gebruikt wordt, niet te weten. Dit is bijvoorbeeld het nummer van een creditcard. Het betalingsverzoek en de responsen worden beveiligd uitgewisseld tussen de webshop en de betaalserver via een gedeelde geheime sleutel. De sleutel moet opgeslagen worden in een beveiligde omgeving op de website van de webwinkel. In geval van (mogelijk) misbruik van de geheime sleutel dient de ondernemer dringend contact op te nemen met het Support Team Rabo OmniKassa om deze sleutel te (laten) vernieuwen. Dit team is van maandag tot en met zaterdag van 8.00 tot uur en s zondags van 8.00 tot uur bereikbaar op telefoonnummer

5 2. BETAALSTAPPEN Het doel is om de 3 betaalstappen, die voor elke betaling tussen de webwinkel en de betaalserver worden gezet, te implementeren. Betaalpagina op website ondernemer 1: de klant gaat verder naar het afrekenen van de bestelling/order (betalingsverzoek) Redirect connectorgateway Rabo OmniKassa 2: de connector leidt de klant naar de pagina voor betaling (redirect) Betaalpagina op betaalserver van Rabo OmniKassa Retourpagina op de website van de winkelier Automatische response 3a: de klant keert terug naar de website van de winkelier (handmatige respons) 3b: de connector stuurt een automatische respons naar de website van de winkelier (waarop de klant de gewenste betaalmethode kan kiezen en de gevraagde bankgegevens kan invullen) Betaalstap 1 Nadat de klant op de website van de ondernemer heeft gekozen voor afrekenen (het doen van een betaling), moet een payment request (betalingsverzoek) naar de Rabo OmniKassa server (betreft een URL, die voor dit doel aan de ondernemer ter beschikking is gesteld), worden verzonden. De meest eenvoudige weg is het gebruik van een HTML FORMULIER, maar oplossingen waarbij een HTTP POST verstuurd wordt zijn ook mogelijk. Betaalstap 2 Hierna wordt de klant geleid naar de betaalpagina van de Rabo OmniKassa betaalserver en kan de daadwerkelijke betaling uitgevoerd worden. Als deze stap is afgerond, (succesvol of eindigend in een fout), worden responsen verzonden vanaf de betaalserver naar de respons URL's die meegegeven zijn als parameters van het betalingsverzoek. Betaalstap 3 : 3a: Handmatige responsen die door de betaalserver als HTTP(S) POST s verzonden worden naar de normale retour URL zoals aangegeven in het verzoek als de klant op de link voor terugkeren naar site ondernemer klikt in de betaalpagina. Hierna hoort de klant naar de betreffende pagina op de site van de ondernemer geleid te worden. Houd er rekening mee dat dit alleen gebeurt als 5

6 de klant op bedoelde link klikt; dit is niet verplicht of gegarandeerd. Betaalstap 3b: Automatische responsen worden altijd als HTTP(S) POST s verzonden door de betaalserver naar de automatische respons URL zoals aangegeven in het betalingsverzoek, nadat het betalingsproces afgerond is. Opmerking Na een niet geslaagde betalingshandeling wordt de klant naar een foutpagina geleid waarin hij op een link kan klikken om terug te keren naar de site van de ondernemer. Op dat moment wordt de transactie als afgebroken beschouwd. Om dan bijvoorbeeld een andere betaalwijze te gebruiken, moet de gehele betalingstransactie opnieuw uitgevoerd worden, wat begint op de site van de ondernemer. 6

7 3. BESCHRIJVING PROTOCOL 3.1 POST-VELDEN Er worden in betalingsverzoeken en responsen drie velden meegezonden. Data InterfaceVersion Seal Bevat alle informatie over de transactie, verzameld in een enkele reeks zoals uitgelegd in Bevat de gebruikte versie van de interface van de connector Bevat een waarde om de integriteit van de gegevens te valideren. Wordt berekend vanuit veld Data en de geheime sleutel, zoals uitgelegd in Al deze velden zijn verplicht De syntax van veld Data De waarde van veld Data is opgebouwd volgens het volgende schema: <field name>=<value name> <field name>=<value name> <field name>=<value name> Alle voor de transactie benodigde velden (zie ook de gegevens in het Gegevenswoordenboek in 9) moeten in deze reeks aanwezig zijn. De volgorde van de velden maakt niet uit. Voorbeeld van een betalingsverzoek: amount=55 currencycode=978 merchantid= normalreturnurl= transacti onreference= keyversion= De syntax van veld Seal De waarde van veld Seal wordt opgebouwd door toevoeging van de geheime sleutel aan de waarde van veld Data (zie 3.1.1) waarna de bytes van het resultaat als UTF 8 worden opgehaald en gecodeerd met algoritme SHA256 (zie ook 5.2): SHA256( UTF 8(Data+secretKey ) ) 7

8 4. HOE WORDT EEN BETALING GEÏMPLEMENTEERD? 4.1 BETALINGSVERZOEK Het betalingsverzoek moet als HTTP post naar de gateway van de connector worden gedaan. De eenvoudigste manier om dit te doen is het gebruik van een HTML formulier en gebruik van de POSTmethode. Zie onderstaand voorbeeld Velden van het betalingsverzoek Alle gegevens over het betalingsverzoek dienen in de velden van het POST verzoek te staan, zoals aangegeven in 3.1. InterfaceVersion moet ingesteld staan op HP_1.0. Zie het Gegevenswoordenboek in 9 voor een beschrijving van parameters van het betalingsverzoek, het formaat ervan en of ze optioneel of verplicht zijn Voorbeeld <form method="post" target=" payment.server/paymentservlet"> <input type="hidden" name="data" value="amount=55 currencycode=978 merchantid= normalreturnurl= tr ansactionreference= keyversion=1"> <input type="hidden" name="interfaceversion" value="hp_1.0"> <input type="hidden" name="seal" value="21a57f2fe765e1ae4a8bf15d73fc1bf2a533f547f2343d12a499d9c d4"> <input type="submit" value="proceed to payment"> </form> In geval van fouten Als het betalingsverzoek door de gateway ontvangen wordt, worden de waarden van de aangeleverde velden gecontroleerd. Hierna volgt een lijst met fouten die zich voor kunnen doen, inclusief uitleg en tips om de daaruit voortgekomen problemen te verhelpen. Houd er rekening mee dat de volledige gegevens van de fout alleen getoond worden in de simulatieomgeving die bij de integratiestap gebruikt wordt. In de productieomgeving wordt de fout namelijk ook aan de klant getoond, maar dan via een eenvoudige foutpagina met een generieke melding, zoals Uw betaling is niet gelukt. Neem contact op met de webwinkel.. Bericht Oorzaak Oplossing Ongeldig POST veld: <field name> Het POST verzoek bevat een onbekend veld Controleer de beschikbare POSTvelden in de gebruikshandleiding 8

9 Verplicht POST veld ontbreekt: <field name> Onbekende versie interface: <version> Het verplichte POST-veld < field name> ontbreekt in het POSTverzoek De waarde voor <version> in POST-veld InterfaceVersion is onbekend Controleer de verplichte POSTvelden in de gebruikshandleiding Controleer de beschikbare versies van de interface in de gebruikshandleiding Ongeldig sleutelwoord: <param name>=<param value> Ongeldige grootte parameter: <param name>=<param value> Ongeldige waarde parameter: <param name>=<param value> Het verzoek bevat een parameter <param name> die niet verwacht werd in het betalingsverzoek Waarde van parameter <param name> heeft niet de juiste grootte Waarde van parameter <param name> heeft niet het juiste formaat Controleer de parameters voor het betalingsverzoek in het Gegevenswoordenboek Controleer de verwachte waarde voor de grootte van de parameter voor het betalingsverzoek in het Gegevenswoordenboek Controleer de verwachte waarde voor het formaat van de parameter voor het betalingsverzoek in het Gegevenswoordenboek Verplichte parameter ontbreekt: <param name> Onbekende versie sleutel: <version> De verplichte parameter <param name> ontbreekt in het betalingsverzoek De waarde voor <version> van parameter keyversion is onbekend Controleer de verplichte parameters voor het betalingsverzoek in het Gegevenswoordenboek Controleer de voor deze OmniKassa houder beschikbare sleutelversies in het Rabo OmniKassa Dashboard Onbekend webwinkel ID: <ID> De waarde voor merchantid is niet bekend in de database Controleer deze waarde en pas deze zo nodig aan in de parameter merchantid Ongeldige afsluiting (Seal) De controle op de afsluiting van het betalingsverzoek is mislukt door een verkeerd berekende waarde in het betalingsverzoek of een aanpassing in de waarde(n) van één of meer parameters tussen het moment van genereren en het moment van ontvangst door de gateway van Rabo OmniKassa Controleer de regels voor het berekenen van de afsluiting in het Gegevenswoordenboek 9

10 Transactie al verwerkt: <transaction reference> Andere berichten De gateway heeft al een betalingsverzoek met dezelfde waarde voor transactionreference ontvangen en verwerkt Waarborg dat de transactiereferentie voor de transacties uniek is Neem contact op met het Support Team Rabo OmniKassa 4.2 RESPONS OP BETALING Er kan op twee manieren een respons komen op een betalingsverzoek: een handmatige en/of automatische respons Handmatige respons Nadat de klant zijn betalingshandeling op de betaalpagina's afgerond heeft, kan hij op een link terug naar site ondernemer klikken, waardoor hij teruggeleid wordt naar een pagina op de site van de ondernemer waarvan de URL in parameter normalreturnurl van het betalingsverzoek staat. Deze verbinding wordt als HTTP POST verzoek naar de doel URL verzonden, samen met de parameters van de transactie zoals verzonden in het betalingsverzoek, met daarbij extra informatie (status, gebruikte betaalwijze...). Daarom moet gewaarborgd worden dat de doorgegeven doel URL s de informatie kunnen verwerken die door de responsen van de Rabo OmniKassa gateway aangeboden wordt. Zie gegevens POST velden in 3.1. BELANGRIJK: houd er rekening mee dat parameters in de respons dezelfde verdeling in hoofd en kleine letters hebben zoals aangegeven in dit document. De namen worden dus samengesteld uit hoofdletters en kleine letters. InterfaceVersion zal ingesteld worden op HP_1.0. Zie het Gegevenswoordenboek ( 9) van Rabo OmniKassa voor een beschrijving van parameters die in de respons opgenomen zijn. BELANGRIJK: houd er rekening mee dat het kan voorkomen dat de klant niet op de link klikt (browser afgesloten of gestopt, pagina afgesloten, en dergelijke). Er kan daarom niet alleen op de handmatige respons vertrouwd worden als signaal voor de afronding van het betalingsverzoek Automatische respons Als een automaticresponseurl als parameter bij het betalingsverzoek is ingesteld (deze is optioneel), verzendt de betaalserver van Rabo OmniKassa hier een respons naartoe als HTTP POST verzoek die op eenzelfde wijze opgebouwd zijn als een handmatige respons. Zie gegevens POST velden in

11 BELANGRIJK: houd er rekening mee dat parameters in de respons dezelfde verdeling in hoofd en kleine letters hebben zoals aangegeven in dit document. De namen worden dus samengesteld uit hoofdletters en kleine letters. InterfaceVersion zal ingesteld worden op HP_1.0. Zie het Gegevenswoordenboek ( 9) van Rabo OmniKassa voor een beschrijving van parameters die in de respons opgenomen zijn Probleemoplossing voor het niet ontvangen van responsen Rabo OmniKassa Voor het geval dat er geen responsen worden ontvangen op uw server, volgt hier een controlelijst: Controleer of er in het betalingsverzoek URL s aangegeven worden voor respons en of deze geldig zijn. De aangegeven URL s moeten vanaf een externe internettoegang bereikbaar zijn. Een toegangscontrole (inlognaam/wachtwoord of IP filter) of een firewall kan de toegang tot uw server blokkeren. Hits naar de URL s voor respons horen in de toegangsloog van uw server te verschijnen (historie van hits). Als u een niet standaard poort gebruikt, moet deze binnen bereik 80 tot 9999 liggen. U kunt geen contextparameters meegeven aan de respons URL s. In plaats daarvan wordt het orderid gebruikt dat u in het betalingsverzoek hebt aangegeven (optioneel veld) en dat teruggegeven wordt in de parameters van de respons Foutbeheer - geen afsluitend veld in de respons In geval van fouten als Onbekend webwinkel ID, kan de betaalserver de respons niet afsluiten omdat de geheime sleutel ( secret Key ) die door de webwinkel gebruikt is, niet opgehaald kan worden. In dat geval verzendt de betaalserver een respons zonder veld Seal (afsluiting). 11

12 5. HOE WORDT EEN BERICHT AFGESLOTEN? (SEAL) 5.1 WAAROM EEN BERICHT AFSLUITEN? De parameters van de transactie (het betalingsverzoek) worden via de browser van de klant overgedragen. Een oneerlijke klant zou deze daardoor aan kunnen passen voordat het verzoek naar de betaalserver wordt verstuurd. Daarom is het nodig een beveiligingsmethode toe te passen om de integriteit van de transactieparameters te verifiëren. Het feit dat de afsluiting in orde is, betekent twee dingen: Integriteit van de berichten verzoek en respons, dus geen wijzigingen tijdens de uitwisseling; Authenticatie van afzender en ontvanger, omdat ze dezelfde geheime sleutel ( secret Key ) delen. In geval van (mogelijk) misbruik van de geheime sleutel dient de ondernemer dingend contact op te nemen met het Support Team Rabo OmniKassa om deze sleutel te (laten) vernieuwen. Dit team is van maandag tot en met zaterdag van 8.00 tot uur en s zondags van 8.00 tot uur bereikbaar op telefoonnummer METHODE DIE GEBRUIKT WORDT VOOR AFSLUITEN BERICHT Het afsluiten gebeurt door het berekenen van een gecodeerde waarde uit transactieparameters (Data) en een toegevoegde geheime sleutel (secret Key), die voor de klant onbekend is. Reeksen worden voor de codering geconverteerd naar UTF 8 bytes. Het coderingsalgoritme (SHA256) produceert een niet te decoderen resultaat, dat ter vergelijking opnieuw berekent wordt in de Rabo OmniKassa. Het resultaat moet in POST field Seal ingesteld worden als hexadecimale waarde. 5.3 VOORBEELDEN CODERING Java import java.security.messagedigest; public class ExampleSHA256 { /** * table to convert a nibble to a hex char. */ static final char[] hexchar = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'}; /** 12

13 * Fast convert a byte array to a hex string * with possible leading zero. b array of bytes to convert to string hex representation, two chars per byte. */ public static String encodehexstring ( byte[] b ) { StringBuffer sb = new StringBuffer( b.length * 2 ); for ( int i=0; i<b.length; i++ ) { // look up high nibble char sb.append( hexchar [( b[i] & 0xf0 ) >>> 4] ); // look up low nibble char sb.append( hexchar [b[i] & 0x0f] ); } return sb.tostring(); } /** * Computes the seal the Data the parameters to cipher secretkey the secret key to append to the parameters hex representation of the seal, two chars per byte. */ public static String computeseal(string the Data, String secretkey) throws Exception { MessageDigest md = MessageDigest.getInstance("SHA-256"); md.update((the Data+secretKey).getBytes("UTF-8")); } return encodehexstring(md.digest()); /** args */ public static void main(string[] args) { try { System.out.println (computeseal("parameters", "key")); } catch (Exception e) { e.printstacktrace(); } } } Php 5 <?php echo hash('sha256', $Data.$secretKey);?> Data en secretkey moeten de UTF 8 tekenset gebruiken. Zie utf8_encode voor conversie van ISO naar UTF 8. 13

14 5.3.3.net (Met een eenvoudig formulier Form1 dat twee tekstvelden voor invoer bevat: txtrabo, txtsecretkey en één voor uitvoer: lblhex) using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Text; using System.Windows.Forms; using System.Security.Cryptography; namespace ExampleDotNET { public partial class Form1 : Form { public Form1() { InitializeComponent(); } private void cmdgo_click(object sender, EventArgs e) { String schaine = txtrabo.text + txtsecretkey.text; UTF8Encoding utf8 = new UTF8Encoding(); Byte[] encodedbytes = utf8.getbytes(schaine); byte[] sharesult; SHA256 sham = new SHA256Managed(); sharesult = sham.computehash(encodedbytes); } lblhex.text = ByteArrayToHEX(shaResult); private string ByteArrayToHEX(byte[] ba) { StringBuilder hex = new StringBuilder(ba.Length * 2); foreach (byte b in ba) hex.appendformat("{0:x2}", b); return hex.tostring(); } } } 14

15 6. HOE TE TESTEN? Er moet worden getest in de simulatie omgeving van de Rabo OmniKassa. Hiervoor wordt een testwebwinkel ID gebruikt. Hieronder volgt de technische informatie die voor deze omgeving gebruikt kan worden: Simulatie URL connector Webwinkel ID (merchantid) Versie sleutel 1 SecretKey _KEY1 Op de simulatieserver wordt het autorisatieproces gesimuleerd. Daarom is het mogelijk om zonder consequenties betaalinformatie in te vullen op de betaalpagina van de Rabo OmniKassa. Het test webwinkel ID is geregistreerd met de volgende betaalmethoden: ideal, MiniTix, Visa, Mastercard en Maestro. Ook zijn de volgende kassaservices geregistreerd: Incasso, Acceptgiro en rembours. 6.1 TESTEN IDEAL-TRANSACTIE Als u ideal selecteert, wordt u naar de test ideal server geleid, die een ideal transactie simuleert voor het bedrag van de transactie. Hierna wordt u teruggeleid naar de betaalserver die een mededeling toont met het resultaat van de transactie. Simulatieregels ideal : Bedrag transactie Respons ideal 2 Transactie geannuleerd 3 Transactie verlopen 4 Transactie geopend 5 Transactie mislukt Andere gevallen Transactie gelukt 6.2 TESTEN MINITIX-TRANSACTIE Als u MiniTix selecteert, wordt u doorgestuurd naar de test MiniTix server, die een MiniTix transactie simuleert voor het bedrag van de transactie. Hierna wordt u teruggeleid naar de betaalserver die een mededeling toont met het resultaat van de transactie. 15

16 Simulatieregels MiniTix : De MiniTix simulatiepagina biedt verschillende opties om alle mogelijke situaties te testen. 6.3 TESTEN CARD-TRANSACTIE Als u Visa, Mastercard of Maestro als betaalmethode selecteert, wordt u doorgestuurd naar de betaalserver voor simulatie van transacties met deze geselecteerde methode. Simulatieregels Visa, Mastercard, Maestro: De card betaalmethode wordt door de eerste 6 karakters (card prefix) bepaald. De lengte van de PAN (Primary Account Number) moet binnen de 16 en 19 karakters blijven. Card type Card prefix VISA MASTERCARD MAESTRO Alle ondersteunde responscodes voor card transacties (zie 9.6) kunt u simuleren door de laatste 2 karakters te wijzigen. De lengte van de te gebruiken security code moet 3 of 4 karakters lang zijn Voorbeeld: door gebruik van card nummer simuleert u een Visa betaling; deze betaling gaat geweigerd worden met volgende responsecode 05 autorisatie geweigerd. 6.4 TESTEN ACCEPTGIRO-/INCASSO-/REMBOURS-TRANSACTIE Als u Incasso, Acceptgiro of rembours selecteert, wordt u doorgestuurd naar de betrokken betaalpagina vanuit welke alleen maar de Terug naar webwinkel knop beschikbaar is. Indien u op deze knop drukt keert u terug naar de oorspronkelijke webwinkel. Er zijn dus geen specifieke responsecodes voor deze betaalmethoden te testen. 16

17 7. HOE LIVE TE GAAN? (GO LIVE) De volgende stap is de pre live test waarin de laatste testen plaatsvinden voordat de Rabo OmniKassa in productie kan werken ( go live kan gaan). Deze fase maakt een juiste (contract )registratie mogelijk, die afhangt van de door u in uw kassa opgenomen betaalmethoden. 7.1 IDENTIFICATIE ONDERNEMERS De URL die gebruikt kan worden als live /pre live omgeving luidt: Voor toegang tot de live-server heeft u 3 identificatiemiddelen nodig: het merchantid (webwinkel ID) dat de webwinkel identificeert op de betaalserver de KeyVersion, en de secretkey. Deze laatste twee middelen worden gebruikt om het verzoek af te sluiten en de respons te controleren. Het merchantid wordt in de aanmeldingsfase door het Support Team Rabo OmniKassa aan u bekend gemaakt. U verkrijgt een KeyVersion en de secretkey via met een gebruikersnaam en wachtwoord, die genoemd team tijdens de aanmeldingsfase aan u heeft verstrekt. 7.2 PRE-LIVE-TESTEN Tijdens de pre live testen moet een echt creditcardnummer of bankrekeningnummer worden gebruikt, omdat de transacties daadwerkelijk naar de echte Acquirer worden gestuurd voor een autorisatie. Bij transacties met een Visa of Mastercard creditcard volgt er geen financiële afwikkeling, wat betekent dat er geen af en bijschrijving voor de koper en webwinkel zal plaatsvinden. Bij ideal transacties wordt een bericht naar de Acquirer verzonden, dat zowel autorisatie als betalingsgegevens bevat. Dit betekent dat hierbij wèl een af en bijschrijving voor de koper en webwinkel volgen. Het wordt daarom sterk aanbevolen dat de ondernemer eigen creditcardnummers en een eigen (ideal) bankrekeningnummer gebruikt om deze pre live transacties te genereren. 7.3 PRODUCTIE/GO-LIVE Als de pre live testen succesvol zijn afgerond, kan het e mailbericht dat u eerder van ons ontvangen heeft (na ontvangst en verwerking van de door u geretourneerde Overeenkomst Rabo OmniKassa) naar ons worden doorgestuurd. Per website dient u daarin aan te geven op welke datum u de Rabo 17

18 OmniKassa geactiveerd wilt hebben. U kunt dit in één keer voor al uw websites doen of dit bericht meermaals doorsturen (telkens voor één website of voor enkele websites tegelijk). 18

19 8. BESCHRIJVING BERICHTEN 8.1 BETALINGSVERZOEK Verplichte velden Deze velden moeten voor alle transacties meegestuurd worden. Naam veld currencycode merchantid normalreturnurl bedrag transactionreference keyversion Beschrijving Geef de valuta van de transactie aan. Betreft een numerieke code van 3 tekens. Zie bijlage 9.3. ID (Identificatie gegeven) van de webwinkel URL waarnaar de klant teruggeleid moet worden nadat de transactie afgerond is (URL voor handmatige respons). Lengte is beperkt tot 512 tekens. LET OP! De URL mag geen parameters bevatten. Bedrag van de transactie zonder decimaal scheidingsteken (bijv. 106, ). Zie bijlage 9.3. Numerieke reeks, beperkt tot 12 tekens (maximaal bedrag is ) Referentie van de Rabo OmniKassa transactie die uniek moet zijn voor elke ondernemer. Alfanumerieke reeks, beperkt tot 35 tekens. Versie van de te gebruiken geheime sleutel (secretkey) die door aan de ondernemer geleverd/bekend gemaakt wordt. Tabel 1: Betalingsverzoek - verplichte velden Optionele velden Naam veld automaticresponseurl customerlanguage paymentmeanbrandlist Beschrijving URL voor gebruik bij automatische responsen. Lengte is beperkt tot 512 tekens. LET OP! De URL mag geen parameters bevatten. De taal die gebruikt moet worden om de betaalpagina en of de foutpagina weer te geven. Standaard is de taal die van de browser van de gebruiker. Code van 2 tekens lang. Zie bijlage 9.4. Lijst van de geautoriseerde betaalmethoden. Als er een beperking in de keuze voor klanten moet worden gerealiseerd, bevat de lijst van merknamen 19

20 van alle via uw Rabo OmniKassa aan klanten aangeboden betaalmethoden, gescheiden door komma's. Voorbeelden: ideal, MiniTix, Visa, MasterCard. Standaard worden alle ondersteunde betaalmethoden aan de klant voorgelegd/aangeboden/getoond met uitzondering van de kassaservices INCASSO, ACCEPTGIRO en REMBOURS die altijd expliciet opgenomen dienen te worden in de lijst van te gebruiken betaalmethoden (als dit gebruik gewenst is). Zie bijlage 9.5. orderid expirationdate Privéveld voor ondernemer. Dit veld kan bijvoorbeeld door de ondernemer gebruikt worden om de identificatie van de bestelling in zijn informatiesysteem op te slaan. Alfanumerieke reeks, 32 tekens. Verloopdatum van het betalingsverzoek. Alfanumerieke reeks, geformatteerd volgens ISO8601. Zie bijlage 9.1. Tabel 2: Betalingsverzoek - optionele velden 8.2 RESPONSEN (AUTOMATISCH EN HANDMATIG) De inhoud van de automatische en handmatige responsen van de Rabo OmniKassa betaalserver is identiek. De inhoud varieert al naar gelang de status van het betalingsverzoek. Naam veld amount currencycode merchantid transactionreference keyversion orderid responsecode transactiondatetime Beschrijving Zoals aangegeven in het betalingsverzoek. Zoals aangegeven in het betalingsverzoek. Zoals aangegeven in het betalingsverzoek. Zoals aangegeven in het betalingsverzoek. Zoals aangegeven in het betalingsverzoek. Zoals optioneel aangegeven in het betalingsverzoek. Betreft de Rabo OmniKassa responscode van het betalingsverzoek. Zie bijlage 9.6. Als de betaling naar de Acquirer wordt verzonden voor 20

21 autorisatie: datum/tijd in het Rabo OmniKassa systeem waarop de betaling naar de Acquirer wordt verzonden in de tijdzone van de webwinkel. Anders de datum en tijd waarop de responscode van Rabo OmniKassa op de Rabo OmniKassa betaalserver wordt gecreëerd. Alfanumerieke reeks, geformatteerd volgens ISO8601. Zie bijlage 9.1. authorisationid* Identificatie van de autorisatie die door de Acquirer wordt afgegeven. Ingesteld door de ondernemer voor handmatige autorisatie. paymentmeantype* De betaalmethode die de klant gekozen heeft. Zie bijlage 9.5. Merknaam van betaalmethode die de klant gekozen heeft. Zie paymentmeanbrand* bijlage 9.5. complementarycode* maskedpan* Responscode voor aanvullende controles. Toekomstig gebruik! Verborgen Primary Account Number. Formaat is nnnnnn.nnnn (n is een nummer tussen 0 en 9) *: deze velden worden meegezonden als ze beschikbaar zijn, afhankelijk van de status van de transactie en de gekozen betaalmethode. Tabel 3: Velden voor respons op betaling 21

22 9. GEGEVENSWOORDENBOEK 9.1 CONVENTIE FORMAAT Dit hoofdstuk beschrijft de conventie met betrekking tot de kolom Formaat zoals gebruikt in de beschrijving van velden. Of met andere woorden: verklaart de waardes in de kolom Formaat in 9.2 Beschrijving velden. Waarde N A S Numeriek YYYY YY MM DD hh mm ss Beschrijving Geeft aan dat een numerieke waarde [0-9] geaccepteerd wordt Geeft aan dat een alfabetische waarde [aa-zz] geaccepteerd wordt Geeft aan dat speciale tekens geaccepteerd worden Geeft de maximale grootte van het veld aan Geeft het jaar aan Geeft de laatste twee cijfers van het jaar aan Geeft de maand aan Geeft de dag aan Geeft de uren aan (24-uurs indeling) Geeft de minuten aan Geeft de seconden aan Geeft een ISO8601- DateTime-formaat aan (ANS25): YYYY-MM-DDThh:mm:sszzzzzz ISO8601 YYYY-MM-DD: jaar, maand, dag met '-' als scheidingsteken T : «T» is een statische waarde die aangeeft dat daarna een tijdbeschrijving volgt. hh:mm:ss: uren, minuten, seconden met ':' als scheidingsteken. Er kan aan deze tijd een fractie van seconden toegevoegd worden, met als scheidingsteken een punt of een komma. zzzzzz: tijdzone of tijdverschuiving in vergelijking tot UTC, m.b.v. één van de volgende formaten: «Z» of «+hh:mm» of «-hh:mm» url base64url Geeft aan dat een URL geaccepteerd wordt ANS met de volgende geaccepteerde speciale tekens [_-=] 22

23 restrictedstring ANS met de volgende geaccepteerde speciale tekens en blanco liststring extendedstring ANS met de volgende geaccepteerde speciale tekens en blanco ANS met de volgende geaccepteerde speciale tekens [.-,;:_?!<>+=*^/\&~# en blanco Tabel 4: Gegevenswoordenboek - conventie formaat 9.2 BESCHRIJVING VELDEN Onderstaande tabel beschrijft alle velden. Houd er rekening mee dat als er in kolom beschrijving "specifieke waarden" worden genoemd, de lijst met die waarden te vinden is in de sectie "specifieke waarden" van dit document. Naam veld Formaat Beschrijving amount N12 Uiteindelijk bedrag van een transactie (debet of credit) of bedrag van een handeling (terugstorten, annuleren,...) authorisationid automaticresponseurl AN10 ANS512 url Identificatie van de autorisatie die door de Acquirer wordt afgegeven. Ingesteld door de ondernemer voor handmatige autorisatie. Dit is het adres waar de Rabo OmniKassa betaalserver na een betaling of een proces automatisch een respons naartoe moet sturen voor de ondernemer captureday N2 Indicator van vertraging in afhandeling (in dagen). Toekomstig gebruik! capturemode ANS20 Geeft de vastleggingmodus aan (automatisch of zelf ten uitvoer brengen). Toekomstig gebruik! complementarycode N2 Responscode voor aanvullende controles. Toekomstig gebruik! complementaryinfo ANS255 extendedstring Beschrijving van de aanvullende code. Toekomstig gebruik! currencycode N3 Valuta van het bedrag. Specifieke waarden! customerlanguage A2 Taal van de klant; wordt gebruikt voor presentatie aan klanten van onder andere de Rabo OmniKassa betaalpagina. Specifieke waarden! expirationdate ANS25 ISO8601 Verloopdatum van het betalingsverzoek (UTC tijdzone). keyversion N10 Identificatie van de geheime sleutel van de webwinkel maskedpan NS11 Verborgen Primary Account Number. Formaat is nnnnnn.nnnn (n is een nummer tussen 0 en 9) 23

24 merchantid N15 Identificatie van de webwinkel normalreturnurl orderid ANS512 url AN32 Dit is het 'internetadres' dat door de Rabo OmniKassa betaalserver gebruikt wordt om de gebruiker na de betaling verder te leiden. Privéveld voor ondernemer. Dit veld kan bijvoorbeeld door de ondernemer gebruikt worden om de identificatie van de bestelling in het informatiesysteem van de ondernemer op te slaan. paymentmeanbrand ANS20 Merknaam van de betaalmethode. Specifieke waarden! paymentmeanbrandlist ANS128 liststring Lijst van door ondernemer geaccepteerde betaalwijzen. Kan door de ondernemer voor elke transactie worden ingesteld: lijst van geaccepteerde betaalwijzen met een komma ',' als scheidingsteken. Als deze niet is ingesteld, is de standaard lijst van betaalwijzen van toepassing met uitzondering van de kassaservices Incasso, Acceptgiro en Rembours betaalmethoden die altijd in de list opgenomen moeten worden indien gebruik gewenst is. Specifieke waarden (paymentmeans1,paymentmean2,, paymentmeansn). Voorbeeld : ideal, MiniTix, Visa, MasterCard, Maestro, Incasso paymentmeantype ANS20 Type betaalwijze. Specifieke waarden! responsecode transactiondatetime N2 ANS25 ISO8601 De Rabo OmniKassa responscode van een betalingsverzoek. Specifieke waarden! Als de betaling naar de Acquirer wordt verzonden voor autorisatie: datum/tijd in het Rabo OmniKassa betaalserver waarop de betaling naar de Acquirer wordt verzonden in de tijdzone van de webwinkel. Anders de datum en tijd waarop de responscode van Rabo OmniKassa op de Rabo OmniKassa betaalserver wordt gecreëerd. transactionreference AN35 Identificatie van de transactie Tabel 5: Gegevenswoordenboek - beschrijving velden 9.3 VALUTACODES EN BEDRAGEN De valutacodes worden gegeven in ISO 4217 Numeric codification (numerieke codering). Om bedragen in velden in te stellen, beschrijft deze tabel voor elke valuta een voorbeeldbedrag en de waarde ervan. De fractionele eenheid in de volgende tabel staat voor het aantal decimalen van de valuta: Naam valuta Code valuta Fractionele Voorbeeld Waarde eenheid Bedrag Bedrag velden Euro , Amerikaanse Dollar Zwitserse Franc , Pond

25 Canadese Dollar Yen Australische Dollar Noorse Kroon Zweedse Kroon Deense Kroon Tabel 6: Gegevenswoordenboek valutacodes en -bedragen 9.4 TALEN VAN KLANTEN Hier volgt de lijst met belangrijkste taalcodes die gebruikt worden (ISO Alpha2) en hun betekenis. Code en fr de it es nl Taal Engels Frans Duits Italiaans Spaans Nederlands Tabel 7: Gegevenswoordenboek - taal klant 9.5 BETAALMETHODEN PaymentMeanBrand ideal PaymentMeanType CREDIT_TRANSFER Visa MasterCard CARD Maestro MiniTix Incasso Acceptgiro Rembours OTHER (overige) OTHER (overige) OTHER (overige) OTHER (overige) 25

26 Tabel 8: Gegevenswoordenboek - betaalmethoden 9.6 DE RESPONSCODE VAN DE RABO OMNIKASSA Afhankelijk van het verloop van de transactie, kan de geretourneerde responsecode zijn: Code Beschrijving Transaction success, authorization accepted (transactie gelukt, autorisatie geaccepteerd). Please call the bank because the authorization limit on the card has been exceeded (neem contact op met de bank; de autorisatielimiet op de kaart is overschreden) 03 Invalid merchant contract (ongeldig contract webwinkel) Do not honor, authorization refused (niet inwilligen, autorisatie geweigerd) Invalid transaction, check the parameters sent in the request (ongeldige transactie, controleer de in het verzoek verzonden parameters). Invalid card number or invalid Card Security Code or Card (for MasterCard) or invalid Card Verification Value (for Visa/MAESTRO) (ongeldig kaartnummer of ongeldige beveiligingscode of kaart (voor MasterCard) of ongeldige waarde kaartverificatie (voor Visa/MAESTRO)) Cancellation of payment by the end user (betaling geannuleerd door eindgebruiker/klant) 24 Invalid status (ongeldige status). 25 Transaction not found in database (transactie niet gevonden in database) 30 Invalid format (ongeldig formaat) 34 Fraud suspicion (vermoeden van fraude) 40 Operation not allowed to this Merchant (handeling niet toegestaan voor deze webwinkel) 60 Pending transaction (transactie in behandeling) Security breach detected, transaction stopped (beveiligingsprobleem gedetecteerd, transactie gestopt). The number of attempts to enter the card number has been exceeded (three tries exhausted) (het aantal beschikbare pogingen om het cardnummer in te geven is overschreden (max. drie)) Acquirer server temporarily unavailable (server acquirer tijdelijk onbeschikbaar) Duplicate transaction (duplicaattransactie). (transactiereferentie al gereserveerd) Request time out; transaction refused (time out voor verzoek; transactie geweigerd) 26

27 99 Payment page temporarily unavailable (betaalpagina tijdelijk niet beschikbaar) Tabel 9: Gegevenswoordenboek - responscode Zie 9.7 voor gegevens over responscodes voor ideal en 9.8 voor gegevens over responscodes voor MiniTix. 9.7 ACCEPTATIEGEGEVENS IDEAL Dit hoofdstuk geeft informatie over de responscodes met ideal. Veldwaarden ideal status Open Failure sending in (insturen mislukt) ideal ideal - beschrijving Result not known (yet) (resultaat (nog) niet bekend). A new request is necessary to obtain the status (er is een nieuw verzoek nodig om de status te verkrijgen). Issuer unavailable, set by ideal acquirer (uitgever onbeschikbaar, ingesteld door acquirer ideal) Rabobank Omnikassa responsecode 60 (1) In de opgeslagen transacties afhankelijk van de uiteindelijke responsecode van ideal 90 No (nee) Success Positive result; the payment is guaranteed (positief resultaat; de betaling is gegarandeerd) 00 yes (Status=Remitted to the bank) (status=overgemaakt naar de bank) Cancelled (geannuleerd) Expired Failure Negative result due to cancellation by consumer; no payment has been made (negatief resultaat door annulering van consument; er is geen betaling verricht) Negative result due to expiry of validity; no payment has been made (negatief resultaat door verlopen geldigheid; er is geen betaling verricht) Negative result due to other reasons (negatief resultaat om andere redenen) 17 No (nee) 97 (3) No (nee) 05 (4) yes (Status=Refused) (status = geweigerd) Tabel 10: Mapping responscodes ideal 27

28 (1) Transactie niet afgerond, Rabo OmniKassa wacht op de uiteindelijke status van ideal. (3) Rabo OmniKassa stuurt responsecode 97 vanaf Rabo OmniKassa betaalpagina: time out. (4) ideal maakt geen onderscheid tussen technische problemen en functionele afwijzing. 28

29 9.8 ACCEPTATIEGEGEVENS MINITIX Dit hoofdstuk geeft informatie over de responscodes met betrekking tot MiniTix transacties. veldwaarden MiniTix errorcode MiniTix Beschrijving MiniTix responsecode In de opgeslagen transacties 10 Syntax error (syntaxfout) 05 no (nee) 20 Integrity error (fout integriteit) 05 no (nee) 30 Merchant not known (webwinkel niet bekend) 05 no (nee) 31 Merchant disabled (webwinkel niet actief) 05 no (nee) 40 Payment cancelled (betaling geannuleerd) 17 no (nee) 80 Request outside time window (verzoek buiten tijdframe) 97 no (nee) 90 System error (systeemfout) 90 no (nee) 100 Unauthorized customer (nietgeautoriseerde klant) 05 yes (Status=Refused) (status = geweigerd) 110 Payment confirmation started (bevestiging betaling begonnen) 99 no (nee) 120 Insufficient balance (onvoldoende saldo) 05 yes (Status=Refused) (status = geweigerd) NA Transaction OK (transactie ok) 00 yes (Status=Remitted to the bank) (status=overgemaakt naar de bank) Tabel 11: Mapping responscodes MiniTix 29

30 9.9 ACCEPTATIEGEGEVENS INCASSO, ACCEPTGIRO, REMBOURS Aangezien de manier waarop de kassaservices Incasso, Acceptgiro en rembours in de Rabo OmniKassa ondersteund is, bestaan er geen specifieke responscodes voor deze kassaservices buiten de algemene responsecodes (voor details zie in geval van fouten ). 30