Geheime sleutels

Geheime sleutels maken het mogelijk versleuteld te communiceren met de nieuwe Mollie API’s. De nieuwe API’s bieden een verbeterde beveiliging ten opzichte van eerdere API’s, want:

  • Alle API-verzoeken gaan via HTTPS.
    Dit zorgt ervoor dat het API-verzoek niet bekeken kan worden door anderen. Ook weet u dankzij HTTPS zeker dat u met Mollie communiceert.
  • Authenticatie gebeurt door middel van een profile_key.
    U hoeft dus geen gebruikersnaam of wachtwoord mee te sturen. U kunt eventueel per website een andere profile_key gebruiken.
  • Elk API-verzoek bevat timestamp.
    Waardoor het verzoek niet later nog eens nagespeeld kan worden.
  • Alle API-verzoeken zijn ondertekend met een geheime sleutel.
    Hierdoor weet ons platform dat het verzoek door uw website is gedaan en authentiek is, en dat de parameters niet onderweg zijn aangepast.
  • De API is voorzien van versies. U kunt gemakkelijk overschakelen naar een andere versie, en oude versies blijven lange tijd ondersteund.

Beschikbare API’s

De volgende Mollie API’s gebruiken geheime sleutels voor beveiliging:

Hoe werkt het?

Elke API methode heeft een eigen URL die u doormiddel van HTTP aan kunt roepen.
https://www.mollie.com/api/api-naam/versie/methode

Als u bijvoorbeeld versie v1 van de API-methode create-payment van de creditcard-api wilt aanroepen, gebruikt u de URL:
https://www.mollie.com/api/creditcard/v1/create-payment

Ondertekening

U dient elk API-verzoek te ondertekenen met behulp van de geheime sleutel die bij uw websiteprofiel hoort. We gebruiken hiervoor een SHA1-HMAC, oftewel een Hash-based Message Authentication Code met SHA1 als hashing algoritme.

  1. Neem de API endpoint die u aanroept, bijvoorbeeld /api/reseller/account-valid/v1.
  2. Voeg hier een ? aan toe.
  3. Voeg hier alle parameters en waardes in alfabetische volgorde aan toe, gescheiden door een ampersand (&).
    /api/reseller/v1/account-valid?a=value&partner_id=1234567&profile_key=decafbad&q=mijn%20waarde&timestamp=1454324006&z=value
    Toelichting: /api/reseller/account-valid/v1 is de methode die aangeroepen wordt, partner_idprofile_key en timestamp zijn verplichte parameters voor alle API-verzoeken en aq en z zijn de overige parameters voor dit API-verzoek.
    Let er op dat u de waardes voor de parameters moet url-encodenmijn waarde wordt mijn%20waarde.
  4. Bereken met behulp van HMAC de ondertekening van dit API-verzoek en voeg dit toe in de parameter signature. Als sleutel gebruikt u de “key” die bij het websiteprofiel hoort, u vindt deze op de profielen-pagina. U dient “SHA1” als algoritme te kiezen. De signature is dan ook altijd 40 karakters, bijvoorbeeld: 6a018490f38ddc1571ab4cd9cd41f5e700c09ce2.Veel programmeertalen hebben een standaard implemenatie van het HMAC algoritme, zie bijvoorbeeld hash_hmac() voor PHP of deHMAC.hexdigest() methode voor Python.

Tip Meer weten over HMACs? Wikipedia bevat een gedetailleerde omschrijving.

Altijd verplichte parameters

U dient deze verplichte parameters ofwel via POST, ofwel in de querystring via GET meesturen. Deze parameters worden gebruikt om het API-verzoek te authenticeren.

Parameter Uitleg Opmerkingen
partner_id Uw Partner ID
profile_key Uw websiteprofiel-key, u kunt deze inzien via de profielen-pagina. Bijvoorbeeld 115ea03a.
timestamp De huidige tijd in Unix time. De Unix time is nu 1454324006.
signature De ondertekening van het verzoek, zie Ondertekening verderop. .

Versies

Elke Mollie API is voorzien van versies. Wanneer een API aangepast wordt, zal Mollie een nieuwe versie lanceren. Oude API-versies blijven dan nog geruime tijd beschikbaar.

Het versienummer vindt u in de URL tussen de naam van de API en de naam van de methode die u aanroept. Ook is het versienummer beschikbaar in het antwoord wat u van de API krijgt.

Voorbeeld API resultaat

<?xml version="1.0"?>
<response version="v1">
 <success>true</success>
 <resultcode>10</resultcode>
 <resultmessage>It works!</resultmessage>
</response>

De volgende elementen zijn in elk API resultaat aanwezig:

  • <success> Geeft aan of een verzoek succesvol uitgevoerd is.
  • <resultcode> Geeft aan welke fout er opgetreden is tijdens het verzoek.
  • <resultmessage> Geeft extra informatie over het verzoek.

Mogelijke resultaatcodes

Voor alle API-verzoeken geldt dat de volgende resultaatcodes mogelijk zijn:

Code Uitleg
10 Het verzoek is met succes uitgevoerd.
31 De parameter partner_id ontbreekt.
22 De parameter timestamp ontbreekt.
23 De parameter signature ontbreekt.
24 Het API-verzoek is verzonden via HTTP in plaats van HTTPS.
25 Het opgegeven websiteprofiel kan niet gevonden worden.
26 De HTTP methode is niet toegestaan, gebruik een methode die is aangegeven in de Allowed header.
27 De ondertekening van het API-verzoek is niet correct.
28 De timestamp is verlopen, e.g. deze ligt te ver in het verleden of toekomst.
29 Eén van de verplichte parameters ontbreekt
95 De API is tijdelijk niet beschikbaar.
96 Eén van de parameters bevat bytes die niet als UTF-8 begrepen kunnen worden.
98 U heeft geen toegang het opgevraagde object of de API-methode.
97 Het opgegeven object of de aangevraagde API-methode bestaat niet.
99 Er is een interne fout opgetreden tijdens het verwerken van het API-verzoek.

Downloads & voorbeelden

U hoeft zelf niet opnieuw het wiel uit te vinden. Mollie heeft een kant-en-klaar PHP script voor u klaar staan. Natuurlijk kunt u er ook voor kiezen om de integratie geheel zelf te doen als de scripts niet voldoen aan uw eisen.

Maakt u gebruik van node.js? Dan kunt u gebruik maken van de open source API-client voor node.js, die ontwikkeld is door Matthijs van Henten.

Ondersteuning

Heeft u ondersteuning nodig? Neemt u dan gerust contact met ons op.