Integratiehandleiding Rabo OmniKassa

Integratiehandleiding Rabo OmniKassa Versie 1.0.10 – januari 2012

Integratiehandleiding Rabo OmniKassa Versie 1.0.10 januari 2012

1


INHOUD 1. Inleiding .................................................................................................................................................... 4 2. Betaalstappen ........................................................................................................................................... 5 3. Beschrijving protocol ................................................................................................................................ 7 3.1 POST‐velden ....................................................................................................................................... 7 3.1.1 De syntax van veld Data .............................................................................................................. 7 3.1.2 De syntax van veld Seal ............................................................................................................... 7 4. Hoe wordt een betaling geïmplementeerd? ............................................................................................ 8 4.1 Betalingsverzoek................................................................................................................................. 8 4.1.1 Velden van het betalingsverzoek ................................................................................................ 8 4.1.2 Voorbeeld .................................................................................................................................... 8 4.1.3 In geval van fouten ...................................................................................................................... 8 4.2 Respons op betaling ......................................................................................................................... 10 4.2.1 Handmatige respons ................................................................................................................. 10 4.2.2 Automatische respons ............................................................................................................... 10 4.2.3 Probleemoplossing voor het niet ontvangen van responsen Rabo OmniKassa ........................ 11 4.2.4 Foutbeheer ‐ geen afsluitend veld in de respons ...................................................................... 11 5. Hoe wordt een bericht afgesloten ? (SEAL) ............................................................................................ 12 5.1 Waarom een bericht afsluiten? ........................................................................................................ 12 5.2 Methode die gebruikt wordt voor afsluiten bericht ........................................................................ 12 5.3 Voorbeelden codering ...................................................................................................................... 12 5.3.1 Java ............................................................................................................................................ 12 5.3.2 Php 5 .......................................................................................................................................... 13 5.3.3 .net ............................................................................................................................................ 14 6. Hoe te testen? ........................................................................................................................................ 15 6.1 Testen iDEAL‐transactie ................................................................................................................... 15 6.2 Testen MiniTix‐transactie ................................................................................................................. 15 6.3 Testen card‐transactie ...................................................................................................................... 16

2


6.4 Testen acceptgiro‐/incasso‐/rembours‐transactie ........................................................................... 16 7. Hoe ‘live’ te gaan? (GO‐LIVE).................................................................................................................. 17 7.1 Identificatie ondernemers ................................................................................................................ 17 7.2 Pre‐live‐testen .................................................................................................................................. 17 7.3 Productie/go‐live .............................................................................................................................. 17 8. Beschrijving berichten ............................................................................................................................ 19 8.1 Betalingsverzoek............................................................................................................................... 19 8.1.1 Verplichte velden ...................................................................................................................... 19 8.1.2 Optionele velden ....................................................................................................................... 19 8.2 Responsen (automatisch en handmatig) ......................................................................................... 20 9. Gegevenswoordenboek .......................................................................................................................... 22 9.1 Conventie formaat ............................................................................................................................ 22 9.2 Beschrijving velden ........................................................................................................................... 23 9.3 Valutacodes en bedragen ................................................................................................................. 24 9.4 Talen van klanten ............................................................................................................................. 25 9.5 Betaalmethoden ............................................................................................................................... 25 9.6 De responscode van de Rabo OmniKassa ........................................................................................ 26 9.7 Acceptatiegegevens iDEAL ............................................................................................................... 27 9.8 Acceptatiegegevens MiniTix ............................................................................................................. 29 9.9 Acceptatiegegevens Incasso, AcceptGiro, Rembours ...................................................................... 30

3


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 20.00 uur en ‘s zondags van 8.00 tot 16.00 uur bereikbaar op telefoonnummer 0900‐0400180.

4


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

Retourpagina op de website van de winkelier Automatische response

1: de klant gaat verder naar het afrekenen van de bestelling/order (betalingsverzoek)

Redirect‐connector‐ gateway Rabo OmniKassa

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

2: de connector leidt de klant naar de pagina voor betaling (redirect)

Betaalpagina op betaalserver van Rabo OmniKassa (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


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


3. BESCHRIJVING PROTOCOL 3.1 POST-VELDEN Er worden in betalingsverzoeken en responsen drie velden meegezonden. Data

Bevat alle informatie over de transactie, verzameld in een enkele reeks zoals uitgelegd in § 3.1.1

InterfaceVersion

Bevat de gebruikte versie van de interface van de connector

Seal

Bevat een waarde om de integriteit van de gegevens te valideren. Wordt berekend vanuit veld Data en de geheime sleutel, zoals uitgelegd in § 3.1.2

Al deze velden zijn verplicht. 3.1.1 De syntax van veld Data

De waarde van veld Data is opgebouwd volgens het volgende schema: =|=|=… 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=011223744550001|normalReturnUrl=http://www.normalreturnurl.com|transacti onReference=534654|keyVersion=1

3.1.2 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


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 POST‐ methode. Zie onderstaand voorbeeld. 4.1.1 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. 4.1.2 Voorbeeld

4.1.3 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

Ongeldig POST‐veld: Het POST‐verzoek bevat een onbekend veld

Oplossing Controleer de beschikbare POST‐ velden in de gebruikshandleiding

8


Verplicht POST‐veld ontbreekt:

Het verplichte POST-veld < field Controleer de verplichte POST‐ name> ontbreekt in het POSTvelden in de gebruikshandleiding verzoek

Onbekende versie interface:

De waarde voor in Controleer de beschikbare versies POST-veld InterfaceVersion is van de interface in de onbekend

gebruikshandleiding

Ongeldig sleutelwoord: <param name>=<param value>

Het verzoek bevat een parameter Controleer de parameters voor <param name> die niet verwacht het betalingsverzoek in het werd in het betalingsverzoek Gegevenswoordenboek

Ongeldige grootte parameter: <param name>=<param value>

Waarde van parameter <param Controleer de verwachte waarde name> heeft niet de juiste grootte voor de grootte van de parameter voor het betalingsverzoek in het Gegevenswoordenboek

Ongeldige waarde parameter: <param name>=<param value>

Waarde van parameter <param Controleer de verwachte waarde name> heeft niet het juiste formaat

Verplichte parameter ontbreekt: <param name>

De verplichte parameter <param Controleer de verplichte name> ontbreekt in het parameters voor het betalingsverzoek

voor het formaat van de parameter voor het betalingsverzoek in het Gegevenswoordenboek

betalingsverzoek in het Gegevenswoordenboek

Onbekende versie sleutel:

De waarde voor van Controleer de voor deze parameter keyVersion is onbekend

Onbekend webwinkel ID:

De waarde voor merchantId is niet Controleer deze waarde en pas bekend in de database

OmniKassa‐houder beschikbare sleutelversies in het Rabo OmniKassa Dashboard

deze zo nodig aan in de parameter merchantId

Ongeldige afsluiting (Seal)

De controle op de afsluiting van Controleer de regels voor het het betalingsverzoek is mislukt berekenen van de afsluiting in het door een verkeerd berekende waarde in het betalingsverzoek of Gegevenswoordenboek 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

9


Transactie al verwerkt:

De gateway heeft al een Waarborg dat de betalingsverzoek met dezelfde transactiereferentie voor de waarde voor transactionReference transacties uniek is ontvangen en verwerkt

Andere berichten

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. 4.2.1 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. 4.2.2 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 § 3.1.

10


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. 4.2.3 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.

4.2.4 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


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 20.00 uur en ‘s zondags van 8.00 tot 16.00 uur bereikbaar op telefoonnummer 0900‐0400180. 5.2 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 5.3.1 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

Integratiehandleiding Rabo OmniKassa Versie 1.0.10 – januari 2012 * Fast convert a byte array to a hex string * with possible leading zero. * @param b array of bytes to convert to string * @return hex representation, two chars per byte. */ public static String encodeHexString ( byte[] b ) { StringBuffer sb = new StringBuffer( b.length * 2 ); for ( int i=0; i>> 4] ); // look up low nibble char sb.append( hexChar [b[i] & 0x0f] ); } return sb.toString(); } /** * Computes the seal * @param the Data the parameters to cipher * @param secretKey the secret key to append to the parameters * @return 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()); } /** * @param args */ public static void main(String[] args) { try { System.out.println (computeSeal("parameters", "key")); } catch (Exception e) { e.printStackTrace(); } } }

5.3.2 Php 5

Data en secretKey moeten de UTF‐8 tekenset gebruiken. Zie utf8_encode voor conversie van ISO‐8859‐1 naar UTF‐8.

13

Integratiehandleiding Rabo OmniKassa Versie 1.0.10 – januari 2012 5.3.3 .net

(Met een eenvoudig formulier “Form1” dat twee tekstvelden voor invoer bevat: txtRabo, txtSecretKey en één voor uitvoer: lblHEX) using using using using using using using using

System; System.Collections.Generic; System.ComponentModel; System.Data; System.Drawing; System.Text; System.Windows.Forms; 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


6. HOE TE TESTEN? Er moet worden getest in de simulatie‐omgeving van de Rabo OmniKassa. Hiervoor wordt een test‐ webwinkel ID gebruikt. Hieronder volgt de technische informatie die voor deze omgeving gebruikt kan worden: Simulatie‐URL connector

https://payment-webinit.simu.omnikassa.rabobank.nl/paymentServlet

Webwinkel ID (merchantId) 002020000000001 Versie sleutel 1 SecretKey 002020000000001_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


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

410000

MASTERCARD

510000

MAESTRO

500000

‐

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 “4100000000000005” 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


7. HOE ‘LIVE’ TE GAAN? (GOLIVE) 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: https://payment-webinit.omnikassa.rabobank.nl 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 https://download.omnikassa.rabobank.nl 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


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


8. BESCHRIJVING BERICHTEN 8.1 BETALINGSVERZOEK

8.1.1 Verplichte velden

Deze velden moeten voor alle transacties meegestuurd worden.

Naam veld currencyCode

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

merchantId normalReturnUrl

bedrag

transactionReference

keyVersion

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,55  10655). Zie bijlage §9.3. Numerieke reeks, beperkt tot 12 tekens (maximaal bedrag is 999999999999) 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 8.1.2 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

Integratiehandleiding Rabo OmniKassa Versie 1.0.10 – januari 2012 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. 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.

orderId

expirationDate

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

Beschrijving

amount

Zoals aangegeven in het betalingsverzoek.

currencyCode


merchantId




keyVersion


orderId

Zoals optioneel aangegeven in het betalingsverzoek.

responseCode

Betreft de Rabo OmniKassa responscode van het betalingsverzoek. Zie bijlage § 9.6.

transactionDateTime

Als de betaling naar de “Acquirer” wordt verzonden voor

20

Integratiehandleiding Rabo OmniKassa Versie 1.0.10 – januari 2012 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. Identificatie van de autorisatie die door de Acquirer wordt afgegeven. Ingesteld door de ondernemer voor handmatige autorisatie.

authorisationId*

paymentMeanType* paymentMeanBrand*

De betaalmethode die de klant gekozen heeft. Zie bijlage § 9.5. Merknaam van betaalmethode die de klant gekozen heeft. Zie bijlage § 9.5. Responscode voor aanvullende controles.

complementaryCode* Toekomstig gebruik! maskedPan*

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


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

Beschrijving

N

Geeft aan dat een numerieke waarde [0-9] geaccepteerd wordt

A

Geeft aan dat een alfabetische waarde [aA-zZ] geaccepteerd wordt

S

Geeft aan dat speciale tekens geaccepteerd worden

Numeriek YYYY

Geeft de maximale grootte van het veld aan Geeft het jaar aan

YY

Geeft de laatste twee cijfers van het jaar aan

MM

Geeft de maand aan

DD

Geeft de dag aan

hh

Geeft de uren aan (24-uurs indeling)

mm

Geeft de minuten aan

ss

Geeft de seconden aan Geeft een ISO8601- DateTime-formaat aan (ANS25): YYYY-MM-DDThh:mm:sszzzzzz  

ISO8601  

url base64Url

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 »

Geeft aan dat een URL geaccepteerd wordt ANS met de volgende geaccepteerde speciale tekens [_-=]

22


restrictedString ANS met de volgende geaccepteerde speciale tekens [[email protected]+] en blanco listString extendedString

ANS met de volgende geaccepteerde speciale tekens [[email protected]+,] 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 Uiteindelijk bedrag van een transactie (debet of credit) of bedrag van een handeling (terugstorten, annuleren, ...)

amount

N12

authorisationId

AN10

Identificatie van de autorisatie die door de Acquirer wordt afgegeven. Ingesteld door de ondernemer voor handmatige autorisatie.

automaticResponseUrl

ANS512 url

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

captureMode

ANS20

complementaryCode

N2

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)

Indicator van vertraging in afhandeling (in dagen). Toekomstig gebruik! Geeft de vastleggingmodus aan (automatisch of zelf ten uitvoer brengen). Toekomstig gebruik! Responscode voor aanvullende controles. Toekomstig gebruik!

23

Integratiehandleiding Rabo OmniKassa Versie 1.0.10 – januari 2012 merchantId

N15

Identificatie van de webwinkel

normalReturnUrl

ANS512 url

Dit is het 'internetadres' dat door de Rabo OmniKassa‐betaalserver gebruikt wordt om de gebruiker na de betaling verder te leiden.

orderId

AN32

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!

ANS128 paymentMeanBrandList 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 Type betaalwijze. Specifieke waarden!

paymentMeanType

ANS20

responseCode

N2

De Rabo OmniKassa responscode van een betalingsverzoek. Specifieke waarden!

transactionDateTime

ANS25 ISO8601

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.


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 Euro Amerikaanse Dollar Zwitserse Franc Pond

Code valuta Waarde 978 840 756 826

Fractionele eenheid 2 2 2 2

Voorbeeld Bedrag Bedrag velden 106,55 10655 106.55 10655 106,55 10655 106.55 10655 24


Canadese Dollar Yen Australische Dollar Noorse Kroon Zweedse Kroon Deense Kroon

124 392 036 578 752 208

2 0 2 2 2 2

106.55 106 106.55 106.55 106.55 106.55

10655 106 10655 10655 10655 10655

Tabel 6: Gegevenswoordenboek – valutacodes en -bedragen 9.4 TALEN VAN KLANTEN Hier volgt de lijst met belangrijkste taalcodes die gebruikt worden (ISO 639‐1 Alpha2) en hun betekenis. Code

Taal

en

Engels

fr

Frans

de

Duits

it

Italiaans

es

Spaans

nl

Nederlands

Tabel 7: Gegevenswoordenboek - taal klant

9.5 BETAALMETHODEN PaymentMeanBrand PaymentMeanType iDEAL

CREDIT_TRANSFER

Visa MasterCard

CARD

Maestro

MiniTix

OTHER (overige)

Incasso

OTHER (overige)

Acceptgiro

OTHER (overige)

Rembours

OTHER (overige)

25


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 00 02 03 05 12

14

17

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) 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)

75 90 94 97

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)

24

63

Beschrijving

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 card‐ nummer 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


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. iDEAL Veldwaarden iDEAL status

iDEAL - beschrijving

Rabobank Omnikassa responseCode

In de opgeslagen transacties

Open

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).

60 (1)

afhankelijk van de uiteindelijke responseCode van iDEAL

Failure sending in (insturen mislukt)

Issuer unavailable, set by iDEAL acquirer (uitgever onbeschikbaar, ingesteld door acquirer 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)

Negative result due to cancellation by consumer; no payment has been made (negatief resultaat door annulering van consument; er is geen betaling verricht)

17

No (nee)

Expired

Negative result due to expiry of validity; no payment has been made (negatief resultaat door verlopen geldigheid; er is geen betaling verricht)

97 (3)

No (nee)

Failure

Negative result due to other reasons (negatief resultaat om andere redenen)

05 (4)

yes (Status=Refused) (status = geweigerd)

Tabel 10: Mapping responscodes iDEAL

27


(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


9.8 ACCEPTATIEGEGEVENS MINITIX Dit hoofdstuk geeft informatie over de responscodes met betrekking tot MiniTix‐transacties.

MiniTix veldwaarden MiniTix Beschrijving MiniTix errorCode 10 Syntax error (syntaxfout)

responseCode

In de opgeslagen transacties

05

no (nee) no (nee)

20

Integrity error (fout integriteit)

05

30

Merchant not known (webwinkel niet bekend)

05

31

Merchant disabled (webwinkel niet actief)

05

40

Payment cancelled (betaling geannuleerd)

17

80

Request outside time window (verzoek buiten tijdframe)

97

90

System error (systeemfout)

90

no (nee)

100

Unauthorized customer (niet‐ geautoriseerde klant)

05


110

Payment confirmation started (bevestiging betaling begonnen)

99

120

Insufficient balance (onvoldoende saldo)

05


00

yes (Status=Remitted to the bank) (status=overgemaakt naar de bank)

NA

Transaction OK (transactie ok)

no (nee)

no (nee)

no (nee)

no (nee)

no (nee)

Tabel 11: Mapping responscodes MiniTix

29


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 §4.1.3”).

30

Integratiehandleiding Rabo OmniKassa

Recommend Documents