|
SOFORT Banking: Documentatie
In dit document staat beschreven hoe u een SOFORT Banking 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-en-klaar modules.
1.1 Opmerking vooraf
Om de integratie voor u gemakkelijk te maken hebben we voor PHP 5 (en hoger) een aantal voorbeeld classes ontwikkeld. Hiermee integreert u alle betaalwijzen van TargetPay zeer eenvoudig in uw website. U hoeft de bestanden alleen maar te uploaden op uw server.
U downloadt het pakket via de volgende link: TargetPayExampleClasses.zip
1.2 Werking van de API in een notendop
Afrekenen met SOFORT Banking werkt als volgt:
- U roept bij TargetPay een URL aan met alle kenmerken van de betaling, TargetPay retourneert een link naar het online
bankieren pakket van SOFORT Banking (zie kopje 3);
- Op SOFORT Banking selecteert de gebruiker zijn of haar land, bank en voltooit de betaling. Na betaling wordt de bezoeker teruggestuurd naar uw site (zie kopje 4);
- Als u gebruik maakt van het push model vertelt ons systeem u of de betaling succesvol is geweest. Gebruikt u het pull model, dan controleert u status van de betaling bij TargetPay (zie kopje 5);
- Bij een succesvolle betaling levert u de gekozen dienst aan uw bezoeker.
2.1 Aanroep
De link naar het internet bankieren kan opgevraagd worden door aanroep te doen via HTTP GET of POST naar:
https://www.targetpay.com/directebanking/start
Met de volgende parameters:
| Variabele |
Naam |
Formaat |
Verplicht |
| rtlo | Layoutcode | Numeriek | Ja |
| description | Omschrijving | Alfanumeriek | Ja |
| amount | Bedrag in centen, lokale valuta | Alfanumeriek | Ja |
| country | Landcode | Numeriek | Ja |
| type | Type | Numeriek | Ja |
| userip | IP-Adres | Alfanumeriek | Ja |
| lang | Taal | Alfanumeriek | Nee |
| returnurl | Return URL | Alfanumeriek | Ja |
| reporturl | Rapporteer naar URL | Alfanumeriek | Nee |
Toelichting per variabele:
- rtlo
De layoutcode waarop de betaling geboekt moet worden. Zie subaccounts.
- description
Ordernummer / Beschrijving van de dienst of het product dat u levert. Dit veld zal voorgegegaan worden met TargetMedia's transactienummer in het volgende formaat: trxid.uwDescription. Dit veld mag samen met TargetMedia's transactienummer en de daarop volgende punt maximaal 27 karakters lang zijn. Let op: Dit veld komt op de eerste regel van het bankafschrift van de consument te staan. Op de tweede regel komt de bedrijfsnaam of, indien geen bedrijfsnaam aanwezig is, de naam van het contactpersoon van uw account.
- amount
Het in rekening te brengen bedrag in centen van de lokale valuta. Mogelijke waarden: minimaal 10, maximaal 500000. Dus in Duitsland: € 0,10 - € 5.000. In U.K.: £ 0,10 - £ 5.000
- country
De ISO landcode van het land waarvoor u SOFORT Banking wilt gebruiken. Op het moment ondersteund zijn:
- Duitsland (49)
- Oostenrijk (43)
- Zwitserland (41)
- België (32)
Let op dat u hier het getal zonder haakjes meegeeft, niet de tekst.
- type
De ID voor het type dienst dat u levert. De mogelijkheden zijn:
- Fysieke producten: bijv. webwinkel, adult & non-adult (1)
- Digitaal: bijv. download, betaalde toegang, non-adult (2)
- Digitaal: bijv. download, betaalde toegang, adult (3)
Let op dat u hier het getal zonder haakjes meegeeft, niet de tekst.
- userip
Het IP adres van uw klant.
- lang
De taal waarin de SOFORT Banking betaalomgeving moet worden getoond. De mogelijkheden zijn:
- returnurl
De URL waarnaar de bezoeker moet worden verwezen na betaling (zie kopje 4).
- reporturl
Als u deze invult, dan roepen we de URL op uw server aan na de betaling (vanaf onze server). 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'. Daarnaast: Voor SOFORT Banking worden er alleen reporturl aanroepen gedaan voor succesvolle, geannuleerde en verlopen transacties!
2.2 Resultaatcode's
Als de overboeking met succes klaargezet is, ontvangt u een resultaat in de vorm:
000000 xxxxxx|yyyyyy
- xxxxxx : Het transactie ID (nodig voor het opvragen van de status van de transactie);
- yyyyyy : URL waarnaar u de bezoeker kunt doorverwijzen;
Voorbeeld:
000000 30626804185492|https://www.directebanking.com/payment/start?
user_id=56123&project_id=512311&sender_holder=&sender_account_number=
&sender_bank_code=&sender_country_id=&amount=1.00¤cy_id=EUR
&reason_1=Betaling+voor&reason_2=orderID&user_variable_0=11
&user_variable_1=&user_variable_2=&user_variable_3=&user_variable_4=
&user_variable_5=&hash=0d4ac7d721f369693e5d14b7bd65104c42834e65
U kunt uw bezoeker nu redirecten naar de teruggegeven URL, bijv. met een HTTP 302 response.
Als er een fout is opgetreden, dan wordt een van de volgende foutcodes geretourneerd:
TP0001 No layoutcode specified
TP0002 Amount too low (minimaal 0,10 euro)
TP0003 Amount too high (maximaal 5.000 euro)
TP0004 Invalid or no return URL
TP0005 Geen bank ID meegegeven
TP0006 Invalid or no description
TP0007 Invalid or no country
TP0008 Country not supported for SOFORT Banking
TP0009 Invalid or no user IP given
TP0010 Invalid or no amount
TP0011 Report URL is invalid
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.
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 worden als extra parameters 'trxid' en 'rtlo' meegegeven, welken het transactie
ID en de layoutcode bevatten. Deze zijn gelijk aan het transactie ID en de layoutcode van de vorige stap.
4.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/directebanking/check
Met de volgende parameters:
| Variabele |
Naam |
Formaat |
Verplicht |
| rtlo | Layoutcode | Numeriek | Ja |
| trxid | Transactie ID | Numeriek | Ja |
| once | 'Reeds ingewisseld' melding? | 0 of 1 | Nee |
| test | test nee of ja | 0 of 1 | Nee |
Toelichting per variabele:
- 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 Already checked terug.
Als u voor once '0' invult dan zal steeds een OK status terug blijven komen.
4.2 Resultaatcode's
Als de betaling met succes afgerond is, ontvangt u als antwoord:
000000 OK
Als de betaling nog niet is afgerond of de transactie is niet bekend:
TP0010 Transaction not finished yet, try again later
TP0011 Transaction canceled
TP0012 Transactie is verlopen (max. 1 uur)
TP0014 Already checked
TP0020 No layoutcode specified
TP0021 No transactionID specified
TP0022 No transaction with this ID found
TP0023 Layoutcode does not match this transaction
5.1 Callback
Als u bij het aanmaken van de transactie de parameter "reporturl" hebt meegegeven, zal deze URL worden aangeroepen in een van de volgende gevallen:
- Als de transactie succesvol verlopen is
- Als de gebruiker de transactie annuleert
- Als de transactie verloopt na te lang open te hebben gestaan
De door u opgegeven reporturl wordt via HTTP POST aangeroepen met de volgende parameters:
- trxid - Het transactienummer dat aangemaakt is in de aanroep beschreven in 2.1
- rtlo - De layoutcode die u hebt meegegeven in de aanroep beschreven in 2.1
- status - De status van de transactie. Deze kan bestaan uit "Success", "Failed", "Canceled", of "Expired"
|
|
|
|
Niet ingelogd, klik hier