Technische handleiding iDeal (IDE.001)
Auteur(s): Michel Westerink
(MW)
Versie geschiedenis: V1.0 MW (kopie van targetpay.com)
07/01/13
V1.0
20/02/14
MKh Tabel Foutcodes bijgewerkt
Inhoudsopgave 1. Algemeen ................................................................................................................. 3 1.1 Voorbeeldcode PHP ................................................................................................ 3 1.2 Werking van de API in een notendop ....................................................................... 3 1.3 Testen zonder te betalen ........................................................................................ 3 1.4 E-mail notificaties ................................................................................................. 3 2. Keuze van de bank .................................................................................................... 4 2.2 Voorbeeld............................................................................................................. 4 2.3 XML ..................................................................................................................... 4 3. Opvragen link naar internetbankieren ........................................................................... 5 3.1 Aanroep ............................................................................................................... 5 3.2 Resultaatcodes ..................................................................................................... 6 4. Klant wordt doorverwezen .......................................................................................... 8 5. Status opvragen ........................................................................................................ 8 5.1 Aanroep ............................................................................................................... 8 5.2 Resultaatcodes ..................................................................................................... 9 6. Voorbeelden ............................................................................................................ 10 6.1 iDeal voorbeeld ................................................................................................... 10 6.2 Parameters returnurl ........................................................................................... 12
2/12
1. Algemeen In dit document staat beschreven hoe u een iDeal betaling afhandelt via TargetPay door gebruik te maken van onze API (technische koppeling). Om hiermee aan de slag te kunnen heeft u technische kennis nodig. Heeft u zelf geen technische kennis en ook geen programmeur om u hiermee te helpen, kijk dan bij de kant-enklaar modules. ( https://www.targetpay.com/info/ideal-start )
1.1 Voorbeeldcode PHP Om de integratie voor u gemakkelijk te maken hebben we onderaan deze pagina een PHP voorbeeld geplaatst. Hiermee integreert u iDeal zeer eenvoudig in uw website. U hoeft deze programmacode alleen maar te uploaden op uw server.
1.2 Werking van de API in een notendop Afrekenen met iDeal werkt als volgt: 1. U laat uw bezoeker zijn bank kiezen (zie Paragraaf 2); 2. U roept bij TargetPay een URL aan met alle kenmerken van de betaling, TargetPay retourneert een link naar het online bankieren pakket van de bezoeker (zie kopje 3); 3. Na betaling wordt de bezoeker teruggestuurd naar uw site (zie kopje 4); 4. U controleert bij ons of de betaling succesvol is geweest (zie kopje 5); 5. Bij een succesvolle betaling levert u de gekozen dienst aan uw bezoeker.
1.3 Testen zonder te betalen Om uw orderafhandeling te testen kunt u bij de check functie uit paragraaf 5 de parameter test=1 opgeven. Met deze instelling krijgt u altijd een '00000 OK' status terug. Indien u nu de transactie annuleert tijdens de betaling wordt deze in uw winkelsoftware toch als succesvol geboekt. Niet vergeten om de parameter weg te halen voordat de website live gaat.
1.4 E-mail notificaties Het is mogelijk om van iedere succesvolle iDeal betaling een E-mail notificatie te ontvangen. Hiervoor gaat u naar het scherm Subaccounts/Layouts en wijzig daar de betreffende layoutcode. Onderin dit scherm kunt u het E-mail adres en de betaalvorm aangeven waarvan u de notificaties wilt ontvangen. LET OP: controleer de iDeal orderdetails indien u een E-mail ontvangt.
3/12
2. Keuze van de bank Een van de voorwaarden om iDeal te mogen gebruiken is het juist gebruik van de iDeal huisstijl. Deze schrijven onder meer voor dat de eindconsument zijn bank moet kiezen uit een pulldown menu (<select> statement), en hoe de verschillende opties gepresenteerd moeten worden. Om te zorgen dat deze lijst altijd up-to-date is en voldoet aan de voorwaarden kan deze kanten-klaar ingeladen worden bij TargetPay. De 'options' uit het select statement kunnen met een Javascript include ingeladen worden. Hiervoor zijn 2 URL's: Nederlandstalig:
https://www.targetpay.com/ideal/issuers-nl.js
Engelstalig:
https://www.targetpay.com/ideal/issuers-en.js
2.2 Voorbeeld Een voorbeeld HTML waarbij de lijst met banken variabel wordt ingeladen: HTML-voorbeeld code
2.3 XML Tevens is het mogelijk om de lijst met banken op te vragen in HTML of in XML formaat. opvragen. De resultaten kunt u dan zelf verwerken in een pull-down menu. Hiervoor kunt u de URL: https://www.targetpay.com/ideal/getissuers.php of https://www.targetpay.com/ideal/getissuers.php?format=xml
4/12
3. Opvragen link naar internetbankieren 3.1 Aanroep Als de consument zijn of haar bank geselecteerd heeft kan een link opgevraagd worden naar het internet bankieren. Dit kan door aanroep te doen via HTTP-GET of POST naar: https://www.targetpay.com/ideal/start Met de volgende parameters: Variabele
Naam
Formaat
Verplicht
rtlo
Layoutcode
Numeriek
Ja
bank
ID van de Bank
Numeriek
Ja
description
Omschrijving
Alfanumeriek
Ja
currency
Valuta
Numeriek
Nee
amount
Bedrag in centen
Alfanumeriek
Ja
language
Taal
Alfanumeriek
Nee
returnurl
Return URL
Alfanumeriek
Ja
reporturl
Rapporteer naar URL
Alfanumeriek
Nee
cinfo_in_callback
Naam/Rekeningnummer in callback
0/1
Nee
5/12
Toelichting per variabele: Variabele
Toelichting
rtlo
De layoutcode waarop de betaling geboekt moet worden. Zie subaccounts.
bank
Nummer van de bank, gekozen door de consument in de vorige stap.
description
Duidelijke omschrijving van de te leveren dienst. Alleen letters of cijfers, maximaal 32 tekens.
currency
Valuta, momenteel is alleen de euro beschikbaar: 'EUR' (veld is niet verplicht, voor toekomstig gebruik)
amount
Het in rekening te brengen bedrag in eurocenten. Mogelijke waarden: minimaal 84, maximaal 1000000 (€ 0,84 - € 10.000)
language
De taal van uw bezoeker, voor gebruik in internetbankieren, momenteel is alleen Nederlands beschikbaar: 'nl' (veld is niet verplicht, voor toekomstig gebruik)
returnurl
De URL waarnaar de bezoeker moet worden verwezen na betaling (zie kopje 4). Let op 1:De URL moet vanaf het internet bereikbaar zijn anders zullen niet alle banken functioneren. Let op 2: U mag zelf maar één parameter meegeven aan de returnurl. In paragraaf 6.2 staat een oplossing beschreven om toch meerdere parameters door te sturen.
reporturl
Als u deze invult, dan roepen we de URL op uw server aan na de betaling (vanaf onze server). Dit gebeurt ook als uw klant niet op de knop 'Verder klikte...'. Aan uw URL voegen we 3 parameters toe: trxid met daarin het bestelnummer, rtlo met de layoutcode en status met een van de resultaatcodes uit § 5.2. Dus als uw report URL 'www.test.nl/report' is dan doen we een http POST naar: "http://www.test.nl/report". Let op: verwar de reporturl niet met de returnurl. Uw bezoeker krijgt de reporturl nooit te zien, dit gebeurt 'onder water'. Indien cinfo_in_callback gelijk is aan 1, wordt cname, ccity en cbank nog aan de reporturl toegevoegd. ccity is na de invoering van SEPA leeg.
cinfo_in_call De statuscontrole en de reporturl bevat bij een succesvolle betaling de naam en back het rekeningnummer van de consument
3.2 Resultaatcodes Als de betaling met succes klaargezet is, ontvangt u een resultaat in de volgende vorm:
<spatie> Het resultaat van de aanvraag. Het transactie ID van 16 tekens. Dit transactie nummer heeft u later nodig voor het opvragen van de status van de transactie.
De URL waarnaar u de bezoeker kunt doorverwijzen;
Voorbeeld van een succesvolle aanvraag: 000000 30626804185492|https://idealet.abnamro.nl/nl/ideal/identification.do?randomizedstring=1684152718&trxid=306268041854 92 6/12
U kunt uw bezoeker nu redirecten naar de teruggegeven URL, bijv. met een HTTP 302 response. Foutcodes: Foutcode
Omschrijving
TP0001 No layoutcode.
Geen layoutcode opgegeven
TP0002 Amount too low.
Bedrag te laag (minimaal 0,84 euro)
TP0003 Amount too high.
Bedrag te hoog (maximaal 10.000 euro)
TP0004 No or invalid return URL.
Geen of ongeldige return URL meegegeven
TP0005 No bank ID.
Geen bank ID meegegeven
TP0006 No description.
Geen omschrijving meegegeven
TP0016 No iDEAL approval for this account yet.
Het account is nog niet goedgekeurd voor iDeal
TP0017 Incorrect rtlo code.
De layoutcode (rtlo) is onjuist of bestaat niet
TP0019 Account disabled.
Het account staat op uitgeschakeld
TP9997 Internal error, failed to create transaction. TP9997 ING is performing maintenance.
Te veel retry’s bij de bank. Performing maintenance meldingen zijn er voor alle banken
TP9998 Failed to create transaction.
De bank geeft geen transactienummer terug
TP9999 Internal error
Mail [email protected] voor onderzoek.
TP9999 Your account has been blocked.
Account geblokkeerd wegens vermeend misbruik
SO1000
Storing in systeem
SO1200
Systeem te druk. Probeer later nogmaals
SO1400
Onbeschikbaar door onderhoudswerkzaamheden
Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn. Neem dan contact op met TargetPay, vermeldt de aanroep en de foutmelding.
7/12
4. Klant wordt doorverwezen Als uw klant klaar is met afrekenen bij internetbankieren óf wanneer hij op 'annuleren' klikt tijdens dit proces, wordt hij automatisch doorverwezen naar uw site, namelijk naar de opgegeven return URL. Daarbij wordt als extra parameter 'trxid' meegegeven, welke het transactie ID bevat. Dit is gelijk aan het transactie ID van de vorige stap. Voorbeeld: http://www.uwsite.nl/idealReturnFile.php?trxid=30626804185492
5. Status opvragen 5.1 Aanroep Als de bezoeker door internetbankieren terug verwezen is naar uw site, kunt u met een aanroep naar TargetPay opvragen of de betaling afgerond is. https://www.targetpay.com/ideal/check Met de volgende parameters: Variabele
Naam
Formaat
Verplicht
rtlo
Layoutcode
Numeriek
Ja
trxid
Transactie ID
Numeriek
Ja
once
'Reeds ingewisseld' melding?
0/1
Ja
test
test nee of ja
0/1
Nee
Toelichting per variabele: Variabele
Toelichting
rtlo
Layoutcode (zelfde waarde als meegegeven onder 5.1)
trxid
Transactie ID, geretourneerd in de vorige stap (16 tekens)
once
Als u voor once '1' invult dan zal slechts 1x een OK status teruggegeven worden. Als de bovenstaande URL nog een keer wordt aangeroepen voor hetzelfde Transactie ID dan krijgt u een foutmelding 'TP00014 (Reeds ingewisseld)' terug. Als u voor once '0' invult dan zal steeds een OK status terug blijven komen. Vul bij twijfel 1 in, zo weet u zeker dat een dienst niet meerdere malen geleverd wordt als de bezoeker op “Refresh” en/of “F5” zou drukken.
test
8/12
Betreft het een test aanroep ja (1) of nee (0). Het systeem valideert de aanvraag op dezelfde wijze als deze gedaan zou worden met een echte call (test=0)
5.2 Resultaatcodes Als de betaling met succes afgerond is, ontvangt u als antwoord: 000000 OK Of indien cinfo_in_callback gelijk is aan 1: 000000 OK |Naam|rekeningnummer| Als de betaling nog niet is afgerond of de transactie is niet bekend: Foutcode
Omschrijving
TP0010 Transaction has not been completed, try again later.
Transactie is nog niet afgerond, probeer het later opnieuw
TP0011 Transaction has been cancelled
Transactie is geannuleerd
TP0012 Transaction has expired
Transactie is verlopen (max. 10 minuten)
TP0013 The transaction could not be processed Of TP0013 Internal Error
De transactie kon niet verwerkt worden
TP0014 Already used
Reeds ingewisseld
TP0020 Layoutcode not entered.
Geen layoutcode opgegeven
TP0021 Tansaction ID not entered.
Geen transactie-id opgegeven
TP0022 No transaction found with this ID.
Geen transactie met dit ID gevonden
TP0023 Layoutcode does not match this transaction.
Layoutcode hoort niet bij deze transactie
9/12
6. Voorbeelden 6.1 iDeal voorbeeld Het onderstaande voorbeeld kunt u kopiëren in een bestand 'iDealExample.php' en uploaden naar uw server. U hoeft alleen de parameters bovenin het bestand in te stellen om een transacties te doen. Als u dit script wilt koppelen met een webwinkel kunt u zelf programmacode toevoegen in de functies StartTransaction, HandleReporturl en bij het resultaat van de returnurl. PHP-voorbeeld code Thank you for your order".$status ); } //In all other cases do not delever(yet) // Update the orderinfo to failed else die( "Status was ".$status. "
" ); } // The reporturl is called from the Targetpay server if ( isset($_POST['rtlo'])&&isset($_POST['trxid'])&& isset($_POST['status'])) { HandleReporturl($_POST['rtlo'], $_POST['trxid'], $_POST['status'] ); } // Start with the bank selection SelectBank(); // paragraph 2: Bank selection function SelectBank(){ $url="https://www.targetpay.com/ideal/getissuers.php"; $strResponse = httpGetRequest($url); echo ""; echo ""; echo ""; }
10/12
// Paragraph 3. Request redirect URL to the bank function StartTransaction( $rtlo, $bank, $description, $amount, $returnurl, $reporturl){ $url= "https://www.targetpay.com/ideal/start?". "rtlo=".$rtlo. "&bank=".$bank. "&description=".urlencode($description). "&amount=".$amount. "&returnurl=".urlencode($returnurl). "&reporturl=".urlencode($reporturl); $strResponse = httpGetRequest($url); $aResponse = explode('|', $strResponse ); # Bad response if ( !isset ( $aResponse[1] ) ) die('Error' . $aResponse[0] ); $responsetype = explode ( ' ', $aResponse[0] ); $trxid = $responsetype[1]; // You may add the trxid to your orderinfo here if( $responsetype[0] == "000000" ) return $aResponse[1]; else die($aResponse[0]); } // Paragraph 5. Request status in returnurl function CheckReturnurl($rtlo, $trxid){ $once=1; $test=0; // Set to 1 for testing as described in paragraph 1.3 $url= "https://www.targetpay.com/ideal/check?". "rtlo=".$rtlo. "&trxid=".$trxid. "&once=".$once. "&test=".$test; return httpGetRequest($url); } // Handler for the reporturl. // Update your your orderstatus and deliver the product if $status = "000000 OK" function HandleReporturl($rtlo, $trxid, $status ){ if( substr($_SERVER['REMOTE_ADDR'],0,10) == "89.184.168" ){ // Update your orderinfo status here. //...... //reporturl should return OK to TargetPay.com die( "OK" ); }else{ die("IP address not correct... This call is not from Targetpay"); } } function httpGetRequest($url){ $ch = curl_init( $url ); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1) ; $strResponse = curl_exec($ch); curl_close($ch); if ( $strResponse === false ) 11/12
die("Could not fetch response " . $url ); return $strResponse; } ?>
6.2 Parameters returnurl De banken kunnen maar één parameter in de returnurl verwerken. Als u dit toch doet komt er bij sommige banken een 'BR1200 Ongeldig versienummer' foutmelding terug. Indien u meerdere parameters wilt meesturen moet u deze als volgt in de returnurl encoden: http://www.uwsite.nl/preparse.php?token=param1-value1,param2-value2 Al uw parameters worden op deze manier in een parameter meegestuurd. In het script preparse.php dient u dan de parameter token uit te lezen en op de juiste manier door te sturen naar uw werkelijke returnurl. Bijvoorbeeld iDealExample.php preparse.php
PHP-voorbeeld code $v) { if ($k!="token") { $url .= "&$k=$v"; } } // Stel deze URL in op uw site $url = "http://www.uwsite.nl/iDealExample.php?".substr($url,1); Header ("Location: $url"); ?>
12/12
