paysafecard API

Wat heeft u nodig?

Om de paysafecard API te gebruiken, heeft u de volgende gegevens nodig:

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

  1. U vraagt via de paysafecard prepare API een betaling aan, aan de hand van o.a. uw partnerid en het gewenste amount in 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.
  2. De API meldt zich na de betaling op de achtergrond bij een door u opgegeven reporturl, waarna u de betaling controleert via de check-status API en dit resultaat verwerkt.
  3. 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.

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)

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.

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.

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 Geeft de exacte status zoals deze van paysafecard terug kwam, mits deze beschikbaar was. Mogelijke statussen zijn:
Status Omschrijving
Success De betaling is gelukt
Cancelled De consument heeft de betaling geannuleerd.
Expired De betaling is verlopen doordat de consument niets met de betaling heeft gedaan.
Open De betaling is nog niet afgerond (er is geen verdere informatie beschikbaar)
CheckedBefore U heeft de betalingstatus al een keer opgevraagd.

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
-1We've failed to create the payment due an unknown error
-2Missing parameter: [de missende parameter komt hier]
-3This account doesn't exist or is suspended
-4Invalid profile_key
-5Amount is too low. Minimal amount is [het minimale bedrag komt hier te staan]
-6Amount is too high. Maximum amount is [het maximale bedrag komt hier te staan]
-7There is a problem with the 'reporturl' you have provided: [de url die u geeft komt hier te staan]
-8There is a problem with the 'returnurl' you have provided: [de url die u geeft komt hier te staan]
-9Invalid type
-10Invalid transaction_id
-11Payments are disabled for this customer
-12Invalid customer_ref

Support

Bekijk de documentatie en vind antwoorden op veelgestelde vragen.

Klantportfolio

Ontdek wie allemaal de diensten van Mollie gebruikt.

Salesteam

Spreek met een medewerker voor een oplossing op maat.

Contact

Neem voor vragen contact op met een medewerker van Mollie.