Voorwaarden

De iDEAL Merchant Integratie Gids wordt door de producteigenaar Currence beschikbaar gesteld onder de volgende voorwaarden:

1. Currence iDEAL B.V. als eigenaar van het iDEAL Scheme stelt de iDEAL Merchant Integratie Gids beschikbaar aan Acquiring banken die deze vervolgens distribueren aan (potentiële) Merchants en Payment Service Providers opdat zij als (potentiële) afnemers van iDEAL zich een goed beeld kunnen vormen van wat het betekent om tot het voeren van het product over te gaan.

2. Currence iDEAL B.V. behoudt zich het recht voor om beschikbaarstelling van de iDEAL Merchant Integratie Gids te weigeren voor (potentiële) Merchants en Payment Service Providers op grond van haar moverende redenen, in overleg met de Acquiring bank waarmee de Merchant/PSP een contract heeft.

3. De iDEAL Merchant Integratie Gids wordt nadrukkelijk uitsluitend met bovenstaand doel ter beschikking gesteld en enig ander gebruik is niet toegestaan. Aan het document of de in de bijgaande toelichting gegeven informatie kunnen geen rechten worden ontleend. Currence iDEAL B.V. is op geen enkele wijze aansprakelijk voor de gevolgen van latere wijzigingen van de iDEAL Standaard of de iDEAL Merchant Integratie Gids. Indien banken of andere geïnteresseerden beslissingen nemen en/of investeringen doen op basis van de informatie die zij via deze iDEAL Merchant Integratie Gids hebben verkregen, dan accepteert Currence iDEAL B.V. hiervoor geen enkele aansprakelijkheid.

4. De iDEAL Merchant Integratie Gids is een vertaling van de Engelstalige iDEAL Merchant Integration Guide, die is gebaseerd op de informatie in de iDEAL Standaard documenten. Deze vertaling is met grote zorgvuldigheid samengesteld. Indien er toch afwijkingen zijn tussen de Nederlandse vertaling en het Engelstalige origineel dan is de Engelstalige versie leidend. In het geval er afwijkingen zijn tussen de Merchant Integratie Gids en de iDEAL Standaard documenten dan is de tekst in de Standaard documenten leidend.

Alle vragen over dit document of verzoeken om meer informatie kunnen worden gericht aan uw iDEAL acquiring bank of Collecterende Payment Service Provider.

Inhoud

1. Inleiding 

2. Overzicht 

2.1 Wat is iDEAL?

iDEAL is een internet betaalmethode voor de Nederlandse markt. De grootste Nederlandse banken hebben gezamenlijk de iDEAL standaard ontwikkeld. Hierdoor kunnen Consumenten online real-time betalen aan iDEAL Merchants.
De belangrijkste kenmerken van iDEAL zijn:

• Real-time betaling via een vertrouwd bestaand internetbankier-product waar de Consument al bekend mee is.

• Direct een betaalbevestiging voor de Consument en real-time betaalgarantie afgegeven aan de Merchant door de Acquiring bank met een daaropvolgende onherroepelijke overboeking ten gunste van de Merchant.

• Geschikt voor zowel online leveringen (bijv. downloads, opwaarderen beltegoed) als offline leveringen (fysieke goederen) en tijdgebonden leveringen (bijv. vliegtickets).

• Biedt de flexibiliteit om betalingen te doen met verschillende doelen (bijvoorbeeld donaties, telefonische/e-mail bestellingen).

Elke Consument die de beschikking heeft over een internetbankier-product van een bij iDEAL aangesloten Nederlandse bank kan in principe via iDEAL betalen.

2.2 Wat is iDEAL mobiel?

iDEAL is een internetbetaalmethode voor de Nederlandse markt. Hoewel oorspronkelijk ontwikkeld voor gebruik met internetbankieren, is het nu ook mogelijk voor Issuers om iDEAL aan te bieden gebaseerd op mobiele bankierdiensten, zoals mobiele websites of mobiele apps. Dit heeft de naam iDEAL mobiel.
De belangrijkste kenmerken van iDEAL mobiel zijn:

• Er zijn geen veranderingen in de berichten die worden uitgewisseld tussen Issuers en bank van de Merchant en geen veranderingen in berichten tussen de Merchant en zijn bank ten opzichte van regulier iDEAL;

• Merchant en Consument hoeven geen extra handelingen te verrichten voor het uitvoeren van een mobiele iDEAL transactie. Het omleiden van de Consument naar een mobiel bankierkanaal wordt geautomatiseerd gedaan door de bank van de Consument. Bij banken die iDEAL in hun bankier-app ondersteunen kan de Consument kiezen of hij wil betalen via de mobiele web browser of via de bankieren-app;

• De grondslag van iDEAL mobiel is betrouwbaarheid, veiligheid en gebruiksvriendelijkheid, net als iDEAL op een PC of laptop. In die gevallen waar mobiele technologie niet dezelfde technische veiligheidsmaatregelen ondersteunt als een desktop computer zal de bank alternatieve veiligheidsmaatregelen treffen ter compensatie.

Iedere Consument die een internetbankierproduct afneemt bij één van de iDEAL Issuers kan met iDEAL betalen via een mobiel apparaat (al zal het soms nodig zijn voor een Consument om een mobiele applicatie/app hiervoor te downloaden). Die Issuers die (nog) geen iDEAL mobiel implementatie hebben, of die een implementatie hebben die nog niet de meerderheid van alle Consumenten kan bereiken, zal nog steeds in staat zijn om transacties te verwerken via de reguliere iDEAL pagina's op de browser van het mobiele apparaat.

2.3 Vier partijen model

Bij een iDEAL transactie spelen tenminste 4 partijen een rol. Allereerst is er de Consument die (op internet) een product koopt of een dienst afneemt. Dat doet hij bij de acceptant van de iDEAL betaling, meestal een webwinkelier. De webwinkelier wordt door banken (en in de rest van dit document) ook wel "Merchant" genoemd. De Consument heeft een relatie met zijn bank waar hij in zijn internetbankier-omgeving iDEAL betalingen kan doen. De bank van de Consument heet binnen iDEAL de Issuer. De Merchant heeft met zijn bank een contract afgesloten om iDEAL betalingen te kunnen accepteren. De bank van de Merchant wordt binnen iDEAL de Acquirer genoemd. Zoals in de inleiding al opgemerkt behandelt dit document de iDEAL berichten die tussen de Merchant en de Acquirer worden uitgewisseld. De iDEAL berichten die tussen Issuer en Acquirer worden uitgewisseld komen in dit document slechts zijdelings aan bod voor zover dat nodig is voor een goed begrip van het verloop van een iDEAL transactie.

Naast deze 4 partijen, die in elk geval een rol spelen bij een iDEAL transactie, kunnen er nog andere partijen betrokken zijn. Zo kan de Merchant bijvoorbeeld via een Payment Service Provider (PSP) zijn aangesloten op een Acquirer. In situaties waarbij de betalingen binnenkomen op de bankrekening van de PSP treedt deze "collecterende" PSP (CPSP) op als de Merchant bij de iDEAL betalingen en sluit het iDEAL contract met de Acquirer ten behoeve van één of meerdere achterliggende Merchants. De overige rollen worden in dit document buiten beschouwing gelaten. Bijgaande figuur toont de vier partijen en hun onderlinge relaties.

Open

 

Op https://www.ideal.nl/demo is een demo van een iDEAL betaling te vinden. Een typische iDEAL transactie omvat (request-/response-) XML-berichtenuitwisseling en browser-redirects die in een bepaalde volgorde zorgen voor het initiëren en het verwerken van een transactie, waarbij alle betrokken partijen geïnformeerd raken over de status van de transactie. De verschillende stappen zijn schematisch weergegeven in onderstaande figuur.

Er zijn drie request/response paren (ook wel protocollen genoemd) die deel uitmaken van een iDEAL transactie: het Directoryprotocol, het Betaalprotocol en het Navraagprotocol.

• Middels het Directoryprotocol stuurt de Merchant een DirectoryRequest naar de Acquirer. Het DirectoryRequest is een verzoek, in XML formaat, van de Merchant aan de Acquirer om de lijst met aangesloten Consumentbanken (Issuers) op te leveren. De Acquirer levert deze lijst door middel van de DirectoryResponse. De banken die de Merchant in de DirectoryResponse ontvangt toont hij aan de Consument. Deze kiest uit de lijst de bank waar hij bankiert. Het Directoryprotocol wordt in meer detail beschreven in hoofdstuk 4.

• Middels het Betaalprotocol stuurt de Merchant een TransactionRequest naar de Acquirer waarin onder andere de gekozen Issuer, het bedrag, een ordernummer en andere transactiedetails worden doorgegeven. Dit bericht bevat ook de merchantReturnURL waarheen de Consument na het afronden van de betaling wordt terug geleid om weer terug te keren op de website van de Merchant. De Acquirer stuurt op zijn beurt een bericht naar de gekozen Issuer. De Issuer antwoordt met een bericht wat onder andere de IssuerAuthenticationURL bevat. De Acquirer geeft deze IssuerAuthenticationURL samen met een uniek iDEAL transactieID via de TransactionResponse terug aan de Merchant. De Merchant dient de Consument nu door te sturen (Engels: "redirect") naar de IssuerAuthenticationURL. Dit is de pagina van het internetbankier-systeem van de Issuer waar de transactiegegevens al vooringevuld zijn. De Consument keurt de betaling goed en ontvangt van de Issuer een bevestiging. Daarna stuurt de Issuer de Consument terug naar de website van de webwinkelier via de merchantReturnURL. Het Betaalprotocol en de 2 redirects worden uitgebreider behandeld in hoofdstuk 5.

• De Merchant initieert tot slot het Navraagprotocol door een StatusRequest te sturen naar de Acquirer. De Acquirer vraagt de status van de transactie, indien nodig, na bij de betreffende Issuer en retourneert deze status aan de Merchant. Als de gehele transactie goed is verlopen ontvangt de Merchant hiermee het bewijs dat de betaling is voldaan. In hoofdstuk 6 is meer informatie te vinden over het Navraagprotocol. In plaats van een reguliere response op bovengenoemde requests kan er ook een ErrorResponse teruggegeven worden als er iets fout is met een request of als er tijdens de afhandeling ervan iets fout gaat. De ErrorResponse wordt behandeld in hoofdstuk 7.

Open

Het volgende hoofdstuk beschrijft het algemene formaat van iDEAL berichten. In de daaropvolgende hoofdstukken wordt elk van de drie protocollen meer in detail beschreven.

3. Berichtformaat 

3.1 Algemeen

Dit hoofdstuk beschrijft de algehele structuur van de berichten van het Directory, Betaal- en Navraagprotocol. De komende hoofdstukken gaan nader in op de velden die binnen het XML bericht verstuurd worden voor elk van de protocollen.

3.2 Header formaat

De volgende HTTP header wordt gebruikt voor alle berichten:

• Alle berichten moeten voldoen aan de HTTP 1.1 standaard. Deze is gedefinieerd in RFC 2616 van W3C. Zie http://www.w3.org/Protocols/rfc2616/rfc2616.html voor meer informatie.

• Een XML request bericht moet worden verstuurd via HTTP POST als body van het bericht.

• Een XML response bericht moet worden verstuurd als body van een http 200 OK bericht.

De volgende XML header wordt gebruikt voor alle berichten:

3.3 XML Namespace declaratie

In iDEAL berichten kan de declaratie van XML namespaces op alle manieren worden gedaan die zijn beschreven in de XML standaard (default namespace declaratie of namespace kwalificaties / prefixes). De meeste voorbeeldberichten in dit document gebruiken de default namespace declaratie methode. Ook wordt een voorbeeld gegeven van een bericht met namespace prefixes. Beide typen berichten zijn correct en moeten geaccepteerd worden.

3.4 Gebruik van lege velden

In iDEAL berichten is een XML tag voor een optioneel of conditioneel veld:

• aanwezig (in dat geval moet de tag gevuld zijn met een geldige waarde)

• of geheel afwezig.

XML tags zonder inhoud zijn niet toegestaan en zullen resulteren in een foutbericht.

3.5 Merchant informatie geregistreerd bij de Acquirer

Naast de transactie-informatie die de Merchant verstuurt als onderdeel van de iDEAL berichten zoals beschreven in de volgende hoofdstukken, voegt de Acquirer ook informatie toe aan de iDEAL berichten uit de eigen administratie. Sommige van deze informatie moet worden geregistreerd door een Merchant bij de Acquirer voordat de Merchant kan beginnen met het inzenden van iDEAL transacties. De relevante iDEAL informatie wordt hieronder beschreven:

^{Merchant informatie geregistreerd bij de Acquirer.}

4. Directoryprotocol 

4.1 Algemeen

Het Directoryprotocol heeft als doel de Merchant de actuele lijst met aangesloten Issuers te laten ophalen bij zijn Acquirer, zodat deze kan worden getoond aan de Consument. Het Directoryprotocol zorgt ervoor dat veranderingen van de Issuerlijst automatisch in de keuzelijsten van alle Merchants te zien zijn.

Het is niet toegestaan het Directoryprotocol voor elke transactie uit te voeren. Aangezien de lijst met Issuers slechts sporadisch wijzigt is het voldoende eenmaal per dag de lijst op te halen en op basis van de directoryDateTimestamp te bepalen of de lijst gewijzigd is. De lijst dient, indien deze is gewijzigd, opgeslagen te worden en voor alle volgende transacties opnieuw gebruikt te worden. Acquirers informeren normaliter alle Merchants (bijv. via e-mail) over wijzigingen in de Issuerlijst. Het Directoryprotocol moet minstens eenmaal per maand uitgevoerd worden.

Het Directoryprotocol bestaat (zoals ook het Betaalprotocol en Navraagprotocol) uit een HTTP POST request van de Merchant naar de Acquirer waarop een HTTP response wordt terugontvangen. Het DirectoryRequest wordt verstuurd naar de URL, die door de Acquirer voor dit doel aan de Merchant is verstrekt. Dit kan een andere URL zijn dan voor het TransactionRequest en StatusRequest, maar de Acquirer kan hier ook een en dezelfde URL voor gebruiken.

De Acquirer controleert de authenticiteit van het bericht van de Merchant door de meegestuurde handtekening te controleren. Hiervoor is het nodig dat de Acquirer beschikt over het gebruikte certificaat van de Merchant met daarin de publieke sleutel. De manier waarop de Merchant het publieke deel van het certificaat aan de Acquirer laat weten verschilt per bank. Zie hoofdstuk 8 voor meer informatie over authenticatie en beveiliging.

4.2 DirectoryRequest

Het DirectoryRequest bestaat uit een XML bericht dat via een HTTP POST request naar de Acquirer wordt verstuurd, zie hoofdstuk 3iDEAL Merchant Integratie Gids (NL)#3.voor meer informatie. De tabel hieronder toont de velden van het DirectoryRequest en hun formaat. Zie Legenda in 3.5

Velden van de DirectoryRequest

*SignedInfo, SignatureValue en KeyInfo zijn XML Signature data elementen die gedefinieerd zijn in de XML-Signature Syntax and Processing. De digitale handtekening wordt in meer detail beschreven in hoofdstuk 8. Het XML Digital Signature Schema is beschikbaar bij de W3C op het adres: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd#

Voorbeeld van bericht

4.3 DirectoryResponse

De Merchant ontvangt de DirectoryResponse als antwoord op de DirectoryRequest. Dit XML bericht bevat een lijst met namen van Issuers met hun bijbehorende IssuerID (BIC). Issuers zijn gegroepeerd per land. De banken in het voorkeursland van de Merchant mogen bovenaan in de Issuer selectielijst worden getoond, de overige banken worden getoond op alfabetische volgorde van landnaam en vervolgens van bank naam. De tabel hieronder toont alle velden die (1 of meer keren) voorkomen in de DirectoryResponse. Zie Legenda in 3.5

Velden van de DirectoryResponse

*SignedInfo, SignatureValue en KeyInfo zijn XML Signature data elementen die gedefinieerd zijn in de XML-Signature Syntax and Processing. De digitale handtekening wordt in meer detail beschreven in hoofdstuk 8. Het XML Digital Signature Schema is beschikbaar bij de W3C op het adres: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd#

Voorbeeld van bericht

4.4 Presentatie van de Issuerselectielijst

Om er voor te zorgen dat een iDEAL transactie voor de Consument altijd op dezelfde wijze verloopt, dienen alle Merchants de volgende presentatie aan te houden:

Indien de Merchant middels het iDEAL Notification System (Centraal Meldpunt voor iDEAL banken om onbeschikbaarheid te melden) of via vanuit de Acquiring bank ontvangen errormeldingen heeft vastgesteld dat een bepaalde Issuing bank niet beschikbaar is, kan de Merchant op zijn website een melding tonen aan de Consument dat de betreffende bank op dat moment niet beschikbaar is. Een dergelijke melding tonen is dus toegestaan; het uitgrijzen of tijdelijk verwijderen van de issuing bank uit de Issuerselectielijst is dat niet.

5. Betaalprotocol 

5.1 Algemeen

Het Betaalprotocol initieert het berichtenverkeer van de daadwerkelijke betaling via iDEAL. Nadat de Consument heeft gekozen voor iDEAL als betaalmethode en zijn bank heeft gekozen, stuurt de Merchant een TransactionRequest naar zijn Acquirer. Binnen de iDEAL standaard wordt dit bericht aangeduid als AcquirerTransactionRequest. De Acquirer beantwoordt het TransactionRequest met een TransactionResponse. Deze bevat onder andere de IssuerAuthenticationURL waarheen de browser van de Consument moet worden geleid om de Consument de betaling te laten autoriseren.

5.2 TransactionRequest

Het XML bericht dat de Merchant verstuurt naar de Acquirer om een betaling te initiëren bevat de velden die getoond worden in onderstaande tabel. Zie Legenda in 3.5

Velden van het TransactionRequest.

*SignedInfo, SignatureValue en KeyInfo zijn XML Signature data elementen die gedefinieerd zijn in de XML-Signature Syntax and Processing. De digitale handtekening wordt in meer detail beschreven in hoofdstuk 8. Het XML Digital Signature Schema is beschikbaar bij de W3C op het adres: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd#

Voorbeeld van bericht

5.3 TransactionResponse

De Acquirer reageert op het TransactionRequest, als alles goed gaat, met de TransactionResponse. In onderstaande tabel staan alle velden die voorkomen in de TransactionResponse. Zie Legenda in 3.5

Velden van het TransactionRequest.

*SignedInfo, SignatureValue en KeyInfo zijn XML Signature data elementen die gedefinieerd zijn in de XML-Signature Syntax and Processing. De digitale handtekening wordt in meer detail beschreven in hoofdstuk 8. Het XML Digital Signature Schema is beschikbaar bij de W3C op het adres: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd#

Voorbeeld van bericht

5.4 Foutsituaties tijdens uitvoeren van het Transactieprotocol

Bij de uitvoering van het iDEAL Transactieprotocol kan een aantal foutsituaties optreden. Deze kunnen te maken hebben met onbeschikbaarheid binnen uw webwinkel omgeving (Merchant), de Acquirer omgeving of de Issuer omgeving.
De volgende situaties kunnen zich voordoen:

• Het initiëren van de iDEAL betaling lukt niet.

• U ontvangt binnen de ingestelde time-out een error-response (bericht 'X') van uw Acquirer.

• U ontvangt geen response binnen de ingestelde time-out.

In alle bovenstaande gevallen kan het transactieprotocol niet succesvol worden uitgevoerd. De iDEAL betaling kan op dat moment dus niet plaatsvinden. U wordt in deze gevallen geadviseerd, behalve als u in de ErrorResponse een consumermessage heeft ontvangen, om een melding met de volgende strekking aan de Consument te tonen: 'Op dit moment is betalen met iDEAL helaas niet mogelijk. Probeer het op een later moment nog eens of gebruik een andere betaalmethode'.

5.5 Redirect naar internetbankier-omgeving (IssuerAuthenticationURL)

Na het ontvangen van de TransactionResponse dient de Merchant de Consument door te sturen (Engels: "redirect") naar de IssuerAuthenticationURL van de gekozen bank, zoals die in de TransactionResponse is ontvangen. Als de pagina is opgebouwd met behulp van HTML-frames dan zullen deze door de Issuer verwijderd worden ("frame-busting"). Na terugkomst op de website van de Merchant (middels de merchantReturnURL) zal de Merchant ervoor moeten zorgen dat de frames weer opgebouwd worden voor het tonen van de orderbevestiging.
Bij het doorsturen van de Consument naar de gekozen bank mag vanuit privacy overwegingen geen persoons- en bestelinformatie van de Consument meegestuurd worden in de HTTP referer header (die gegevens bevat over de webpagina waar de Consument vandaan komt).

5.6 Redirect naar Merchantomgeving (merchantReturnURL)

Nadat de Consument de interactie met de Issuer heeft doorlopen, biedt de Issuer hem een 'Doorgaan' knop aan die hem moet terugleiden naar de website van de webwinkelier, middels de merchantReturnURL die de Merchant heeft opgegeven in de TransactionRequest. Achter deze URL worden twee parameters als GET parameters meegegeven: de entranceCode (zie paragraaf 5.2), met als GET parameter naam "ec" en de transactionID (zie paragraaf 5.3), met als GET parameternaam "trxid". Het is ook mogelijk voor de Merchant om andere extra parameters toe te voegen.

Als de Merchant bijvoorbeeld als merchantReturnURL opgeeft:

"http://www.webwinkel.nl/betaalafhandeling?productsoort=elektronica"

kan de uiteindelijke URL er bijvoorbeeld uitzien als:

"http://www.webwinkel.nl/betaalafhandeling?productsoort=elektronica&trxid=0010123456789012&ec=4hd7TD9wRn76w" . 

Het veld entranceCode dient, zoals eerder beschreven in paragraaf 5.2, een unieke waarde te bevatten. Dit om "sniffing" van de berichtuitwisseling tegen te gaan. Kwaadwillenden zouden door het gebruik van steeds dezelfde entranceCode de gegevens uit de merchantReturnURL kunnen onderscheppen en hier misbruik van kunnen maken. Vandaar dat het gebruik van unieke waardes voor de entranceCode van groot belang is.

5.7 Foutsituaties tijdens het uitvoeren van de redirect naar de Issuer internetbankier-omgeving, het uitvoeren van de betaling en/of de redirect naar de Merchantomgeving

Bij het uitvoeren van de redirect naar de internetbankier-omgeving (Issuer), het uitvoeren van de betaling bij de Issuer en/of de redirect terug naar uw (Merchant)omgeving kunnen de volgende foutsituaties zich voordoen:

• De bankpagina is onbereikbaar, waardoor de Consument niet kan betalen, maar ook niet op de juiste manier kan worden terug geleid naar uw bevestigingspagina.

• De bankpagina is wel bereikbaar maar de Consument kan (na een eventuele betaling) niet op de juiste manier worden terug geleid naar uw bevestigingspagina.

In beide situaties kan de Consument (als gevolg van een storing) dus niet op de normale manier terugkeren naar uw bevestigingspagina. De Consument kan in dat geval bijvoorbeeld via de 'back' knop van zijn browser of door de URL in te tikken terugkomen op uw website. In deze situaties is het advies om bij het herkennen van de Consument (bijvoorbeeld doordat deze inlogt in de Merchantomgeving, of via de browser-sessie) de status van de betaling op te vragen en deze aan de Consument te melden.

Als de Consument wordt herkend en de status kan worden opgehaald maar nog op 'open' staat, adviseren wij om de volgende melding aan de Consument te tonen: We hebben van uw bank nog geen bevestiging van uw betaling ontvangen. Als u in uw Internetbankieren ziet dat uw betaling heeft plaatsgevonden, zullen wij na ontvangst van de betaling tot levering overgaan.

Als de Consument niet wordt herkend, dient uw systeem de status van de betaling na het verlopen van de expiration period op te vragen. Wij adviseren u daarnaast in dergelijke situaties de status van de betaling – zodra deze definitief is geworden - op een of meer van de onderstaande manieren aan de Consument te melden:

• Per e-mail.

• Op uw website, bijvoorbeeld in het account van de Consument of via de browsersessie van de Consument.

5.8 Vier scenario's voor het afronden van een iDEAL mobiel betaling

Er zijn vier scenario's mogelijk voor het afronden van een iDEAL mobiel betaling. De Merchant kan een mobiele web pagina of een mobiele app gebruiken om zijn/haar winkel te presenteren aan de Consument. De Issuer kan een mobiele web pagina of een Mobiel Bankieren App aanbieden aan de Consument om de iDEAL transactie af te ronden. 

^{Vier mogelijke scenario's voor de afronding van een iDEAL mobiel betaling.}

5.9 Verwerkingssnelheid en time-out van betalingsberichten

De verwerkingssnelheid van de systemen van de Issuer en de Acquirer heeft een directe invloed op de gebruikerservaring van de Consument. Daarom schrijft iDEAL een streeftijd en een time-out periode voor de transactie responseberichten voor. De voor een Merchant relevante streeftijd en time-out periode hebben betrekking op de communicatie met zijn iDEAL Acquirer:

^{Verwerkingssnelheid eisen (voor het 95ste percentiel)}

De streeftijd is de tijd (in seconden) waarbinnen normaal gesproken een TransactionResponse bericht ontvangen zou moeten zijn door de Merchant na verzending van een TransactionRequest. De time-out is de tijdsduur waarna de Merchant geen response meer mag verwachten (waarschijnlijk is er een fout opgetreden) en toepasselijke actie moet ondernemen (bijvoorbeeld het tonen van een toepasselijke foutmelding aan de Consument). 95^ste percentiel is een term uit de statistiek die aangeeft dat 95% van de transacties in een steekproef binnen de gestelde streeftijd moeten vallen.

5.10 Uitvoeren van betalingen

Een iDEAL Transactie Request die succesvol door de Consument wordt geauthentiseerd zal uiteindelijk resulteren in een betaling van de bankrekening van de Consument bij de Issuer naar de bankrekening van de Merchant. Dit wordt gedaan in de vorm van een SEPA Credit Transfer (SCT). Hieronder wordt een beschrijving gegeven van de informatie in deze overschrijvingsvorm en hoe deze gerelateerd is aan de informatie in de iDEAL berichten.

SEPA Credit Transfer

^{Transactiedetails van iDEAL betaling en hoe deze worden ingevuld in een SEPA Credit Transfer}

In betalingsveld 2.3, End to End Identification, is Transaction.statusDateTimestamp verplicht en wordt ingevuld in de lokale tijdzone van de Issuer (inclusief zomer/wintertijd) en het formaat van de Consument met een maximum van 16 posities (bijv. DD-MM-YYYY HH:MM). Optioneel kan dit worden gevolgd door een spatie en dan de Transaction.transactionID (welke ook een onderdeel vormt van het veld Remittance Information).

5.11 Printen of e-mailen van betalingsbevestiging

Na een succesvolle reguliere iDEAL betaling moet de Issuer de Consument altijd de optie geven om een betalingsbevestiging te printen. In een mobiele omgeving zal afdrukken echter vaak niet mogelijk zijn, daarom wordt deze eis uitgebreid met alternatieven zoals het via e-mail ontvangen van een bevestiging of het ontvangen van een bevestiging in de internetbankieromgeving.

6. Navraagprotocol 

6.1 Algemeen

Om na te gaan of een transactie is geslaagd, start de Merchant het Navraagprotocol door het versturen van een StatusRequest naar de Acquirer. Dit kan gestart worden bij terugkeer van de Consument op de website van de Merchant (na de redirect door de Issuer) of na bijvoorbeeld 5 of 10 minuten na het verlopen van de geldigheidsduur van de transactie (expiration period). Om onnodige belasting van systemen te voorkomen mogen statusverzoeken niet onnodig vaak worden gedaan, zie 6.5 voor meer details over wat is toegestaan.
Binnen de iDEAL standaarden wordt dit bericht aangeduid als het AcquirerStatusRequest.

6.2 StatusRequest

In onderstaande tabel worden alle velden opgesomd die deel uitmaken van het StatusRequest XML bericht. Zie Legenda in 3.5 

Velden van het StatusRequest

*SignedInfo, SignatureValue en KeyInfo zijn XML Signature data elementen die gedefinieerd zijn in de XML-Signature Syntax and Processing. De digitale handtekening wordt in meer detail beschreven in hoofdstuk 8. Het XML Digital Signature Schema is beschikbaar bij de W3C op het adres: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd#

Voorbeeld van bericht

6.3 StatusResponse

Het antwoord op het StatusRequest bevat de velden die zijn opgesomd in onderstaande tabel. Hierin wordt de status van de transactie (waarvan het transactionID is meegegeven in de StatusRequest) aan de Merchant bekend gemaakt. Als deze status "Success" is, worden een aantal extra velden met informatie over de Consument gevuld. Deze informatie kan gebruikt worden om, indien nodig (een deel van) het transactiebedrag terug te boeken naar de Consument. Zie Legenda in 3.5 

De velden die voorkomen in de StatusResponse

*SignedInfo, SignatureValue en KeyInfo zijn XML Signature data elementen die gedefinieerd zijn in de XML-Signature Syntax and Processing. De digitale handtekening wordt in meer detail beschreven in hoofdstuk 8. Het XML Digital Signature Schema is beschikbaar bij de W3C op het adres: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd#

Voorbeeld van bericht

6.4 Foutsituaties tijdens het uitvoeren van het Navraagprotocol

Bij het navragen van de iDEAL status middels het Navraagprotocol kunnen foutsituaties optreden waardoor de status van de betaling op dat moment niet door u kan worden opgehaald. De eindstatus van de transactie kan op dat moment dus niet aan de Consument worden getoond.
Tekstvoorstel voor gebruik door u als er geen status opgehaald kan worden: We hebben van uw bank nog geen bevestiging ontvangen. Als u in uw Internetbankieren ziet dat uw betaling heeft plaatsgevonden, zullen wij na ontvangst van de betaling tot levering overgaan.
Naast deze melding adviseren wij u om aan uw klant aan te geven hoe hij over de betaalstatus geïnformeerd zal worden zodra deze bekend is, dan wel waar hij deze informatie (online) terug kan vinden.
U kunt vanaf dat moment conform de richtlijnen de status via uw Acquirer proberen op te halen. Zodra een definitieve status is ontvangen, kunt u de status van de betaling bijvoorbeeld op de volgende manieren aan de Consument melden:

• Per e-mail.

• Op uw website, bijvoorbeeld in het account van de Consument of via de browsersessie van de Consument.

6.5 Haalplicht

De Merchant dient een StatusRequest uit te voeren wanneer de Consument terecht komt op de pagina waarnaar hij is terug geleid door de Issuer (de merchantReturnURL uit het TransactionRequest). Het kan echter zo zijn dat de Consument zijn browserwindow sluit voordat hij terugkeert op de merchantReturnURL (zelfs als hij/zij de betaling heeft geauthenticeerd). Merchants moeten ook in dat geval een StatusRequest voor de transactie uitvoeren. Er geldt een zogenaamde "haalplicht" t.a.v. het resultaat van de transactie. Aan deze haalplicht kan voldaan worden door voor elke transactie het StatusRequest uit te voeren als:

• de Consument middels de MerchantReturnURL terugkeert bij de Merchant

• meer dan 3 minuten zijn verstreken na het verkrijgen van de TransationResponse en er nog geen definitieve status verkregen is

• de expiration period (opgegeven in de TransactionRequest) is verlopen en er nog geen definitieve status verkregen is.

Indien het teruggegeven resultaat van een transactie "Open" is, dient de Merchant na enige tijd opnieuw een StatusRequest te doen voor deze transactie. Alle andere statussen (Cancelled, Expired, Success en Failure) zijn eind-statussen en zullen nooit meer veranderen, het is dan ook niet nodig (en niet toegestaan) opnieuw een StatusRequest uit te voeren. Ter voorkoming van onnodige belasting van de systemen van Acquirers en Issuers dienen Merchants geen onnodige StatusRequests te versturen. 

De volgende situaties mogen nooit voorkomen:

• Status vaker dan 5 maal per transactie navragen voordat de expiration period is verlopen;

• Herhaalde statusnavragen met een tijdsinterval van minder dan 60 seconden;

De volgende situaties mogen niet voorkomen nadat de expiration period is verstreken:

• Herhaalde statusnavragen met een tijdsinterval van minder dan 60 minuten;

• Meer dan 5 keer op een dag de status van één transactie opvragen;

• Statusnavraag voor transacties waarvan de timestamp meer dan 7 dagen oud is;

• Status vaker dan één maal navragen nadat de eindstatus is bereikt;

• Stoppen met het opvragen van de status van een transactie voordat de eindstatus is bereikt of tot de timestamp meer dan 7 dagen oud is.

Normaal gesproken zou vrij kort na het verstrijken van de expiration period één van de eind-statussen teruggegeven moeten worden. Als het teruggegeven resultaat "Open" enige tijd na de expiration period nog steeds wordt teruggegeven is er sprake van een storing. Als deze storing niet binnen 24 uur is opgelost neem dan contact op met de Acquirer in plaats van StatusRequests te blijven versturen.
Indien de eindstatus "Success" is, kan de Merchant m.b.v. de bewaarde ordergegevens overgaan tot levering van het bestelde product. Als de klant op een niet reguliere wijze (bijvoorbeeld met de 'Terug' knop van de browser), terugkomt op de website van de Merchant en opnieuw ervoor kiest om met iDEAL te betalen, dient de Merchant hiervoor een nieuw iDEAL transactieverzoek in te sturen, nadat hij eerst geprobeerd heeft om een eindstatus van de eerder ingestuurde iDEAL betaling op te vragen.

6.6 Verwerkingssnelheid en time-out van statusberichten

De verwerkingssnelheid van de systemen van de Issuer en de Acquirer heeft een directe invloed op de gebruikerservaring van de Consument. Daarom schrijft iDEAL een streeftijd en een time-out periode voor de status responseberichten voor. De voor een Merchant relevante streeftijd en time-out periode hebben betrekking op de communicatie met zijn iDEAL Acquirer:

^{Verwerkingssnelheid eisen (voor het 95ste percentiel)}

De streeftijd is de tijd (in seconden) waarbinnen normaalgesproken een StatusResponse bericht ontvangen zou moeten zijn door de Merchant na verzending van een StatusRequest. De time-out is de tijdsduur waarna de Merchant geen response meer mag verwachten (waarschijnlijk is er een fout opgetreden) en toepasselijke actie moet ondernemen (bijvoorbeeld het tonen van een toepasselijke foutmelding aan de Consument). 95^ste percentiel is een term uit de statistiek die aangeeft dat 95% van de transacties in een steekproef binnen de gestelde streeftijd moeten vallen.

7. Foutafhandeling 

7.1 Algemeen

Als er iets fout gaat bij de verwerking van een DirectoryRequest, TransactionRequest of StatusRequest, bijvoorbeeld omdat het request een foutieve waarde bevat, wordt er geen normale response teruggegeven. In plaats daarvan komt er een ErrorResponse bericht terug. Deze ziet er voor alle drie de request typen hetzelfde uit.

7.2 ErrorResponse

In plaats van een normale response (DirectoryResponse, TransactionResponse of StatusResponse) zal de Acquirer een ErrorResponse terugsturen als er met het request die door de Merchant werd verstuurd bij ontvangst of bij de verwerking van de inhoud daarvan iets fout gaat. In onderstaande tabel staan de velden opgesomd die voorkomen in een ErrorResponse. Zie Legenda in 3.5

De velden in de ErrorResponse

*SignedInfo, SignatureValue en KeyInfo zijn XML Signature data elementen die gedefinieerd zijn in de XML-Signature Syntax and Processing. De digitale handtekening wordt in meer detail beschreven in hoofdstuk 8. Het XML Digital Signature Schema is beschikbaar bij de W3C op het adres: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd#

Voorbeeld van bericht

De consumerMessage is een bericht dat bedoeld is om aan Consumenten getoond te worden als er een fout optreedt. Het bevat één van de volgende teksten:

• "Betalen met iDEAL is nu niet mogelijk. Probeer het later nogmaals of betaal op een andere manier." ConsumerMessage bevat deze tekst als er iets misgaat in het Betaalprotocol.

• "Het resultaat van uw betaling is nog niet bij ons bekend. U kunt desgewenst uw betaling controleren in uw internetbankieren." ConsumerMessage bevat deze tekst als er tijdens het Navraagprotocol iets mis gaat.

• "De geselecteerde iDEAL bank is momenteel niet beschikbaar i.v.m. onderhoud tot naar verwachting datum en tijd uit Notificatiesysteem. Probeer het later nogmaals of betaal op een andere manier."ConsumerMessage bevat deze tekst als een Issuer niet beschikbaar is vanwege gepland onderhoud.

• "De geselecteerde iDEAL bank is momenteel niet beschikbaar. Probeer het later nogmaals of betaal op een andere manier." ConsumerMessage bevat deze tekst als een Issuer onverwacht onbeschikbaar is.

Merchants dienen altijd de door de Acquirer aangeleverde gestandaardiseerde consumerMessage te tonen aan hun klanten.
De overige velden uit de ErrorResponse dienen gebruikte te worden voor lokale foutopsporing. Appendix C geeft een overzicht van mogelijke foutcodes voor de diverse berichten en de bijbehorende tekst van het errorDetail veld.

7.3 Onbeschikbaarheid

Het kan zijn dat één van de Issuers tijdelijk niet beschikbaar is. Transacties voor die Issuer zullen dan een ErrorResponse opleveren (zie boven). Nadat een Acquirer heeft vastgesteld dat er sprake is van een onbeschikbaarheid zal hij dit doorgeven aan de betreffende Issuer. Een Merchant heeft dus nooit rechtstreeks contact met een Issuer.
Het kan voorkomen dat de Acquirer zelf tijdelijk niet beschikbaar is. In dit geval kunnen er geen iDEAL transacties worden verwerkt, tenzij de Merchant meer dan één Acquirer heeft, en levert ieder bericht een ErrorResponse op van de Acquirer.
Ook kan het voorkomen dat uw bevestigingspagina niet goed functioneert. In dit geval adviseren wij u een nette foutmelding te tonen aan de Consument.
Wij adviseren u daarna de status van de betaling op een of meer van de onderstaande manieren aan de Consument te melden:

• Per e-mail.

• Op uw website, in het account van de Consument.

• Op uw website, als onderdeel van de sessie-informatie van de bestelling.

8. Beveiliging en certificaten 

8.1 Algemene principes van certificaten

Bij asymmetrische encryptie wordt gebruik gemaakt van 2 sleutels: een publieke en een private sleutel. De publieke sleutel is gekoppeld aan een certificaat en mag aan iedereen bekend worden gemaakt, de private sleutel moet door de eigenaar strikt geheim worden gehouden. Door bijzondere wiskundige eigenschappen van het private deel en het publieke deel van een certificaat kan een stuk tekst dat versleuteld is met de publieke sleutel ontsleuteld worden met de private sleutel en andersom. Het is niet mogelijk een tekst te ontsleutelen met dezelfde sleutel als waarmee deze versleuteld is.
Deze bijzondere eigenschappen maken 2 toepassingen van certificaten mogelijk:

1. Versleutelen van een bericht. Door een bericht te versleutelen met de publieke sleutel van de ontvanger is de informatie alleen te lezen door de ontvanger (die de private sleutel, die nodig is om te ontsleutelen, als enige kent).

2. Digitaal tekenen van een bericht. Door (de hash van) een bericht te versleutelen met de private sleutel van de verzender kan de ontvanger (door een succesvolle ontsleuteling met de publieke sleutel van de verzender) vaststellen dat het bericht daadwerkelijk van de verzender komt (authenticiteit) en dat de inhoud van het bericht niet door derden is aangepast (integriteit).

De binnen iDEAL gebruikte enkelzijdige Transport Layer Security (TLS) verbinding tussen Merchant en Acquirer is gebaseerd op de eerste toepassing. Deze TLS verbinding gebruikt 128 bits encryptie waarbij de Acquirer een server-certificaat gebruikt. Het is belangrijk dat u zorgt voor een actuele TLS implementatie, waarin u gebruik maakt van de laatste veiligheidspatches (in ieder geval dient TLS versie 1.2 of hoger te worden ondersteund). Het niet regelmatig updaten van uw TLS implementatie kan leiden tot het niet meer kunnen insturen van iDEAL betalingen. iDEAL legt geen eisen op aan de communicatie tussen Consument en Merchant. Dus deze kan al dan niet via TLS verlopen. Merchants worden echter aangeraden om altijd TLS te gebruiken voor de betaalpagina's van hun website. Binnen iDEAL wordt ook gebruik gemaakt van de tweede toepassing, het digitaal tekenen van een bericht om de authenticiteit, integriteit en onweerlegbaarheid te waarborgen van alle berichten behalve de redirects. Doordat bijvoorbeeld de StatusResponse getekend wordt door de Acquirer kan de Merchant de betaalbevestiging op echtheid controleren.

8.2 Digitaal tekenen van iDEAL berichten

De Merchant tekent alle berichten die hij naar de Acquirer stuurt (DirectoryRequest, TransactionRequest en StatusRequest). Het ondertekenen van berichten gebeurt volgens de "XML Signature Syntax and Processing ( http://www.w3.org/TR/xmldsig-core/, met de volgende instellingen en restricties:

1. Het volledige XML bericht moet worden getekend. XML Signature referentie naar de signed info URL wordt leeg gelaten, zie de voorbeeldberichten in iDEAL Merchant Integratie Gids (NL)#Appendix B

2. Om de digest voor het volledige bericht te kunnen genereren moet het inclusive canonicalisatie algoritme worden toegepast. Deze manier van canonicalisatie van het volledige bericht wordt niet (overal) expliciet in de iDEAL XML berichten vermeld. Dit is daarom ook niet opgenomen in de voorbeeldberichten in dit document. In de door Merchants aangeleverde berichten hoeft deze transform daarom ook niet expliciet te worden aangegeven.

3. Om de signature waarde te kunnen genereren moet het exclusive canonicalisatie algoritme worden toegepast.

4. De syntax voor een "enveloped signature" moet gebruikt worden. Voor dit doel moet de handtekening zelf uit het XML bericht worden verwijderd volgens het standaard transformatieproces.

5. Voor hashing moet het SHA256 algoritme worden gebruikt.

6. Voor digitale handtekening doeleinden moet het RSAWithSHA256 algoritme gebruikt worden. RSA sleutels moeten 2.048 bits lang zijn.

7. Naar de publieke sleutel moet gerefereerd worden met een fingerprint van een X.509 certificaat. De fingerprint wordt berekend op basis van de volgende formule: HEX(SHA-1(DER certificate)). Zie voorbeeldberichten in Appendix B.

In het algemeen hoeft een Merchant geen diepgaande kennis van RSA te hebben omdat er voor de meeste (web)programmeertalen libraries bestaan die XML Digital Signature functies implementeren. Het wordt sterk aanbevolen hiervan gebruik te maken. Standaard functionaliteit voor het aanmaken en verifiëren van RSAWithSHA256 digitale handtekeningen is voor de veelgebruikte softwareplatformen in elk geval beschikbaar vanaf de volgende versies: PHP versie 5.3.0, Microsoft .NET versie 3.5 sp1 en Java 1.6 u18. Deze functionaliteit is mogelijkerwijs ook beschikbaar in eerdere versies van genoemde platformen en voor andere platformen (Python, Ruby en andere). Voor het aanmaken van een publieke en private sleutel zie paragraaf 8.4.

8.3 Authenticatie van iDEAL berichten

Om zeker te zijn van de status van een transactie moet een Merchant de handtekening van de Acquirer in de Response berichten controleren.
Om de handtekening in het SignatureValue veld te controleren, wordt aangeraden gebruik te maken van de standaard XML Digital Signature libraries die hiervoor beschikbaar zijn in de meeste (web)programmeertalen.

8.4 Maken van een sleutelpaar

Als u gebruik wilt maken van een zogenaamd "self signed certificate" leest u in deze paragraaf hoe u dit certificaat kunt maken. U kunt ook een certificaat inkopen bij een daarin gespecialiseerde partij (Certificate Authority), zie hieronder.
Doorloop de volgende stappen om een publieke en geheime sleutel aan te maken:

1. Download de 'OpenSSL Library' van www.openssl.org. Meer informatie over de te gebruiken 'certificate generating utility' vindt u hier: www.openssl.org/docs/apps/req.html. Het is ook mogelijk om met behulp van andere software een sleutelpaar te creëren, raadpleeg in dat geval de handleiding van de gebruikte software. Zorg er voor dat u altijd een actuele versie heeft geïmplementeerd om zo voldoende beveiligd te zijn.

2. Genereer een 'RSA private key' met het volgende commando (gebruik een zelfgekozen wachtwoord voor het veld [privateKeyPass] ):  openssl genrsa –aes128 –out priv.pem –passout pass:[privateKeyPass] 2048

3. Genereer een certificaat op basis van de 'RSA private key' (gebruik hetzelfde wachtwoord voor het veld [privateKeyPass]): openssl req –x509 –sha256 –new –key priv.pem –passin pass:[privateKeyPass] -days 1825 –out cert.cer

   Deze openssl instructie genereert een certificaat in X509 formaat, met een geldigheid van 5 jaar (1825 dagen), de maximumduur toegestaan binnen iDEAL.

4. Het bestand priv.pem bevat de private key, het bestand cert.cer bevat het certificaat met de publieke sleutel. Het bestand priv.pem moet de Merchant dus zelf houden en wordt gebruikt in de RSA versleuteling. Het cert.cer bestand moet beschikbaar worden gesteld aan de Acquirer. Hoe dit moet verschilt per Acquirer.

Een certificaat aanschaffen bij een Certificate Authority

Als een certificaat gekocht wordt van een Certificate Authority (CA), in plaats van een self-signed certificaat te gebruiken, is het volgende van belang: Het certificaat dat de CA gebruikt (en de rest van de certificate chain) moet ten minste even veilig zijn als het certificaat van de Merchant.
CA-certificaten die worden gebruikt om elektronische handtekeningencertificaten te ondertekenen moeten dus ten minste SHA-256 als hashing algoritme gebruiken en RSA sleutels van 2.048 bits.
Certificaten voor ondertekening mogen bovendien maximaal 5 jaar geldig zijn.

9. Presentatie

9.1 Algemeen

Ten aanzien van de presentatie van iDEAL op de site van de Merchant geldt een aantal eisen. Het voornaamste doel van deze eisen is het creëren van een uniforme gebruikerservaring voor Consumenten, ongeacht op welke website ze met iDEAL betalen. De verschillende eisen worden in de volgende paragrafen genoemd en toegelicht.

9.2 Betaalmethode

Een Merchant die iDEAL als betaalmethode accepteert, dient de iDEAL betaalmethode op te nemen in zijn lijst met alle aangeboden betaalmethoden, op die plaats in zijn orderproces waar dit gebruikelijk is.De iDEAL betaalmethode dient op een dusdanige manier in de lijst met aangeboden betaalmethoden te worden opgenomen, dat zij minimaal gelijke aandacht krijgt als andere betaalmethoden. Omdat iDEAL de meest gebruikte online betaalmethode is in Nederland wordt aangeraden om iDEAL als eerste betaalmethode te noemen.

9.3 Betaalknop

Het moet voor de Consument duidelijk herkenbaar zijn hoe en wanneer voor de iDEAL betaalmethode wordt gekozen. Dit wordt bewerkstelligd door een zogenaamde 'betaalknop' aan te bieden op de pagina waar uit betaalmethoden gekozen wordt. De toegestane afbeeldingen voor de iDEAL betaalknop zijn beschikbaar via het Merchantgedeelte van de website http://www.ideal.nl/ontvangen/logos-banners/. De richtlijnen en instructies voor het tonen van het iDEAL (QR) logo staan beschreven in het document 'Handleiding iDEAL-logo'.

Specifieke eisen iDEAL mobiel: betaalknop
In die gevallen waar het logo niet in de vereiste grootte kan worden weergegeven op een mobiel apparaat (bijvoorbeeld indien dit in strijd is met de eisen aan app iconen op het apparaat), mag de vereiste vrije ruimte van 15 pixels rondom het logo worden ingeperkt om tegemoet te komen aan de eisen van de mobiele omgeving.

9.4 Betaalflow

Na het selecteren van de iDEAL betaalknop, dient de Consument direct de iDEAL Issuerselectielijst te worden getoond, zonder dat hier nog allerlei tussenliggende schermen van de Merchant worden getoond (bijv. Consumenten inlog- en/of registratieschermen). Ook na de selectie van de betreffende Issuing bank door de Consument in de Issuerselectielijst dient deze direct te worden doorgeleid naar de iDEAL omgeving van de gekozen Issuing bank. Consumenten inlog en registratie bij de Merchant dienen dus te hebben plaatsgevonden voor de selectie van de iDEAL betaalmethode middels de iDEAL betaalknop.

9.5 Redirect naar Issuer

Een Merchant dient de redirect naar de Issuer binnen het browservenster te laten plaatsvinden waar de Consument de bank heeft geselecteerd, waarna de volledige pagina van de Merchant vervangen wordt door de volledige pagina van de gekozen Issuing bank. Het is dus niet toegestaan de redirect naar de Issuer in een nieuw browservenster te laten plaatsvinden. Het is wel toegestaan een nieuw venster, met zichtbare adresbalk, te openen vóór de Consument zijn bank selecteert.

9.6 Frames

Frames in de site van de Merchant worden toegestaan. Het scherm van de Issuing bank zal deze frames wegdrukken met een framebusting techniek zodat de Consument beter kan controleren dat er werkelijk bij zijn eigen bank betaald wordt met iDEAL. Na de redirect moet de Merchant het eigen scherm weer volledig laten opbouwen, voor het tonen van de bevestiging van de bestelling door de Merchant.

9.7 Nieuw venster

Het afhandelen van een iDEAL betaling in een nieuw browservenster is toegestaan, als de Merchant dit window laat verschijnen bij (of voorafgaand aan) de betaalmethodekeuze door de Consument. Het openen van een nieuw venster mag alleen op initiatief van de Consument gebeuren (geen pop-up). De gehele betaalflow dient in dit venster plaats te vinden tot en met de bevestiging van de bestelling door de Merchant. Dit nieuw geopende window dient ook voorzien te zijn van een zichtbare adresbalk zodat dit kan worden gebruikt bij het controleren dat er bij de eigen bank met iDEAL wordt betaald door verificatie van het adres (URL) en het SSL-certificaat. Gedurende de betaalflow moet het voor de Consument niet mogelijk zijn via het oorspronkelijke browserwindow van de Merchant nogmaals een betaling voor dezelfde order te starten.

Specifieke Requirements iDEAL mobiel: Nieuw venster of app

De iDEAL mobiel betaling kan een Consument omleiden naar een andere mobiele webpagina of app als onderdeel van de transactie. De Merchant moet ernaar streven om de Consument zoveel mogelijk binnen één browserpagina te houden maar de Merchant mag geen gebruik maken van een in-app browser via web view in zijn app (zie paragraaf 5.5). In die gevallen waar het switchen naar een andere app of venster noodzakelijk is (zoals de redirect naar de Issuer) moet de Consument hierover worden geïnformeerd om verwarring te voorkomen. Voorbeeld "U zal nu worden doorgestuurd naar de app of (mobiele) website van uw bank").

9.8 Issuerselectielijst

De Issuerlijst moet gepresenteerd worden op een voorgeschreven wijze. De details van deze voorgeschreven presentatie zijn te vinden in paragraaf 4.4.

9.9 iDEAL banners en logo

Merchants die op hun website een iDEAL banner of logo willen gebruiken om het gebruik van iDEAL te promoten kunnen de meest recente banners downloaden van http://www.ideal.nl/ontvangen/logos-banners/. Deze banners hoeven slechts één keer geïnstalleerd te worden, de gebruikte URL verwijst daarna altijd naar de laatste versie van de banner. Bij het gebruiken van een iDEAL banner op een mobiel apparaat (mobiele website of app) wordt geadviseerd om het logo zonder pay-off te gebruiken of de pay-off verdeeld over 2 regels om de breedte op het kleinere mobiele scherm te beperken.

9.10 Uitleg over iDEAL voor Consumenten

Merchants die op hun website aan Consumenten gerichte uitleg geven over iDEAL als betaalmethode worden geadviseerd daarvoor de volgende tekst te gebruiken:

Hoe werkt iDEAL?
Betalen met iDEAL doet u in een paar stappen:

• U bestelt een product

• Kies iDEAL als betaalmethode

• Selecteer de bank waar u uw bankzaken online regelt

• U komt direct in het bekende internetbankierprogramma van uw bank

• De relevante gegevens van uw aankoop zijn al ingevuld

• Op de voor u bekende manier keurt u de betaling goed

• U ontvangt een bevestiging van uw bank

• U keert terug naar de webwinkel. Bestelling en betaling geslaagd!

10. Tips verbeteren succeskans webshops 

10.1 iDEAL bankenlijst - houd hem up-to-date

• Wanneer u de iDEAL issuer selectielijst (bankenselectielijst) niet up-to-date houdt, loopt u de kans dat sommige van uw klanten niet met iDEAL kunnen betalen en handelt u bovendien in strijd met de iDEAL richtlijnen.

• Nieuwe iDEAL Issuers (dit zijn banken die iDEAL aan consumenten aanbieden) dienen zo snel mogelijk, maar uiterlijk binnen 1 maand nadat ze zijn toegevoegd aan iDEAL, getoond te worden in uw Issuer selectielijst.

• Het meest eenvoudig  is om het up-to-date houden van uw Issuer selectielijst volledig automatisch te laten verlopen. Dit kunt u doen u op één van de volgende manieren:

  • Maak wanneer mogelijk gebruik van een iDEAL landingspagina van uw bank of CPSP. De Issuer selectielijst die daar staat, wordt automatisch door deze partijen up to date gehouden;

  • Indien u een eigen iDEAL contract heeft bij een bank (de iDEAL betalingen komen dan rechtstreeks op uw bankrekening binnen), zorg er dan ervoor dat u het up-to-date houden van uw Issuer lijst koppelt aan het iDEAL directory protocol. Als u geen iDEAL contract heeft bij een bank, maar bij een CPSP dan kunt u vaak gebruik maken van een Issuer lijst API. Houdt uw Issuer selectielijst vervolgens up-to-date door het Directoryprotocol of de API daarbij automatisch dagelijks of wekelijks uit te voeren.

• Maakt u gebruik van een plug-in voor iDEAL (in bijv. Woocommerce of Magento)? Zorg er dan voor dat u regelmatig checkt dat u de laatste versie van de plug-in heeft geïmplementeerd.

• Kiest u ervoor om uw issuer selectielijst zelf handmatig aan te passen? Zorg er dan voor dat u de benodigde technische capaciteit in huis heeft om dit snel te doen. Deze aanpassing is meestal klein, maar vergt wel programmeerkennis. Neem contact op met uw softwareleverancier of CPSP als u vragen heeft over het handmatig aanpassen van uw iDEAL Issuer selectielijst.

• Zorg er bij een handmatige aanpassing ook voor dat u iDEAL Issuers verwijdert die iDEAL niet meer aanbieden (bijv. Friesland bank).

10.2 iDEAL transactiestatus – verifieer de eindstatus op tijd

• Zorg ervoor dat er in ieder geval twee triggers ingebouwd zijn waarmee de iDEAL transactie eindstatus wordt opgevraagd:

  1. Het terugkeren van de gebruiker naar uw merchant omgeving (via de MerchantReturnURL)

  2. Het verlopen van de iDEAL transactie expirationPeriod (deze is in te stellen in je transactie request, en staat wanneer niet meegegeven standaard op 30 min)

• Het niet hebben van een tweede trigger kan leiden tot mismatches tussen uw order system en de iDEAL eindstatus. Dit kan weer resulteren in situaties waarin uw klanten hebben betaald voor hun order via iDEAL, maar dat geen bevestiging van betaling in uw order system staat geadministreerd. Als gevolg hiervan wordt er niet uitgeleverd aan de consument, hoewel deze wel betaald heeft.

• Zorg er ook voor dat u de eindstatus van de iDEAL transactie ophaalt voordat uw order systeem de order automatisch laat verlopen.

• Zorg ervoor dat u niet levert enkel op basis van de terugkeer van de consument op uw merchant omgeving (via de MerchantreturnURL) maar uitsluitend na het ontvangen van de eindstatus “Success”.

• De formele eindstatus kan enkel worden geverifieerd op de volgende manieren:

  • Het navraagprotocol uit te voeren (StatusRequest te verzenden), waardoor u middels de StatusResponse de status van de iDEAL-transactie ontvangt, of

  • In het dashboard bij uw iDEAL contractpartij (indien van toepassing) de status van de iDEAL-transactie vast te stellen.

10.3. iDEAL mobiel vanuit uw app – foutief gebruik in-app-browsing via webview

• Wanneer u als merchant een app heeft, waarin u iDEAL als betaaloplossing aanbiedt, houdt dan specifiek rekening met de volgende vereisten rondom de redirect naar de Issuer:

1. De consument moet de URL en https “slotje” van de Issuer pagina’s te allen tijde kunnen controleren;

2. De browser, waarin de redirect naar de Issuer plaatsvindt, moet afgeschermd zijn voor de merchant (de merchant mag niet kunnen meekijken met consument);

3. De browser, waarin de redirect naar de Issuer plaatsvindt, moet toelaten dat bank-apps kunnen worden geopend (app URL schemes zoals “bank://ideal/12392”).

• Om aan bovenstaande vereisten te voldoen raden wij u aan om de IssuerAuthenticationURL altijd aan te bieden aan het operating system van het mobiele apparaat. Vervolgens zal de IssuerAuthenticationURL worden geopend in de browser van keuze van de consument of direct in de bank-app.

• Het is strikt verboden om custom made in-app browsers te gebruiken (via zgn. webview) voor de redirect naar de Issuer, omdat daarin niet aan alle bovenstaande vereisten wordt voldaan!

• Wanneer u er desondanks toch voor kiest een browser scherm binnen uw app te hanteren, dient u voor Apple iOS SafariViewController te gebruiken en voor Android Chrome Custom Tabs, om aan bovenstaande vereisten te voldoen.

Appendix A: Data catalogus 

De onderstaande tabellen bevatten alle elementen die voorkomen in de iDEAL berichten, voor zover relevant voor de Merchant, met informatie over hun formaat en toegestane waarden:

^{Data elementen in iDEAL berichten}

Karakterset

• In alle iDEAL berichten moet de Unicode karakterset gebruikt worden. Alleen de MES-2 deelverzameling moet ondersteund worden.

• Encoding die gebruikt moet worden is, zoals aangegeven in de HTTP en XML headers, UTF-8 (Unicode Transformation Format).

• Gebruik van een teken dat niet behoort tot de Unicode MES-2 karakterset leidt niet tot weigering van een batch of post, maar het teken kan naar een spatie, vraagteken of asterisk vertaald worden.

• Het Byte Order Mark (BOM) mag niet worden gebruikt. De UTF presentatie van het BOM is de byte serie 0xEF,0xBB,0xBFs.

Appendix B: Voorbeeldberichten 

De voorbeelden staan los van elkaar, zo is het voorbeeld van de DirectoryResponse niet per se een resultaat van het versturen van het voorbeeld DirectoryRequest. Verder zijn gebruikte waarden fictief, bijvoorbeeld de gebruikte IDs voor Acquirers en Issuers worden niet (allemaal) in de praktijk gebruikt.

APPENDIX C: Foutcodes 

Categorieën

De Error.errorCode is opgebouwd uit:

• een categorie (twee letters)

• een nummer (vier cijfers)

De volgende categorieën worden onderscheiden:

^{Foutcode categorieën}

Foutcodes

^Foutcodes

Het veld errorDetail bevat één van de onderstaande waarden, volgens de aanduiding in de kolom errorDetail in bovenstaande tabel. De cursief gedrukte woorden worden vervangen door actuele waarden, zoals aangegeven.

^errorDetail 

Cursief gedrukte woorden worden vervangen door de juiste waardes, zoals aangegeven.
Toelichting verwijzing 3: bij het maximum amount in het error detail worden door de Issuer enkel de voor de Issuer geldende maximum transactie- en daglimieten vermeld. Geen persoonlijke door de Consument ingestelde limieten.

De waarde van consumerMessage wordt gespecificeerd in ErrorResponse door de Acquirer gebaseerd op de criteria in de volgende tabel:

^{consumerMessage}

Cursief gedrukte woorden worden vervangen door de juiste waardes, zoals aangegeven.

APPENDIX D: XML berichten schema (XSD)