Implementatie Ideal voor webprogrammeurs

Aansluitend op het succes van Internet bankieren bedachten banken een veilige methode om aankopen op het Internet te kunnen realiseren: iDeal.

We onderscheiden 4 partijen:

de acceptant; een eigenaar van een webstek. Hij heeft een webstek waarop hij iets te koop aanbiedt wat hij per iDeal wil kunnen laten betalen. Hij sluit een overeenkomst met de bank af en zorgt er voor dat zijn webstek met iDeal overweg kan;
de iDeal organisatie - een door de banken gezamenlijk gedragen initiatief. Elke bank onderhoud zijn eigen iDeal server, de uitwisseling van data tussen de diverse partijen is gestandaardiseerd;
de consument; degene die wil betalen via het iDeal mechanisme;
de bank van de consument - aangesloten bij de iDeal organisatie.

Om gebruik te kunnen maken van iDeal moet een acceptant (webaanbieder) een contract met een van de iDeal ondersteunende banken afsluiten. Er zijn drie soorten contracten, afhankelijk van het aantal transacties wat men denkt af te handelen per jaar. De eenvoudigste variant staat tot 100 transacties per jaar toe en kost een vast bedrag per transaktie (dit was 70 eurocent bij de ABNAMRO in november 2008). De andere vormen kosten een bedrag per jaar en een lager bedrag per transaktie.

De bank doet de aanvrager een aantal gegevens toekomen, waarmee deze kan inloggen op het zogenaamde iDeal 'dashboard' bij de bank. Dit is een webportal waarmee het account kan worden beheerd. Vanuit dit dashboard kan bijvoorbeeld een certificaat worden ge-upload zodat beveiligde transakties uit kunnen worden gevoerd vanaf zijn de webstek van de acceptant, als deze dit wil gebruiken.

De banken die zijn aangesloten hebben elk een zogenaamde iDeal server opgesteld, die via het publieke Internet toegankelijk is. Deze iDeal servers staan met elkaar in verbinding en wisselen zo informatie over transakties uit. Ze kunnen vanaf het Internet op twee manieren worden benanderd:

middels plain text POST operaties over https
middels XML opgemaakte boodschappen door een TLS/SSL tunnel

Beide manieren kunnen ook door elkaar worden gebruikt, het hangt af van de gewenste functionaliteit en de handigheid van de programmeur. Beide methoden worden hieronder nader uitgelegd.

POST over https

op een website wordt een artikel te koop aangeboden. De pagina met het te verkopen item bevat een formulier <FORM> en een submit button, waarop bijvoorbeeld de tekst 'betalen via iDeal'. In dat formulier zullen vaak al een aantal variabelen (HIDDEN) zijn gegenereerd vanuit een (mySQL) database, andere dienen door de eindgebruiker in de browser te worden ingevuld. Dan verstuurt de browser van de gebruiker het formulier naar de iDeal server van de bank waar het account is afgesloten. In een dergelijke POST operatie worden de volgende velden verstuurd:

PM altijd de string "iDEAL" (zonder quotes)

PSPID de door de bank aan de webstek eigenaar gegeven identificatie

language de taal, in ons geval altijd NL_NL

orderID een unieke order identificatie

amount het bedrag, uitgedrukt in de kleinste eenheden (e.g. centen, dus 16 euro en 20 centen wordt: 1620)

currency in welke eenheden is het bedrag uitgedrukt; in Nederland is dat EUR

COM een orderomschrijving

CN de Customer Name, naam van de klant

EMAIL het e-mail adres van de klant

owneraddress het woonadres van de klant

ownertown stad waarin de klant woont

ownerzip de postcode van het adres van de klant

ownercty land waarin de besteller woont, meestal NL

een koper wil kopen en hij klikt dus op de button. Het FORM wordt nu door de browser verzonden naar de iDeal server van de bank van de verkoper. Die server is publiek bereikbaar op het Internet;
de iDeal webserver van de verkoper ontvangt de variabelen en controleert de inhoud. Een transaktie wordt voorbereid binnen de iDeal infrastructuur, met een uniek kenmerk. Dan wordt een pagina gegenereerd en naar de browser van de eindgebruiker gezonden, waarop deze kan kiezen bij welke bank hij is aangesloten;
de klant kiest zijn bank en drukt op de button. Daardoor worden de eerder opgegeven data verzonden naar de iDeal server bij de bank van de eindgebruiker;
de iDeal server bij de bank van de eindgebruiker genereert de inlogpagina, die de gebruiker normaliter ook krijgt als hij wil Internetbankieren. Na inloggen wordt de gebruiker echter doorgezet naar een speciale iDeal pagina waarop aan de hand van de transaktiecode de eerder al doorgegeven betaalgegevens, omschrijving etc. alvast zijn ingevuld;
de eindgebruiker authoriseert deze transaktie en de bank betaalt het product;
dit wordt weer binnen de iDeal infrastructuur geregistreerd. De iDeal server van de bank van de klant stuurt nu een nieuwe pagina naar de browser van de koper met daarop een redirect naar een door de acceptant (verkoper) eerder gespecificeerde ontvangstpagina (bijvoorbeeld vanuit het dashboard ingesteld), deze pagina zal meestal een pagina zijn op de site van de acceptant;
er kan in die ontvangstpagina van de verkoper logica zitten (zie methode XML/TSL) die contact opneemt met de eigen bank om te vragen of het overgemaakte geld daadwerkelijk op de rekening is binnengekomen, de bank antwoord dan met een ja of nee, zo ja kan de bestelling dus volautomatisch worden afgerond;
de bank van de verkoper kan ook mail genereren met details over de transaktie en die mail sturen naar de verkoper, zodat die de bestelling handmatig kan afwerken.

webshop
ACCEPTANT
webserver klant
CONSUMENT
browser bank verkoper
BANK
webserver bank koper
BANK
webserver

genereert bestelformulier

stuurt form naar bank

ontvangt en controleert

genereert pagina met form: welke bank gebruikt klant?

geeft bank aan

stuurt form naar bank

ontvangt en controleert

stuurt tx data naar bank klant

ontvangt tx gegevens koper

genereert redirect naar inlogpagina bank klant

ontvangt redirect, logged in

laat tx data zien

authoriseert transaktie

voert tx uit

stuurt redirect

voert redirect uit stuurt mail naar acceptant

ontvangt input van redirect

neemt contact met bank op

bevestigt succes transaktie

ontvangt mail

initieert logistieke afhandeling ;

genereert bestelformulier

Een voorbeeld van het verloop van dit proces vindt je hier.

XML over SSL/TLS

Deze methode gaat er van uit dat de acceptant (webwinkel) een server beheert waarop zich software bevindt die met de bank kan communiceren. Er zijn bijvoorbeeld PHP bibliotheken beschikbaar waarmee dit mogelijk is. De acceptant (webwinkel eigenaar) dient een sleutelpaar te genereren en ofwel zelf te tekenen, ofwel te laten tekenen. Hij upload het publieke deel van dit paar naar de bank (via het dashboard/webportel waar hij toegang tot heeft).

Nu is het voor hem mogelijk XML opgemaakte boodschappen uit te wisselen met de iDeal server bij zijn bank. Het gaat ook hier weer om POST opdrachten, maar de boodschappen zijn nu opgemaakt in XML opmaak en bevatten onder meer zogenaamde tokens: standaard boodschappen die zijn gesigned met de private sleutel van de klant. De iDeal server die de boodschap ontvangt kan middels de eerder ge-uploade public key van de zender de boodschap decoderen en op die manier verifieren dat de boodschap inderdaad van de desbetreffende zender afkomstig is. Een voorbeeld van zo'n XML boodschap volgt:

<?xml version="1.0" encoding="UTF-8"?>
<AcquirerTrxReq xmlns="http://www.idealdesk.com/Message" version="1.1.0">
  <createDateTimeStamp> VAR </createDateTimeStamp>
  <Issuer>
    <issuerID> VAR </issuerID>
  </Issuer>
  <Merchant>
    <merchantID> VAR </merchantID>
    <subID> VAR </subID>
    <authentication> VAR </authentication>
    <token> VAR </token>
    <tokenCode> VAR </tokenCode>
    <merchantReturnURL> VAR </merchantReturnURL>
  </Merchant>
  <Transaction> 
    <purchaseID> VAR </purchaseID>
    <amount> VAR </amount>
    <currency> VAR </currency>
    <expirationPeriod> VAR </expirationPeriod>
    <language> VAR </language>
    <description> VAR </description>
    <entranceCode> VAR </entranceCode>
  </Transaction> 
</AcquirerTrxReq>

Het is middels deze techniek ook mogelijk de iDeal server te vragen om een lijst van beschikbare banken, zodat er op de webserver van de acceptant al een dropdown gemaakt kan worden, of zelfs kan worden onthouden voor de klant bij welke bank hij is aangesloten. De acceptant kan middels deze techniek ook bij de bank navragen of een transactie is gelukt of niet en zo dus onmiddellijk de logistiek afhandelen.

PM	altijd de string "iDEAL" (zonder quotes)
PSPID	de door de bank aan de webstek eigenaar gegeven identificatie
language	de taal, in ons geval altijd NL_NL
orderID	een unieke order identificatie
amount	het bedrag, uitgedrukt in de kleinste eenheden (e.g. centen, dus 16 euro en 20 centen wordt: 1620)
currency	in welke eenheden is het bedrag uitgedrukt; in Nederland is dat EUR
COM	een orderomschrijving
CN	de Customer Name, naam van de klant
EMAIL	het e-mail adres van de klant
owneraddress	het woonadres van de klant
ownertown	stad waarin de klant woont
ownerzip	de postcode van het adres van de klant
ownercty	land waarin de besteller woont, meestal NL

webshop ACCEPTANT webserver	klant CONSUMENT browser	bank verkoper BANK webserver	bank koper BANK webserver
genereert bestelformulier
	stuurt form naar bank
		ontvangt en controleert
		genereert pagina met form: welke bank gebruikt klant?
	geeft bank aan
	stuurt form naar bank
		ontvangt en controleert
		stuurt tx data naar bank klant
			ontvangt tx gegevens koper
		genereert redirect naar inlogpagina bank klant
	ontvangt redirect, logged in
			laat tx data zien
	authoriseert transaktie
			voert tx uit
			stuurt redirect
	voert redirect uit		stuurt mail naar acceptant
ontvangt input van redirect
neemt contact met bank op
		bevestigt succes transaktie
ontvangt mail
initieert logistieke afhandeling			;
genereert bestelformulier