Secret keys

Secret keys facilitate encrypted communication with Mollie's new API’s. The new API's provide even better security than the previous ones because:

  • All API requests are routed via HTTPS.
    This ensures that the API request can not be viewed by others. HTTPS also guarantees that it is really Mollie that you are communicating with.
  • Authentication is performed by means of a profile_key.
    This means you don't have to include a username of password. If you so choose, you can use a different profile_key per website.
  • Each API request contains a timestamp.
    This means that the request cannot be resubmitted later.
  • All API requests are signed with a secret key.
    This is how our platform knows that the request was made by your website and is authentic, and that the parameters were not changed en route.
  • The API features versions. You can easily switch to a different version, and older versions are supported over a longer period.

Available APIs

The following Mollie APIs use secret keys for security:

How does it work?

Each API method has its own URL, that you can call via HTTP.
https://www.mollie.com/api/api-naam/versie/methode

For instance, if you want to call version v1 of the API method create-payment of the credit card-api, you use the URL:
https://www.mollie.com/api/creditcard/v1/create-payment

Signature

You must sign every API -request with the secret key that belongs to your website profile. For this purpose, we use a SHA1-HMAC, or Hash-based Message Authentication Code with SHA1 as the hashing algorithm.

  1. Take the API endpoint that you call, for instance /api/reseller/account-valid/v1.
  2. Add a ? to it.
  3. Add all parameters and values in alphabetical order, separated by an ampersand (&).
    /api/reseller/v1/account-valid?a=value&partner_id=1234567&profile_key=decafbad&q=mijn%20waarde&timestamp=1454324006&z=value
    Explanation: /api/reseller/account-valid/v1 is the method that is being called, partner_idprofile_key and timestamp are obligatory parameters for all API requests and aq and z are the other parameters for this API request.
    Please take note that you must URL-encode the values for the parameters: my value  becomes my%20value.
  4. Use HMAC to calculate the signature of this API request and add it to the parameter signature. For a key, you use the 'key' that belongs to the website profile, you will find it on the profiles-page. You must chose 'SHA1' as the algorithm. The signature is therefore always 40 characters long, for instance: 6a018490f38ddc1571ab4cd9cd41f5e700c09ce2. Many programming languages feature a standard implementation of the HMAC algorithm. See for instance hash_hmac() for PHP or theHMAC.hexdigest() method for Python.

Tip Want to know more about HMACs? Wikipedia has a detailled description.

Always obligatory parameters

You need to send these obligatory parameters along either via POST or in the query string via GET. These parameters are used to authenticate the API request.

Parameter Explanation Remarks
partner_id Your Partner ID
profile_key Your website profile key, you can retrieve it via the profiles-page. For instance 115ea03a.
timestamp The current time in Unix time. The Unix time is now 1454324006.
signature The signature of the request, see Signature further down. .

Versions

Each Mollie API is equipped with versions. When an API is changed, Mollie launches a new version. Old API versions will remain available for a substantial period.

You can find the version number in the URL between the name of the API and the name of the method that you are calling. The version number is also available from the response you receive from the API.

Example of API result

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

The following elements are present in every API result:

  • <success> Indicates whether a request was successfully executed.
  • <resultcode> Indicates which error occurred during the request.
  • <resultmessage> Provides additional information about the result.

Possible result codes

The following result codes are possible for all API requests:

Code Explanation
10 The request was successfully executed.
31 The parameter partner_id is missing.
22 The parameter timestamp is missing.
23 The parameter signature is missing.
24 The API request was sent via HTTP instead of HTTPS.
25 The submitted website profile cannot be found.
26 The HTTP method is not allowed, use a method listed in the Allowed header.
27 The signature of the API request is incorrect.
28 The timestamp has expired, e.g. is located too far in the past or the future.
29 One of the obligatory parameters is missing
95 The API is temporarily unavailable.
96 One of the parameters contains bites that can not be read as UTF-8.
98 You have no access to the requested object or the API method.
97 The stated object or the requested API method does not exist.
99 An internal error occurred during the processing of the API request.

Downloads & examples

There is no need for you to re-invent the wheel. Mollie has a ready-to-use PHP script lined up for you. Of course, you can also choose to do the integration all on your own if the scripts don't meet your demands.

Are you using node.js? In that case, you can use the open source API-client for node.js, which has been developed by Matthijs van Henten.

Support

Do you need support? Please don't hesitate to contact us.

Was this article helpful?