Integratiehandleiding Rabo OmniKassa Versie 3.0, november Versie 3.1, november 2012

Transcriptie

1 Integratiehandleiding Rabo OmniKassa Versie 3.1, november

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? 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 Activeren van de Rabo OmniKassa 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 De integratiehandleiding beschrijft hoe de Rabo OmniKassa kan worden geïntegreerd in de webwinkel. U vindt een 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 Voor de installatie van de Rabo OmniKassa is kennis nodig van één van de talen 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 5

6 op de site van de ondernemer geleid te worden. Houd er rekening mee dat dit alleen gebeurt als 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" action=" 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> De verplichte parameter <param name> ontbreekt in het betalingsverzoek Controleer de verplichte parameters voor het betalingsverzoek in het Gegevenswoordenboek Onbekende versie sleutel: <version> Onbekend webwinkel ID: <ID> De waarde voor <version> van parameter keyversion is onbekend De waarde voor merchantid is niet bekend in de database Controleer de voor deze OmniKassa-houder beschikbare sleutelversies in het Rabo OmniKassa Dashboard 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? 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? In de simulatieomgeving van de Rabo OmniKassa kunnen testtransacties gedaan worden met behulp van een test-webwinkel ID. Gebruik van het eigen webwinkel ID in deze omgeving is niet mogelijk en leidt tot een foutmelding. Er kan getest worden met de betaalmethoden ideal, MiniTix, Visa, MasterCard en Maestro en met de kassaservices Acceptgiro, Incasso en rembours. Hieronder staat de voor de simulatieomgeving benodigde technische informatie en een belangrijke mededeling: Simulatie-URL connector Webwinkel ID (merchantid) Versie sleutel 1 SecretKey _KEY1 Belangrijk Voor elke transactie is een unieke transactiereferentie vereist in het veld 'transactionreference'. Dit kunt u in de simulatieomgeving bijvoorbeeld realiseren door gebruik te maken van uw KvK-nummer, gevolgd door een zelfbepaalde code voor uw webwinkel (als u meer webwinkels heeft) en een referentie naar eigen keuze. Bijvoorbeeld: uw KvK-nummer is , de webshop-code is 01 en het order ID uit uw webwinkelpakket is 1, dan resulteert dat in de transactiereferentie 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 15

16 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. 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. ACTIVEREN VAN DE RABO OMNIKASSA De gegevens voor het activeren van de Rabo OmniKassa, ontvangt u van de Rabobank nadat de Rabobank van de aanvrager het contract Rabo OmniKassa getekend retour heeft ontvangen en is goedgekeurd. Op dat moment worden de gegevens aangemaakt die nodig zijn om de Rabo OmniKassa te activeren. U zet de Rabo OmniKassa in productie door de URL van de simulatieomgeving te vervangen door de URL van de productieomgeving: Voor de toegang tot de live-server heeft u 3 identificatiemiddelen nodig: 1. het merchantid (webwinkel ID) dat de webwinkel identificeert op de betaalserver 2. de KeyVersion, (versie van de sleutel) 3. de SecretKey (geheime sleutel) De KeyVersion en SecretKey worden gebruikt om het verzoek af te sluiten en de respons te controleren. Uw KeyVersion en SekretKey vindt u op de downloadsite van de Rabo OmniKassa: Voor de toegang tot de downloadsite ontvangt de technisch contactpersoon een gebruikersnaam via . Om veiligheidsredenen wordt het wachtwoord van de downloadsite verstuurd naar het postadres van de aanvrager t.a.v. de technisch contactpersoon. Dit geldt ook als er sprake is van een externe partij die de installatie verzorgt. De brief met het wachtwoord wordt verzonden vanuit Frankrijk. Let op: de geheime sleutel (SecretKey) is slechts 30 dagen beschikbaar op de downloadsite. Na het verstrijken van deze termijn vraagt u via de downloadsite een nieuwe geheime sleutel aan. 17

18 8. BESCHRIJVING BERICHTEN 8.1 BETALINGSVERZOEK Verplichte velden Deze velden moeten voor alle transacties meegestuurd worden. Naam veld currencycode merchantid normalreturnurl amount 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 18

19 van alle via uw Rabo OmniKassa aan klanten aangeboden betaalmethoden, gescheiden door komma's. De merknaam van elke betaalmethode altijd in hoofdletters opnemen! En de volgorde van opnemen in dit veld bepaalt de volgorde waarin de methoden aan uw klant worden getoond! 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 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. 19

20 responsecode transactiondatetime Betreft de Rabo OmniKassa responscode van het betalingsverzoek. Zie bijlage 9.6. Als de betaling naar de Acquirer wordt verzonden voor 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 20

21 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 [_-=] 21

22 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 (terugstorting/refund, annulering,...) 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) 22