iDEAL Merchant Integratie Gids (NL) (wordt uitgefaseerd)

iDEAL Merchant Integratie Gids (NL) (wordt uitgefaseerd)

 

Version: 3.6
Oct 9, 2020 

 

  • Druk op het icoontje met drie puntjes rechtsboven

  • Kies "Export to PDF"

  • Wacht tot de PDF Export vervolledigd is

  • Druk op Download om de PDF te downloaden

EN/NL 

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 

1.1 Doelgroep

iDEAL Merchants zijn bedrijven (webwinkels) die iDEAL betalingen willen ontvangen en daartoe een contract hebben afgesloten met een bank. Dit document is bedoeld voor iDEAL Merchants die willen aansluiten op het iDEAL platform van de door hen gekozen Acquiring bank. Het behandelt het berichtenverkeer tussen Merchants en hun bank. Voor Merchants is het berichtenverkeer tussen Issuers en Merchant-banken (Acquirers) niet van belang. Dat deel van de iDEAL standaard wordt daarom in dit document niet behandeld.
Dit document is niet bank specifiek, dat wil zeggen dat alleen generieke iDEAL zaken in dit document worden behandeld. Voor informatie over ”non-standaard aansluitvormen en  (hulp)middelen” verwijzen wij u door naar de aanvullende documentatie van uw Acquiring bank.

1.2 Document opzet

In hoofdstuk 2 wordt een overzicht gegeven van de partijen die een rol spelen bij iDEAL en de verschillende berichten die tijdens een iDEAL transactie worden uitgewisseld. Hoofdstuk 3 gaat in op de algehele structuur van berichten die worden uitgewisseld. Hoofdstuk 4 beschrijft het Directoryprotocol, waarmee de lijst met Issuing banken binnen iDEAL wordt opgevraagd. In Hoofdstuk 5 wordt het Betaalprotocol in detail beschreven. Het Navraagprotocol, waarmee de daadwerkelijke status van een iDEAL transactie wordt opgevraagd, komt aan bod in hoofdstuk 6. Hoofdstuk 7 beschrijft welke fouten en uitzonderingen er kunnen optreden en hoe deze afgehandeld dienen te worden. Hoofdstuk 8 gaat nader in op de beveiliging van iDEAL berichten. Tot slot staan in hoofdstuk 9 een aantal zaken beschreven die betrekking hebben op de presentatie van iDEAL (huisstijl en logo) en in hoofdstuk 10 uitleg over best practices en uitleg over bekende implementatie valkuilen. 

1.3 Definities van internet en online bankieren

In dit document worden de termen 'internet bankieren' of 'online bankieren' gebruikt. Voor Consumenten banken die iDEAL mobiel implementeren zouden deze termen geïnterpreteerd moeten worden als 'internet bankieren' en/of 'mobiel bankieren'. Waar de termen 'internet' of 'online' gebruikt wordt, moet dit altijd gelezen worden als inclusief het mobiele kanaal. In geval het mobiele gebruik van iDEAL tot aanvullende vereisten (requirements) leidt, zullen deze specifiek benoemd worden in dit document.

1.4 Herzieningen

Versie

Omschrijving van versie

Datum gereed

Versie

Omschrijving van versie

Datum gereed

0.9

Versie die kan worden benoemd tot 1.0

16-2-2009

2.2.1

Herziene versie n.a.v. Engelse vertaling

30-6-2009

2.2.2

Toevoeging extra bepaling statusprotocol haalplicht

10-9-2009

2.2.3

  • Toevoeging passage uitgrijzen in Issuerlijst

  • Toevoeging passage verbeteren succeskans webshops

  • Toevoeging passage betaalflow

  • Aanpassing passage redirect naar Issuer

  • Toevoeging passage errorberichten

  • Toevoeging passage entrance codes

  • Toevoeging XSD schema Merchant-Acquirer

19-5-2010

3.3.0 definitief

Nieuwe versie met commentaar CAB verwerkt

07-03-2012

3.3.1 definitief

Nieuwe versie gebaseerd op iDEAL 3.3.1 Standaard

12-04-2012

3.3.1 correctie

Correctie doorgevoerd in URL's

12-06-2012

3.3.1 correctie oktober

Correctie doorgevoerd in OpenSSL syntax

22-10-2012

3.3.1 correctie november

Correcties m.b.t. gebruik Byte Order Mark

08-11-2012

3.3.1 correctie november II

Correctie m.b.t. gebruik van lege velden in XML

20-11-2012

3.3.1 correctie juli

  • Verduidelijking gebruik XMLdsig en RmtInfo

  • Toevoeging TransactionCreateDateTimestamp,

  • Tijdelijke bepalingen veldlengtes verwijderd

  • Aanscherping toegestane karakterset,

  • Verduidelijking gebruik canonicalisatie methode

  • Correctie SSL commando voor maken sleutelpaar

  • Verwijderen informatie over de NL overschrijving

  • Informatie over platformversies met ondersteuning voor RSAwithSHA256 digitale handtekeningen

03-07-2013

3.3.1 correctie januari 2014

  • Toevoeging afhandeling foutsituaties tijdens uitvoeren betaalprotocol en statusprotocol.

01-01-2014

3.3.1 correctie maart 2014

  • Mobiel addendum en iDEAL Mobile Quick Guide geïntegreerd in de MIG voor meer informatie over mobiele implementaties.

17-03-2014

3.3.1 correctie oktober 2014

  • Opname bepaling ten aanzien van redirect naar Issuer in paragraaf 5.5.

08-10-2014

3.3.1 toevoeging februari 2015

  • Wijziging opgenomen links naar iDEAL.nl website

  • Toelichting AP2910 error code

  • Toelichting gebruik Merchant Signing certificaten

15-02-2015

3.5

  • Algemene presentatie verbeteringen

  • Toevoeging trigger voor navraag protocol (3 minuten na TransactionResponse)

  • Veralgemenisering van specificaties presenteren Issuer Selectie lijst

  • Gebruik van Universal Links en Android App links voor Merchant Redirect iDEAL mobiel

  • Support voor TLS 1.1 of hoger verplicht

  • Toevoeging passage over veel voorkomende implementatie valkuilen

  • Inconsistentie in tonen consumermessage aangepast

  • Verwijdering van amount verificatie specificatie in StatusResponse

Q3 2017

3.6

  • Support voor TLS 1.2 of hoger verplicht

  • Note over unsafe karakters in MerchantReturnURL

  • Note toegevoegd aan 8.4 (root versus derived certificaat)

  • Fix Booking Entry Standards: Merchant.tradename van optioneel naar conditioneel

Q3 2020

 


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.

 

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.

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

Het stroomdiagram van een iDEAL mobiel transactie is vrijwel identiek aan de transactieflow in een reguliere iDEAL transactie. Het enige verschil is de automatische redirect naar het mobiele kanaal van de Issuer (op basis van de issuerAuthenticationURL). Bij Issuers die iDEAL in hun mobiel bankieren app ondersteunen wordt de consument of automatisch doorgeleid naar een mobiel bankieren app  of kan de Consument kiezen of hij wil betalen via de web browser of via de app van de bank. De Consument komt dan op een 'landing page'. Op deze pagina kan de Consument de keuze maken of hij de betaling via de (mobiele) website van de Issuer wil afhandelen of via de mobiele app van de issuer.


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:

Data-element

Verplicht

Toelichting

Data-element

Verplicht

Toelichting

Content-Type

Ja

Geeft aan hoe de verdere inhoud geïnterpreteerd moet worden. Bevat als waarde: text/xml; charset="UTF-8".

  • 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:

Data-element

Verplicht

Toelichting

Data-element

Verplicht

Toelichting

Version

Ja

De versie van XML volgens W3C: 1.0

Encoding

Ja

De karakter encoding gebruikt voor (de inhoud van) de XML: UTF-8



POST /nl/issuerInformation/getIssuerInformation.xml HTTP/1.1
Content-type: text/xml, charset="UTF-8"
Content-Length: 1201
Host: ideal.abnamro.nl

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:

Data-element

Merchant

Sub-element

Formaat

Omschrijving

legalName

AN..max70

De juridische naam van de Merchant zoals deze geregistreerd staat bij de Acquirer. Wordt gebruikt samen met Merchant.tradeName om de naam van de Merchant weer te geven aan de Consument (bijv. 'Merchant.legalName inzake Merchant.tradeName'). Ook gebruikt in combinatie met de Merchant.merchantIBAN voor de bankoverschrijving door de Issuer. Moet hetzelfde zijn als de naam behorend bij de bankrekening van de Merchant, zoals geregistreerd door de Acquirer.

tradeName

AN..max35

De handelsnaam van de Merchant, zoals geregistreerd bij de Acquirer in gevallen waar deze afwijkt van de legalName.

merchantIBAN

ANS..max34

De IBAN van de Merchant, zoals geregistreerd bij de Acquirer. (Deze is gekoppeld aan de Merchant.merchantID.)

merchantBIC

ANS..max11

De BIC van de bank waar de Merchant zijn bankrekening heeft

Merchant informatie geregistreerd bij de Acquirer.

Notatie

Betekenis

Notatie

Betekenis

AN

Het veld kan alfanumerieke waarden bevatten. Dit wordt gevolgd door een getal dat de lengte (of maximale lengte) van het veld aangeeft.

ANS

Het veld kan een beperkte verzameling alfanumerieke karakters (alleen letters en cijfers) bevatten. Dit wordt gevolgd door een getal dat de lengte (of maximale lengte) van het veld aangeeft.

N

Het betreft een numeriek veld. Dit wordt gevolgd door een getal dat de lengte (of maximale lengte) van het veld aangeeft.

PN

Het betreft een uitgevulde numerieke waarde. De inhoud wordt tot de maximumlengte aangevuld door het toevoegen van voorloopnullen.

CL

Duidt op een aantal specifiek toegestane waarden (enumeratie). Welke waarden zijn toegestaan wordt altijd bij het betreffende veld uitgelegd.

DT

Betekent een Datumtijdveld: met het formaat yyyy-MM-ddTHH:mm:ss.SSSZ. (ISO standaard 8601). De gebruikte tijd is de "universal time" UTC (voorheen GMT), zonder zomer/wintertijd. Bijvoorbeeld 2009-12-28T13:59:59.393Z

RDT

Duidt op een relatief datum/tijd veld (ISO standaard 8601). Bijvoorbeeld PT10M voor 10 minuten.

DEC(#1,#2)

Duidt op een decimale waarde met als maximaal totaal aantal cijfers #1 en als maximaal aantal decimalen #2. DEC(6,2) kan bijvoorbeeld 1234,56 zijn.

 


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

Naam

Omschrijving

Formaat

Naam

Omschrijving

Formaat

createDateTimestamp

Datum en tijd waarop het DirectoryRequest is gecreëerd.

DT

merchantID

Aansluitnummer / MerchantID zoals dit van de Acquirer ontvangen is. Indien het MerchantID uit minder dan 9 cijfers bestaat, worden voorloopnullen gebruikt.

PN..9

subID

Aansluit subnummer, door Acquirer verstrekt aan Merchant, als Merchant aangeeft hier gebruik van te willen maken. Een Merchant kan bij zijn Acquirer verzoeken om meerdere subID's te mogen gebruiken waardoor op rekeningafschriften, naast een vaste juridische naam, per sub ID een verschillende handelsnaam kan worden meegegeven. Tenzij anders afgesproken met de Acquirer dient de Merchant hier 0 (nul) in te vullen als standaard subID (indien geen subIDs worden gebruikt).

N..max6

SignedInfo

Bevat informatie over de digitale handtekening conform de W3C XMLdsig specificaties

 *

SignatureValue

Bevat de digitale handtekening conform de W3C XMLdsig specificaties

 *

KeyInfo

Bevat informatie (fingerprint) over het certificaat dat gebruikt wordt voor het genereren van de meegestuurde digitale handtekening, zodat de ontvanger de juiste public key kan gebruiken voor validatie van de handtekening conform de W3C XMLdsig specificaties

 *

*SignedInfoSignatureValue 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

<?xml version="1.0" encoding="UTF-8"?> <DirectoryReq xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1"> <createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp> <Merchant> <merchantID>100000001</merchantID> <subID>1</subID> </Merchant> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- Signature is placed here. See Signature section for specification--> </Signature> </DirectoryReq>

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

Naam

Omschrijving

Formaat

Naam

Omschrijving

Formaat

createDateTimestamp

Datum en tijd waarop het response bericht gecreëerd is.

DT

acquirerID

Uniek kenmerk van 4 cijfers van de Acquirer binnen iDEAL.

PN..4

directoryDateTimestamp

Tijd die aangeeft wanneer de Directory voor het laatst gewijzigd is door de Acquirer

DT

countryNames

Bevat de landnamen in de officiële talen van de betreffende landen, gescheiden door een "/" symbool (bijv. 'België/Belgique') Landnamen hoeven alleen getoond te worden in de lijst met Issuers als er banken van meer dan één land in de lijst staan. Als alle banken in de lijst uit hetzelfde land komen, hoeft de landnaam niet te worden getoond. Momenteel zijn er alleen Nederlandse Issuers aangesloten en hoeft de landnaam dus niet getoond te worden



issuerID

Bank Identificatie Code (BIC) van de iDEAL Issuer

ANS..max11

issuerName

De naam van de Issuer (zoals deze getoond moet worden aan de Consument in de Issuer lijst van de Merchant).

AN..max35

SignedInfo

Bevat informatie over de digitale handtekening conform de W3C XMLdsig specificaties

 *

SignatureValue

Bevat de digitale handtekening conform de W3C XMLdsig specificaties

 *

KeyInfo

Bevat informatie (fingerprint) over het certificaat dat gebruikt wordt voor het genereren van de meegestuurde digitale handtekening, zodat de ontvanger de juiste public key kan gebruiken voor validatie van de handtekening conform de W3C XMLdsig specificaties

 *

*SignedInfoSignatureValue 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

<?xml version="1.0" encoding="UTF-8"?> <DirectoryRes xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1"> <createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp> <Acquirer> <acquirerID>0001</acquirerID> </Acquirer> <Directory> <directoryDateTimestamp>2004-11-10T10:15:12.145Z</directoryDateTimestamp> <Country> <countryNames>Nederland</countryNames> <Issuer> <issuerID>ABNANL2AXXX</issuerID> <issuerName>ABN AMRO Bank</issuerName> </Issuer> <Issuer> <issuerID>INGBNL2AXXX</issuerID> <issuerName>ING</issuerName> </Issuer> <Issuer> <issuerID>RABONL2UXXX</issuerID> <issuerName>Rabobank</issuerName> </Issuer> </Country> </Directory> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- Signature is placed here. See Signature section for specification--> </Signature> </DirectoryRes>

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:

  • Alle Issuers in de DirectoryResponse (welke op zijn minst maandelijks dient te worden opgehaald) moeten worden getoond in een lijst (bijv. dropdown lijst of lijst met radio buttons) in alfabetische orde en exact zoals meegegeven in het DirectoryResponse bericht.

  • The lijst wordt voorafgegeaan door de instructie "Kies uw bank". In geval van een HTML <SELECT> toont het eerste element in de lijst deze instructie en is deze by default geselecteerd (om te voorkomen dat mogelijk per ongeluk een onjuiste bank wordt gekozen). 

  • Het is niet toegestaan voor de Merchant om Issuing banken (tijdelijk) uit de Issuerselectielijst te verwijderen of uit te grijzen. In geval van een nieuwe Issuer moet de Issuer lijst binnen een maand zijn aangepast (bij voorkeur eerder).

  • Het is aan te bevelen het HTML "value" veld van de items in de listbox in te stellen op de IssuerID (BIC) van de betreffende Issuer, omdat deze nodig is in vervolgberichten (TransactionRequest).

  • De Merchant mag een Issuer pre-selecteren, maar alleen als daarmee de gebruikservaring kan worden verbeterd (bijv. als de Consument eerder bij deze Merchant een iDEAL betaling heeft geïnitieerd met een specifieke Issuer). De Consument moet echter altijd de mogelijkheid worden geboden om de Issuer te wijzigen.

 

Voorbeeld van een correcte presentatie van de Issuerselectielijst

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.

Naam

Omschrijving

Formaat

Naam

Omschrijving

Formaat

createDateTimestamp

Datum en tijdstip waarop het TransactionRequest bericht is gecreëerd.

DT

issuerID

Bank Identificatie Code (BIC) van de iDEAL Issuer

ANS..max11

merchantID

Aansluitnummer / MerchantID zoals dit van de Acquirer ontvangen is. Indien het MerchantID uit minder dan 9 cijfers bestaat, worden voorloopnullen gebruikt.

PN..9

subID

Aansluit subnummer, door Acquirer verstrekt aan Merchant, als Merchant aangeeft hier gebruik van te willen maken. Een Merchant kan bij zijn Acquirer verzoeken om meerdere subID's te mogen gebruiken waardoor op rekeningafschriften, naast een vaste juridische naam, per sub ID een verschillende handelsnaam kan worden meegegeven. Tenzij anders afgesproken met de Acquirer dient de Merchant hier 0 (nul) in te vullen als standaard subID (indien geen subIDs worden gebruikt).

 N..max6

merchantReturnURL

URL van de Merchant waarheen de Consument na autoriseren van de transactie geredirect moet worden door de Issuer en die terugleidt naar de website van de Merchant. (Hoeft niet noodzakelijkerwijs te beginnen met http:// of https://).

Bijvoorbeeld: https://www.webwinkel.nl/betaalafhandeling

Deze URL’s mogen alleen URL-veilige karakters bevatten. Alle onveilige karakters (spatie “<>#%{}|\^~[]) ’) moeten correct worden geencodeerd. Deze ongecodeerde karakters in de ULR's worden wel succesvol gevalideerd maar kunnen in sommige gevallen verwerkingsissues in de Issuing back-end verzoorzaken, welke resulteren in fouten rondom redirects terug naar merchants.

AN..max512

purchaseID

Uniek kenmerk van de order/bestelling binnen het systeem van de Merchant. Verschijnt uiteindelijk op het betaalbewijs (rekeningafschrift/-overzicht) van de Consument en op het afschrift van de Merchant.

ANS..max35

amount

Het te betalen bedrag in euro (met punt (.) als decimaal-scheidingsteken).

DEC(12,2)

currency

Valuta waarin de betaling moet worden uitgevoerd, uitgedrukt in de drieletterige internationale munteenheid codering uit ISO 4217; Omdat iDEAL op dit moment alleen Eurobetalingen ondersteunt is de waarde van dit veld altijd "EUR"

ANS..3

expirationPeriod

Optional

De geldigheidsduur van het betaalverzoek gemeten vanaf ontvangst door de Issuer. De Consument dient de betaling te accorderen binnen deze tijd. Als dit niet gebeurt dan wordt de status van de transactie door de Issuer op "Expired" gezet. Waarde periode volgens ISO 8601: PnYnMnDTnHnMnS. Minimum waarde: PT1M of PT60S (1 minuut), maximum waarde: PT1H, PT60M of PT3600S (1 uur). Indien niet ingevuld dan stelt de Issuer de Transaction.expirationPeriod standaard op PT30M (een half uur). Omdat bijna alle succesvolle betalingen binnen 1 kwartier afgerond zijn, wordt geadviseerd om de geldigheidsduur niet langer in te stellen dan PT15M (een kwartier). Vanwege de minimale tijd die een Consument nodig heeft om een transactie te doorlopen wordt geadviseerd om de geldigheidsduur niet korter dan 3 minuten (PT180S of PT3M) in te stellen.

RDT

language

Door middel van dit veld kan de Consument bediend worden op de site van de Issuer in de taal naar keuze (of zoals deze geselecteerd is op de site van de webwinkel), indien de site van de Issuer dit ondersteunt. Codelijst conform ISO 639-1. (Nederlands = 'nl') Indien een niet bestaande of niet ondersteunde taal wordt opgegeven wordt de standaardtaal van de Issuer gebruikt. Geadviseerd wordt om alleen "nl" te gebruiken omdat andere talen niet door alle Issuers worden ondersteund.

CL AN..2

description

Omschrijving van het (de) bestelde product(-en) of dienst(en). Dit veld mag geen HTML tags of andere tekens bevatten die de opmaak van schermen waarop dit veld getoond wordt, kunnen verstoren. Om mogelijke problemen te voorkomen zullen veel iDEAL systemen een description veld dat HTML-tags of vergelijkbare code bevat, afkeuren.

AN..max35

entranceCode

De Transaction.entranceCode is een 'authenticatie sleutel' ten behoeve van continuering van de sessie tussen Merchant en Consument, zelfs als de bestaande sessie is beëindigd. De Merchant kan hiermee de Consument herkennen die hoort bij een (inmiddels afgeronde) transactie. De entranceCode moet iedere transactie afwijkend zijn. De Transaction.entranceCode wordt hiertoe meegestuurd in de HTTP(S) GET naar de Merchant als parameter achter de merchantReturnURL. De Transaction.entranceCode dient een minimale variatie van 1 miljoen te hebben. Deze code moet bestaan uit letters en/of cijfers (maximaal 40 posities). De Transaction.entranceCode wordt aangemaakt door de Merchant en doorgegeven aan de Issuer

ANS..max40

SignedInfo

Bevat informatie over de digitale handtekening conform de W3C XMLdsig specificaties

*

SignatureValue

Bevat de digitale handtekening conform de W3C XMLdsig specificaties

*

KeyInfo

Bevat informatie (fingerprint) over het certificaat dat gebruikt wordt voor het genereren van de meegestuurde digitale handtekening, zodat de ontvanger de juiste public key kan gebruiken voor validatie van de handtekening conform de W3C XMLdsig specificaties

*

*SignedInfoSignatureValue 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

<?xml version="1.0" encoding="UTF-8"?> <AcquirerTrxReq xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1"> <createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp> <Issuer> <issuerID>RABONL2UXXX</issuerID> </Issuer> <Merchant> <merchantID>100000001</merchantID> <subID>1</subID> <merchantReturnURL>https://www.ashop.eu/paymentHandling</merchantReturnURL> </Merchant> <Transaction> <purchaseID>iDEALaankoop21</purchaseID> <amount>59.99</amount> <currency>EUR</currency> <expirationPeriod>PT3M30S</expirationPeriod> <language>nl</language> <description>Documenten Suite</description> <entranceCode>4hd7TD9wRn76w6gGwGFDgdL7jEtb</entranceCode> </Transaction> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- Signature is placed here. See Signature section for specification--> </Signature> </AcquirerTrxReq>

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.

Naam

Omschrijving

Formaat

Naam

Omschrijving

Formaat

createDateTimestamp

Datum en tijdstip waarop het TransactionRequest bericht is gecreëerd.

DT

issuerID

Bank Identificatie Code (BIC) van de iDEAL Issuer

ANS..max11

merchantID

Aansluitnummer / MerchantID zoals dit van de Acquirer ontvangen is. Indien het MerchantID uit minder dan 9 cijfers bestaat, worden voorloopnullen gebruikt.

PN..9

subID

Aansluit subnummer, door Acquirer verstrekt aan Merchant, als Merchant aangeeft hier gebruik van te willen maken. Een Merchant kan bij zijn Acquirer verzoeken om meerdere subID's te mogen gebruiken waardoor op rekeningafschriften, naast een vaste juridische naam, per sub ID een verschillende handelsnaam kan worden meegegeven. Tenzij anders afgesproken met de Acquirer dient de Merchant hier 0 (nul) in te vullen als standaard subID (indien geen subIDs worden gebruikt).

 N..max6

merchantReturnURL

URL van de Merchant waarheen de Consument na autoriseren van de transactie geredirect moet worden door de Issuer en die terugleidt naar de website van de Merchant. (Hoeft niet noodzakelijkerwijs te beginnen met http:// of https://).

Bijvoorbeeld: https://www.webwinkel.nl/betaalafhandeling

Deze URL’s mogen alleen URL-veilige karakters bevatten. Alle onveilige karakters (spatie “<>#%{}|\^~[]) ’) moeten correct worden geencodeerd. Deze ongecodeerde karakters in de ULR's worden wel succesvol gevalideerd maar kunnen in sommige gevallen verwerkingsissues in de Issuing back-end verzoorzaken, welke resulteren in fouten rondom redirects terug naar merchants.

AN..max512

purchaseID

Uniek kenmerk van de order/bestelling binnen het systeem van de Merchant. Verschijnt uiteindelijk op het betaalbewijs (rekeningafschrift/-overzicht) van de Consument en op het afschrift van de Merchant.

ANS..max35

amount

Het te betalen bedrag in euro (met punt (.) als decimaal-scheidingsteken).

DEC(12,2)

currency

Valuta waarin de betaling moet worden uitgevoerd, uitgedrukt in de drieletterige internationale munteenheid codering uit ISO 4217; Omdat iDEAL op dit moment alleen Eurobetalingen ondersteunt is de waarde van dit veld altijd "EUR"

ANS..3

expirationPeriod

Optional

De geldigheidsduur van het betaalverzoek gemeten vanaf ontvangst door de Issuer. De Consument dient de betaling te accorderen binnen deze tijd. Als dit niet gebeurt dan wordt de status van de transactie door de Issuer op "Expired" gezet. Waarde periode volgens ISO 8601: PnYnMnDTnHnMnS. Minimum waarde: PT1M of PT60S (1 minuut), maximum waarde: PT1H, PT60M of PT3600S (1 uur). Indien niet ingevuld dan stelt de Issuer de Transaction.expirationPeriod standaard op PT30M (een half uur). Omdat bijna alle succesvolle betalingen binnen 1 kwartier afgerond zijn, wordt geadviseerd om de geldigheidsduur niet langer in te stellen dan PT15M (een kwartier). Vanwege de minimale tijd die een Consument nodig heeft om een transactie te doorlopen wordt geadviseerd om de geldigheidsduur niet korter dan 3 minuten (PT180S of PT3M) in te stellen.

RDT

language

Door middel van dit veld kan de Consument bediend worden op de site van de Issuer in de taal naar keuze (of zoals deze geselecteerd is op de site van de webwinkel), indien de site van de Issuer dit ondersteunt. Codelijst conform ISO 639-1. (Nederlands = 'nl') Indien een niet bestaande of niet ondersteunde taal wordt opgegeven wordt de standaardtaal van de Issuer gebruikt. Geadviseerd wordt om alleen "nl" te gebruiken omdat andere talen niet door alle Issuers worden ondersteund.

CL AN..2

description

Omschrijving van het (de) bestelde product(-en) of dienst(en). Dit veld mag geen HTML tags of andere tekens bevatten die de opmaak van schermen waarop dit veld getoond wordt, kunnen verstoren. Om mogelijke problemen te voorkomen zullen veel iDEAL systemen een description veld dat HTML-tags of vergelijkbare code bevat, afkeuren.

AN..max35

entranceCode

De Transaction.entranceCode is een 'authenticatie sleutel' ten behoeve van continuering van de sessie tussen Merchant en Consument, zelfs als de bestaande sessie is beëindigd. De Merchant kan hiermee de Consument herkennen die hoort bij een (inmiddels afgeronde) transactie. De entranceCode moet iedere transactie afwijkend zijn. De Transaction.entranceCode wordt hiertoe meegestuurd in de HTTP(S) GET naar de Merchant als parameter achter de merchantReturnURL. De Transaction.entranceCode dient een minimale variatie van 1 miljoen te hebben. Deze code moet bestaan uit letters en/of cijfers (maximaal 40 posities). De Transaction.entranceCode wordt aangemaakt door de Merchant en doorgegeven aan de Issuer

ANS..max40

SignedInfo

Bevat informatie over de digitale handtekening conform de W3C XMLdsig specificaties

*

SignatureValue

Bevat de digitale handtekening conform de W3C XMLdsig specificaties

  •  

KeyInfo

Bevat informatie (fingerprint) over het certificaat dat gebruikt wordt voor het genereren van de meegestuurde digitale handtekening, zodat de ontvanger de juiste public key kan gebruiken voor validatie van de handtekening conform de W3C XMLdsig specificaties

  •  

*SignedInfoSignatureValue 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

<?xml version="1.0" encoding="UTF-8"?> <AcquirerTrxRes xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1"> <createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp> <Acquirer> <acquirerID>0001</acquirerID> </Acquirer> <Issuer> <issuerAuthenticationURL>https://www.issuingbank.eu/ideal?random=1Y98dHjPwe2qq3s&amp;amp;trxid=0001000000000001</issuerAuthenticationURL> </Issuer> <Transaction> <transactionID>0001000000000001</transactionID> <transactionCreateDateTimestamp>2008-11-14T09:30:50.125Z</transactionCreateDateTimestamp> <purchaseID>iDEAL21</purchaseID> </Transaction> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- Signature is placed here. See Signature section for specification--> </Signature> </AcquirerTrxRes>

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

De Merchant is verantwoordelijk voor het redirecten van de Consument, vanaf de (mobiele) web pagina of app van de Merchant, naar de Issuer, waar de Consument zijn/haar Issuing bank selecteert. Als het bij het doorsturen niet mogelijk is de Consument in dezelfde web pagina te houden moet dit worden gecommuniceerd met de Consument (bijvoorbeeld: "U zal nu worden doorgestuurd naar de app of (mobiele) website van uw bank").
In het geval dat een betaling wordt geïnitieerd vanuit de Merchant app is het niet toegestaan de Issuer schermen te tonen in de app omgeving van de Merchant middels 'in-app-browsing via web-view'. Alle stappen van de betaalflow, tot aan de redirect terug naar de Merchant, moeten doorlopen worden in een omgeving die door de Consument vertrouwd wordt. Dit kan de voorkeurs-web-browser zijn, die door de consument gekozen is, of de mobiele app van de Issuer. De issuerAuthenticationURL moet daarom altijd voor uitvoering aan het mobiele OS worden aangeboden, of geopend worden met behulp van SafarViewController of Chrome Custom Tabs. Voor meer informatie zie paragraaf 10.3. Gedurende de opgestarte betaalflow mag het voor de Consument niet mogelijk zijn een andere betaling te initiëren in de app van de Merchant.

Relevante details over deze redirect van de Merchant naar het mobiele kanaal van de Issuer:

  • De Issuer bepaalt welke Consumenten worden omgeleid naar welk kanaal. Sommige Issuers kunnen bijvoorbeeld gebruikers van een tablet op dezelfde manier behandelen als gebruikers van een smartphone terwijl anderen tablet gebruikers zullen behandelen zoals reguliere PC gebruikers;

  • De Merchant heeft geen invloed op de redirect, er is maar één issuerAuthenticationURL voor gebruik in alle transacties, dus geen aparte URL voor mobiele iDEAL transacties;

  • Als de Issuing bank iDEAL mobiel heeft geïntegreerd in haar Mobiel Bankieren App zal de Consument, op de 'landing page' van de Issuer, automatisch doorgeleid worden naar de mobiel bankieren app of de mogelijkheid geboden worden de Mobiel Bankieren App te openen of verder te gaan via de (mobiele) web pagina. Op de 'landing page' kan de Consument ook de mogelijkheid geboden worden de nieuwste versie van de Mobiel Bankieren App te downloaden voor het geval deze nog niet geïnstalleerd is op het mobiele apparaat van de Consument.

Zoals hierboven beschreven, mag een Issuer de Consument de mogelijkheid bieden om een (update van een) mobiele betaal-app te downloaden als onderdeel van de transactie. In sommige gevallen zal de extra tijd die nodig is om de app te downloaden en te personaliseren ervoor zorgen dat de betaling de ingestelde geldigheidsduur (expiration period) overschrijdt. Dit zal vooral kunnen gebeuren als de expiration period op een zeer korte tijdspanne is ingesteld. In dergelijke gevallen kan de betaling niet succesvol worden voltooid. De Merchant kan in dit geval wel de status van de betaling ophalen.
Merchants kunnen dergelijke mislukte transacties in het mobiele kanaal voorkomen door een langere geldigheidsduur in te stellen voor betalingen die worden geïnitieerd vanaf het mobiele apparaat van een Consument. Dit is bovendien aan te raden omdat de beschikbare bandbreedte en signaalsterkte van een mobiele internetverbinding wisselend kunnen zijn, wat ervoor kan zorgen dat transacties via dit kanaal meer tijd nodig hebben om succesvol afgerond te worden.

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.

Let op: dat een Consument niet altijd gebruik zal maken van de knop die door de Issuer wordt aangeboden om terug te keren naar de omgeving van de Merchant. Let ook op dat in uitzonderlijke gevallen de Issuer mogelijk niet in staat is de transactionID te vinden in zijn systemen of dat er andere storingen optreden, die het onmogelijk maken om de Consument terug te leiden naar de Merchant. In alle andere gevallen wordt de Consument terug geleid met de complete URL inclusief parameters zoals hierboven beschreven, ongeacht de eindstatus van de betaling (succes, afgebroken, verlopen). De Merchant moet vervolgens het Navraagprotocol gebruiken (zie het volgende hoofdstuk) om de status van de transactie vast te stellen.

 

Nadat de Consument geauthentiseerd is door de Issuer in ofwel de mobiele ofwel het reguliere kanaal, en de betaling door de Issuer is goedgekeurd, zal hij worden terug geleid naar de Merchant door middel van de merchantReturnURL. De merchantreturnURL begint normaalgesproken met 'https' en dit zorgt ervoor dat de consument wordt terug geleid naar een web pagina van de browser op het mobiele apparaat. Als de Consument de betaling geïnitieerd heeft vanaf de Mobiele Merchant App kan de merchantReturnURL beginnen met de app handler van de Merchant, die de Consument doorstuurt naar de app van de Merchant. Een app handler is een mechanisme dat ervoor zorgt dat vanuit de ene app (van de Issuer) een andere app gestart wordt en er een bepaalde actie uitgevoerd wordt. Een Merchant app handler kan bijvoorbeeld starten met 'companyname://' en hiermee wordt de Merchant app geopend. Daarnaast is het ook mogelijk om gebruik te maken van Universal Links (iOS) of Android App Links technieken om de Consument terug naar de Merchant app terug te leiden.

Let op: de merchantReturnURL moet altijd verwijzen naar een webpagina of app van de Merchant zelf (of derde partij handelend namens de Merchant).

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. 

Scenario

Merchant

Issuing Bank

Scenario

Merchant

Issuing Bank

1

(Mobiele) web page

(Mobiele) web page

2

(Mobiele) web page

Mobiel Bankieren App

3

Mobiele app

Mobiel Bankieren App

4

Mobiele app

(Mobiele) web page

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

Stap

Beschrijving

Scenario 1 - Merchant (mobiele) web page naar Issuer (mobiele) web page

Scenario 2 - Merchant (mobiele) web page naar Issuer Mobiel Bankieren App

Scenario 3 - Merchant mobiele app naar Issuer Mobiel Bankieren App

Scenario 4 - Merchant mobiele app naar  Issuer (mobiele) web page

Stap

Beschrijving

Scenario 1 - Merchant (mobiele) web page naar Issuer (mobiele) web page

Scenario 2 - Merchant (mobiele) web page naar Issuer Mobiel Bankieren App

Scenario 3 - Merchant mobiele app naar Issuer Mobiel Bankieren App

Scenario 4 - Merchant mobiele app naar  Issuer (mobiele) web page

1

De Consument selecteert het item wat hij wil kopen, selecteert iDEAL als betaalmiddel en selecteert zijn/haar Issuing bank.









Copyright © Currence iDEAL B.V. All rights reserved.