paysafecard API
Wat heeft u nodig?
Om de paysafecard API te gebruiken, heeft u de volgende gegevens nodig:
- Uw Mollie partner ID: wanneer u bent ingelogd vindt u deze op de Accountgegevens pagina.
- Een actief websiteprofielen waar de betalingen aan gekoppeld worden.
Om daadwerkelijk paysafecard betalingen te kunnen ontvangen, dient paysafecard eerst geactiveerd te worden voor uw account. U kunt dit doen door de benodigde informatie aan ons te leveren via de Diensten pagina.
Voorbeelden & Modules
Het wiel niet opnieuw hoeven uit vinden: download hieronder onze PHP-class met voorbeelden.
| Omschrijving | Programmeertaal | Auteur | Versie |
|---|---|---|---|
| PHP class | PHP 5.x en hoger | Mollie | v1.0 |
Hoe werkt de paysafecard API?
Om een paysafecard-betaling te realiseren, dient u een aantal stappen door te lopen. Deze stappen zijn als volgt:
- U vraagt via de paysafecard
prepareAPI een betaling aan, aan de hand van o.a. uwpartneriden het gewensteamountin centen. U slaat de teruggekregen informatie op en stuurt uw klant naar de URL die in het antwoord op de aanvraag van de betaling zit. - De API meldt zich na de betaling op de achtergrond bij een door u opgegeven
reporturl, waarna u de betaling controleert via decheck-statusAPI en dit resultaat verwerkt. - Wij sturen nu de klant naar een door u opgegeven
returnurl, zodat hij weer uw winkel binnenkomt. U toont de klant op die URL een melding dat het gelukt is, of dat het niet gelukt is en u verwerkt eventueel de order.
Onze API werkt middels HTTP requests. Wanneer u een HTTP request naar onze server stuurt, kunt u met behulp van GET variabelen de waarden meesturen.
Stap 1: Vraag een betaling aan via de prepare API
Om een paysafecard-betaling aan te vragen dient u een aantal gegevens mee te sturen. In de tabel hieronder staan de parameters die nodig zijn om een betaling aan te maken. Deze zijn allemaal verplicht.
Aanvraag:
https://www.mollie.nl/xml/paysafecard/prepare/?partnerid=[uw partner id]&amount=123&profile_key=1a2b3c4d&reporturl=http%3A%2F%2Fwww.uwsite.nl%2Freport.php&returnurl=http%3A%2F%2Fwww.uwsite.nl%2Freturn.php&customer_ref=klant123-255-0-12
Hieronder de tabel met de parameters die u moet meegeven om een betaling aan te maken:
| Parameter | Uitleg |
|---|---|
partnerid |
Uw Mollie Partner ID. Te vinden op de accountgegevens-pagina. Op het gespecificeerde account wordt na succesvolle betaling tegoed bijgeschreven. |
profile_key |
Mollie Profiel Key. U vindt de websiteprofielen op de Profielen-pagina |
amount |
Bedrag van de betaling. OPGEGEVEN IN CENTEN! Dus wilt u een tientje afrekenen? Dan moet de waarde als 1000 worden meegegeven. Let op, want door dit fout te doen kan de marge nogal klein worden ;) |
reporturl |
Op het moment dat door het handelen van uw bezoeker duidelijk wordt of een betaling wel of niet is gelukt, doen wij OP DE ACHTERGROND een aanvraag naar deze url. In deze aanvraag vermelden we niet of de betaling al dan niet gelukt is. Dit moet u zelf checken als reactie op onze aanvraag naar uw reporturl (wordt hieronder verder behandeld). Dit lijkt onhandig, maar is feitelijk een security-enhancement. Als we dit niet zo doen, zouden mensen direct informatie aan uw report-script kunnen voeren. En dat kan gevaarlijk zijn. We geven als extra variablele 'transaction_id' mee. Deze parameter heeft u nodig bij het checken. |
returnurl |
Dit is de URL waar we uw klant heen sturen als het betaalproces (al dan niet succesvol) is afgerond. Als we de klant naar deze URL sturen, voegen we weer als extra variabele 'transaction_id' mee. Zo kunt u weer opzoeken om welke betaling en klant het ging. |
customer_ref |
Dit is een unieke klantreferentie die u aanhoudt voor dezelfde klant, door bijvoorbeeld het account ID of IP-adres van de klant te nemen. Deze referentie is niet iets wat u of uw klant later nog te zien krijgt in de bestelprocedure. (Het is niet mogelijk hier hoofdletters of spaties te gebruiken) |
Hierop krijgt u bijvoorbeeld het volgende antwoord:
<?xml version="1.0"?>
<response>
<order>
<transaction_id>482d599bbcc7795727650330ad65fe9b </transaction_id>
<amount>123</amount>
<currency>EUR</currency>
<URL>https://customer.cc.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=1000002193&mtid=192C-50D3-C396-4E02-AD90-3701-0423&amount=1.23¤cy=EUR</URL>
</order>
</response>
De uitleg van de XML-tags in het antwoord vindt u hieronder:
| Parameter | Uitleg |
|---|---|
transaction_id |
Dit is de combinatie van cijfers en letters waarmee de zojuist aangevraagde transactie kan worden geïndentificeerd. Dit ID kan gebruikt worden om in uw eigen database op te slaan en te koppelen aan de betaling in uw site. Ook kan deze ID in combinatie met de report van de API gebruikt worden om te checken of de betaling gelukt is. |
amount |
Dit is het bedrag zoals het is aangevraagd. Puur ter controle. |
URL |
Dit is de URL waar de klant heen moet worden gestuurd zodat hij aan de betaling kan beginnen bij paysafecard. |
Stap 2: De status van de betaling opvragen
Bij de aanvraag heeft u een reporturl meegegeven. Op deze URL dient een script van u te staan die, wanneer het wordt aangeroepen, met een 'transaction_id' als GET-variabele een check gaat uitvoeren bij onze API. Middels deze check controleert u of de betaling die bij 'transaction_id' hoort, betaald is of niet. Dit resultaat slaat u op bij de betaling die bij de transaction_id hoort in uw database. (U heeft deze koppeling immers aan de hand van de response van stap 1 gemaakt).
- Let op: Wanneer de aanroep naar uw reporturl niet lukt (bijvoorbeeld wanneer de connectie niet lukt of als de uiteindelijke HTTP status code niet 200 is), zal Mollie nog 10x op verschillende tijdsintervallen proberen de reporturl alsnog aan te roepen. Mocht het dan nog niet gelukt zijn, dan krijgt u een waarschuwing op uw Beheer-pagina.
Aanvraag:
https://secure.mollie.nl/xml/paysafecard/check-status/?partnerid=[uw partner id]&transaction_id=[transaction_id]
De parameters die u bij de aanvraag mee dient te geven zijn:
| Parameter | Uitleg |
|---|---|
partnerid |
Uw Mollie Partner ID. Te vinden op de accountgegevens-pagina. Op het gespecificeerde account wordt na succesvolle betaling tegoed bijgeschreven. |
transaction_id |
Dit is de combinatie van cijfers en letters waarmee de transactie kan worden geïndentificeerd bij ons (en uw) systeem. |
Hierop krijgt u bijvoorbeeld het volgende antwoord:
<?xml version="1.0"?>
<response>
<order>
<transaction_id>482d599bbcc7795727650330ad65fe9b</transaction_id>
<amount>123</amount>
<paid>true</paid>
<status>Completed</status>
</order>
</response>
Als u een tweede keer een betaling probeert te checken die weliswaar betaald is, maar die u al een keer heeft gecheckt, krijgt u daar geen paid=true uit. Zo kunnen pogingen van doortrapte klanten om orders twee keer geleverd te krijgen voor de prijs van één, in de kiem gesmoord worden.
Als u paid=true krijgt, kunt u dus in uw eigen database de order van de klant op betaald zetten. Als de klant dan later terugkomt in de winkel kunt u hem of haar het goede nieuws mededelen. Als de API onbekend is met een transactie, of de transactie niet betaald is (of dus al gecheckt), zal de API u dit altijd duidelijk vertellen in de message variabele.
Variabelen voor de paysafecard API bij het ophalen van de status:
| Parameter | Uitleg | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
transaction_id |
Dit is de combinatie van cijfers en letters waarmee de transactie kan worden geïndentificeerd bij ons (en uw) systeem. | ||||||||||||
amount |
Dit is het bedrag zoals het is aangevraagd. Puur voor checks. | ||||||||||||
paid |
'true' of 'false'. Geeft aan of er betaald is. Let op, wij houden bij of u al succesvol gecheckt heeft. Dus als u de tweede keer checkt sinds er betaald is, krijgt u hier 'false'. Zo beschermen we u tegen mogelijke fraude bij uw klanten. | ||||||||||||
status
|
Stap 3: De consument komt terug op returnurl
Nadat de betaling wel of niet gelukt is, sturen we de consument terug naar de door u in returnurl opgegeven URL met als extra variabele transaction_id, waarmee u weer kunt bepalen welke klant het is, en of volgens uw database die betaling gelukt was (u controleerde dat immers eerder met het script op reporturl en bewaarde dat resultaat). Aan de hand hiervan laat u de consument dus een bevestiging zien, of iets anders wat van toepassing is.
Uitzonderlijke situaties
In sommige gevallen is het mogelijk dat uw klant éérder terugkomt op de returnurl dan dat Mollie uw reporturl heeft aangeroepen. Dit kan bijvoorbeeld gebeuren wanneer er een storing optreedt bij paysafecard waardoor de status nog niet bekend is.
In deze situatie is het belangrijk om te onthouden dat Mollie uw systeem pas een rapportage stuurt op de reporturl op het moment dat de definitieve status van de betaling bij Mollie bekend is. Als u dit nog niet heeft ontvangen, weet uw systeem dus nog niet de definitieve status van de betaling.
Om uw klant in deze uitzonderlijke situatie niet in de war te brengen is het verstandig om duidelijk aan te geven dat de definitieve status van de betaling nog niet duidelijk is; maar dat de betaling - wanneer dat wel duidelijk is - automatisch wordt verwerkt.
Overzicht foutcodes
De API geeft bij iedere output een zinvolle uitleg. Bij het programmeren kan het fijn zijn om een overzicht te hebben van de foutcodes en de bijbehorende berichten.
| Foutcode | Uitleg |
|---|---|
| -1 | We've failed to create the payment due an unknown error |
| -2 | Missing parameter: [de missende parameter komt hier] |
| -3 | This account doesn't exist or is suspended |
| -4 | Invalid profile_key |
| -5 | Amount is too low. Minimal amount is [het minimale bedrag komt hier te staan] |
| -6 | Amount is too high. Maximum amount is [het maximale bedrag komt hier te staan] |
| -7 | There is a problem with the 'reporturl' you have provided: [de url die u geeft komt hier te staan] |
| -8 | There is a problem with the 'returnurl' you have provided: [de url die u geeft komt hier te staan] |
| -9 | Invalid type |
| -10 | Invalid transaction_id |
| -11 | Payments are disabled for this customer |
| -12 | Invalid customer_ref |
Other languages
Op deze pagina
- Wat heeft u nodig?
- Hoe werkt de paysafecard API?
- Stap 1: Betaling aanmaken
- Stap 2: Status opvragen
- Stap 3: Terug bij webwinkel
- Overzicht foutcodes
- Voorbeelden & Modules