Via telefoon (IVR/090x)
Vereiste kennis
Deze pagina beschrijft hoe u gebruik kunt maken van onze micropayments-infrastructuur om op uw eigen site betaalde diensten aan uw bezoekers aan te kunnen bieden.
Om van deze zogenaamde 'geïntegreerde' aanpak gebruik te maken dient u enige kennis te hebben van XML en een scripttaal zoals bijvoorbeeld PHP of ASP. Indien deze kennis niet voorradig is kunt u contact met ons opnemen om 'maatwerk' voor u te laten verrichten. We veronderstellen verder de aanwezigheid van eerdergenoemde kennis.
Hoe werkt de API?
Globaal verloopt het proces van een geïntegreerde micropayment als volgt:
- Een bezoeker wil gebruik maken van een betaalde dienst op uw website, middels micropayments;
- Uw site haalt bij het mollie-systeem een betaalnummer (telefoonnummer) en een betaalcode op;
- Uw site toont het betaalnummer en de betaalcode aan de bezoeker en meldt dat de bezoeker het nummer dient te bellen, en de betaalcode in moet voeren om de betaling te verrichten;
- De bezoeker belt het telefoonnummer en toetst de betaalcode in. De bezoeker betaalt hierdoor middels zijn telefoon(rekening);
- De bezoeker gaat verder op uw site waarbij uw site bij onze server controleert of de betaling is gelukt;
- Uw site constateert een succesvolle betaling en levert de bewuste dienst, of uw site constateert geen succesvolle betaling en presenteert wederom het betaalscherm.
Er zijn dus een aantal momenten waarop uw site communiceert met ons systeem. Deze communicatie verloopt middels de HTTP-API. HTTP omdat de communicatie via een webserver/webinterface verloopt. API wil zeggen 'Application Programming Interface', een verzameling definities op basis waarvan een systeem kan communiceren met een ander systeem. De aanvraag kan dus gedaan worden middels een GET- of POST-aanvraag, het antwoord volgt in XML.
We zullen nu laten zien hoe een geïntegreerde micropayment eruit ziet. We zullen het proces stap voor stap uitdiepen, waarbij we bij bepaalde stappen variaties op het thema laten zien.
Stap 1: Betaling aanvragen - ophalen 09xx-nummer & betaalcode
Zodra uw bezoeker besloten heeft om toegang te willen tot het betaalde gedeelte van uw website moet u vanaf uw systeem een POST- of GET-aanvraag doen naar ons systeem om het te bellen 09xx-nummer en de in te voeren betaalcode op te halen. In de POST- of GET-aanvraag die u doet kunt u meesturen welk bedrag er moet worden afgerekend en wat uw accountnummer is. Ons systeem kiest voor het gekozen bedrag de meest geschikte methode uit en zal, indien er betaald is, de tegoeden op uw account ophogen.
Bij het opvragen van een betaalnummer en een betaalcode dient de variabele 'a' ingesteld te worden op 'fetch'. Met deze variabele gebruikt men de HTTP-API dus in de 'fetchmode'. Vervolgens kunnen andere variabelen gebruikt worden om onder andere uw accountnummer en de prijs van de micropayment aan ons door te geven. Slechts partnerid en amount zijn verplicht bij het aanvragen van een code. Nu volgt een voorbeeld waarbij een betaling van € 1,75 wordt aangevraagd op uw partnerid. Daaronder staat het antwoord dat ons systeem zou kunnen geven op die voorbeeld-aanvraag.
Aanvraag:
http://www.mollie.nl/xml/micropayment/?a=fetch &partnerid=[partner id]&amount=1.75
Hierop krijgt u bijvoorbeeld het volgende antwoord:
<?xml version="1.0"?>
<response>
<item country="31">
<servicenumber>0909-1100400</servicenumber>
<paycode>012345</paycode>
<amount>1.75</amount>
<duration>131</duration>
<mode>ppm</mode>
<costperminute>0.80</costperminute>
<payout>1.09</payout>
<currency>euro</currency>
</item>
</response>
Bij het gebruik van de API in de 'fetchmode' kunnen meer variabelen worden opgegeven. Hier volgt een overzicht. Zorg overigens dat u geen variabelen gebruikt die tegenstrijdige informatie bevatten, anders zal de API een foutmelding geven.
Variabelen voor de XML-API in de 'fetchmode' (a=fetch):
| Parameter | Uitleg |
|---|---|
partnerid |
[verplicht] Mollie.nl accountnummer. Bijvoorbeeld partnerid=. Op de gespecificeerde account worden tegoeden bijgeschreven bij succesvolle betaling. |
amount |
[verplicht] Bedrag van de micropayment. Bijvoorbeeld amount=1.10. Echter, er kan ook gebruik gemaakt worden van de instelling amount=endless. In dit geval kan er eindeloos gebeld worden naar dit nummer en kan uw site de bezoeker een dienst aanbieden zolang de bezoeker belt. Het antwoord van de HTTP-API na de aanvraag zal in dit geval ook geen amount of duration bevatten. |
servicenumber |
[optioneel] Specificatie van het telefoonnummer. Bijvoorbeeld servicenumber=0909-1100400. Alleen te gebruiken indien men een specifiek nummer wil laten gebruiken. Kan conflicteren met amount en country. In de meeste gevallen is het niet nodig deze variabele te gebruiken. Het systeem kiest zelf welk nummer toepasselijk is. |
country |
[optioneel] Land vanwaaruit de betaling moet worden gedaan. Bijvoorbeeld country=32. Als dit niet gespecificeerd is, wordt Nederland (31) gebruikt. Klik hier voor een de lijst met (momenteel) ondersteunende landen |
report |
[optioneel] Rapportage URL. Bijvoorbeeld http://www.uwsite.nl/report.php. Op het moment dat de status van een betaling verandert zal ons systeem een GET-request doen naar de opgegeven URL, waarbij servicenumber en paycode worden doorgegeven. Zo'n statusverandering kan zijn dat er naar een nummer gebeld wordt, dat er wordt opgehangen, dat de betaling is afgerond, etc. Uw site kan aan de hand van zo'n statusmelding middels de 'checkmode' (verderop beschreven) alle details van een betaling controleren. Zo hoeft u niet continu te checken ('polling'), maar weet uw site wanneer het zinvol is om te checken. U gebruikt de report dan effectief als een trigger voor uw eigen systeem. Voorbeeld van zo'n report-request bij gebruik van de voorbeeld-rapportage-URL: http://www.uwsite.nl/report.php?servicenumber=0909-1100400&paycode=306792 |
Na het aanvragen van een micropayment middels de hierboven uitgelegde methode, zal de HTTP-API dus een antwoord geven in XML. Afhankelijk van de hierboven besproken instellingen in de 'fetchmode', zal de HTTP-API alle beschikbare informatie geven over de aangevraagde betaling. Hieronder staat uitgelegd welke informatie de API kan teruggeven, en wat deze informatie betekent.
Antwoordvariabelen voor de XML-API in de 'fetchmode':
| Parameter | Uitleg |
|---|---|
<servicenumber> |
[altijd] Hiermee wordt het telefoonnummer teruggegeven waar de bezoeker op moet gaan bellen. |
<paycode> |
[altijd] Hier staat de betaalcode die de bezoeker moet invoeren. |
<amount> |
[soms] Indien geen gebruik wordt gemaak van amount=endless wordt hiermee het bedrag bevestigd. Als amount=endless wordt gebruikt is het uiteindelijk afgerekende bedrag natuurlijk afhankelijk van hoelang de bezoeker aan de lijn is geweest, en kan dit niet op voorhand gegeven worden. |
<duration> |
[soms] Deze waarde geeft aan hoeveel seconden er gebeld moet worden om de betaling te voltooien. Dit kunt u bijvoorbeeld aan de bezoeker tonen. Wederom, dit wordt natuurlijk niet getoond wanneer amount=endless is ingesteld. Ook bij Pay Per Call is deze waarde betekenisloos. |
<mode> |
[altijd] Deze waarde bevat 'PPC', wat Pay Per Call (Kosten per gesprek) betekent, óf 'PPM', Pay Per Minute (Kosten per minuut). Afhankelijk van instellingen zoals amount kan deze waarde gaan verschillen. Zo is het bijvoorbeeld effectiever om in Nederland €1,30 middels een PPC-telefoontje af te rekenen. Uw opbrengst zal dan hoger zijn dan wanneer dit bedrag wordt afgerekend middels 'PPM'. Het systeem zal in dit geval zelf 'PPC' kiezen. (Ook het servicenumber zal dus veranderen, tenzij u dit hard heeft ingesteld bij de aanvraag, wat dus ook onverstandig is indien niet nodig). |
<costperminute> |
[soms] Deze waarde wordt gegeven wanneer de betaling van het type 'PPM' is, en bevat het tarief per minuut. |
<costpercall> |
[soms] Deze waarde wordt gegeven wanneer de betaling van het type 'PPC' is, en bevat het tarief per gesprek. |
<payout> |
[altijd] Dit is het bedrag exclusief 19% btw dat op uw account wordt bijgeschreven indien de betaling succesvol is afgerond. |
<currency> |
[altijd] Deze waarde bevat de valuta-eenheid. Op het moment is dat altijd 'euro'. |
Stap 2: Tonen betaalscherm aan bezoeker
Nu u met de HTTP-API een betaling heeft aagevraagd en van de HTTP-API alle benodigde informatie hierover heeft gekregen wordt het tijd om uw bezoeker uit te leggen hoe hij kan betalen.
Aan de bezoeker moet een betaalscherm getoond worden met op z'n minst het servicenummer (wat de bezoeker moet bellen om te betalen) en de paycode. Natuurlijk moet ook de prijs getoond worden. Daarnaast is het verplicht te vermelden wat de kosten per minuut (PPM) of per gesprek (PPC) zijn. Eventueel kan aan de bezoeker getoond worden hoe lang hij aan de lijn dient te blijven (in geval van PPM).
NB: vermeld bij de betaling altijd de kosten van de consument!
Stap 3: Betaling controleren
In het betaalscherm moet een knop/link gezet worden ('klik hier na betaling', of iets dergelijks). Als hierop geklikt wordt moet uw script op de achtergrond een HTTP request doen naar de HTTP-API in de zogenaamde 'checkmode' (a=check).
In de 'checkmode' geeft de HTTP-API de status van de betaling (wederom in XML) terug. Uit deze XML-status kunt u eenvoudig afleiden of de betaling reeds voltooid is en of u de dienst al kan gaan leveren. (Natuurlijk kunt u op een willekeurig moment de HTTP-API gebruiken in de 'checkmode' om de status van een betaling te controleren. Hiermee kunt u middels AJAX bijvoorbeeld een statusbalkje laten lopen terwijl de bezoeker belt.)
Nu volgt een voorbeeld van een GET-request en een XML-antwoord van een betalingscontrole. U ziet het antwoord dat gegeven wordt indien de in het eerdere voorbeeld aangevraagde betaling ondertussen betaald is door een fictieve bezoeker.
Aanvraag:
http://www.mollie.nl/xml/micropayment/?a=check &servicenumber=0909-1100400&paycode=012345
Hierop krijgt u bijvoorbeeld het volgende antwoord:
<?xml version="1.0"?>
<response>
<item country="31">
<servicenumber>0909-1100400</servicenumber>
<paycode>012345</paycode>
<payed>true</payed>
<durationdone>131</durationdone>
<durationleft>0</durationleft>
<amount>1.75</amount>
<currency>euro</currency>
<paystatus>Payment done.</paystatus>
</item>
</response>
Het gebruik van de API in de 'checkmode' is heel simpel. Belangrijk is dat de a-variable van de aavraag dus op 'check' staat. Voor de andere variabelen kunt u in het onderstaande schema kijken.
Variabelen voor de XML-API in de 'checkmode' (a=check):
| Parameter | Uitleg |
|---|---|
servicenumber |
[verplicht] Specificatie van het telefoonnummer. Bijvoorbeeld servicenumber=0909-1100400. Dit is verplicht bij het uitlezen van een betaling |
paycode |
[verplicht] Specificatie van de betaalcode. Bijvoorbeeld paycode=006616. Ook deze parameter is verplicht bij het uitlezen van een betaling |
Het antwoord van de HTTP-API op een 'checkmode'-aanvraag geeft uitsluitsel over de status van een betaling. Welke informatie de HTTP-API geeft en wanneer, kunt u zien in onderstaand schema. (Het schema gaat er overigens van uit dat u een combinatie van servicenumber en paycode checkt die bij ons bekend is. Als dit namelijk niet zo is, geeft de HTTP-API slechts 'Payment unknown', en geen van de beschreven variabelen.)
| Parameter | Uitleg |
|---|---|
<servicenumber> |
[altijd] Hiermee wordt het telefoonnummer teruggegeven dat aan deze betaling is gekoppeld. |
<paycode> |
[altijd] Hier staat de betaalcode die aan deze betaling is gekoppeld. |
<payed> |
[soms] Tenzij u een betaling checkt die van het type amount=endless is, bevat deze variabele true of false. Als u een betaling die succesvol is afgerond voor de tweede keer checkt zal payed weer op false staan (en zal er een melding worden gemaakt dat u deze betaling eerder succesvol heeft gecheckt). Zo proberen we te voorkomen dat u een dienst twee keer levert waar de bezoeker maar 1 keer voor betaald heeft. |
<paying> |
[soms] Deze variabele wordt alleen gegeven als er gebruikt wordt gemaakt van een betaling waarvoor geldt amount=endless. Tijdens het betalen is deze waarde dan true. |
<mode> |
[altijd] Deze waarde bevat 'PPC', wat Pay Per Call (Kosten per gesprek) betekent, óf 'PPM', Pay Per Minute (Kosten per minuut). Afhankelijk van instellingen zoals amount kan deze waarde gaan verschillen. |
<durationdone> |
[soms] Deze waarde bevat het aantal op deze betaling gebelde seconden. |
<durationleft> |
[soms] Deze waarde bevat het aantal seconden dat nog gebeld zou moeten worden om deze betaling af te ronden. |
<amount> |
[altijd] Deze variabele bevat de prijs van de gecheckte micropayment. |
<paystatus> |
[altijd] Deze variabele bevat een kreet die de huidige toestand van de betaling beschrijft. Bijvoorbeeld: 'Payment ready for usage.'. |
Op basis van dit resultaat kunt u dus de dienst geven aan de bezoeker.
NB: als blijkt dat een betaling niet is voltooid moet u zelf weer redirecten naar uw betaalpagina.
| Code | Landnaam |
|---|---|
| 31 | Nederland |
| 32 | Belgie |
| 33 | Frankrijk |
| 34 | Spanje |
| 39 | Italie |
| 41 | Zwitserland |
| 43 | Oosterrijk |
| 44 | UK |
| 49 | Duitsland |
Voorbeelden & Classes
Hieronder hebben we voor u een simpel voorbeeld klaarstaan.
| Omschrijving | Programmeertaal | Auteur | Versie |
|---|---|---|---|
| PHP class | PHP 4.x & PHP 5.x | Mollie | v1.3 |
| Visual Studio project | Visual Studio | Doczero | v1.0 |
| Perl module | Perl | C. Kras | v0.03 |
| ASP voorbeeld | ASP | Find IT Media | v1.0 |
Op deze pagina
- Vereiste kennis
- Hoe werkt de API?
- Stap 1: Betaling aanvragen
- Stap 2: Betaalscherm tonen
- Stap 3: Betaling controleren
- Voorbeelden