Webhook

Process realtime status updates

A webhook is a URL Mollie will call when a payment's status changes, for example from open to paid. At this URL you should place a script that – when it's called – fetches the payment status and processes it, if it has changed. In case the status changed to paid, you should mark the order as paid.

The webhook will be called with a single POST-parameter named id, which for example will contain the value tr_d0b0E3EA3v. You should use that id to actively fetch the payment to find out about it's status. This step seems a little cumbersome but proper security dictates this flow. Since the status is not transmitted in the webhook, fake calls to your webhook will never result in orders being processed without being actually paid.

With each payment creation, you can specify the webhook for that payment by providing the parameter webhookUrl.

In the future we might call your webhook when other events than payment status changes occur. At the moment we only call it when one of your payments reaches a definitive status, when a (partial) refund has taken place or when a chargeback has been received on the payment. Refer to the page about status changes to see for what statusses we call your webhook exactly.

What IPs will the webhook requests be originating from?

Read our support article for more information about the IP addresses that Mollie uses.

Retry Schema

In response to Mollie calling your webhook, you only have to return the HTTP-status 200 OK. Mollie then knows your system correctly processed the request. In case you return a different status – let's say because there's a temporary problem with your hosting service – we'll keep trying for a few hours, allowing you to process the request later on, after your hosting service is restored.

Example

The most important task your webhook script has to complete is to process orders whenever the status of a payment turns out to be paid. The exact working of this process really depends on your product, your business and your website. That's why we can't show you the details of that process. This causes the example below to be incomplete by definition. It's probably a good place to start but be aware you'll have to add the most important part yourself.

The code examples were taken from examples in the Clients we provide. Note that for cURL we can't provide an example since instead of making requests, you'll be serving the request to your webhook to us, which cURL cannot do.

Request code

require_once 'Mollie/API/Autoloader.php';

$mollie = new Mollie_API_Client;
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');

$payment    = $mollie->payments->get($_POST["id"]);

/*
 * The order ID saved in the payment can be used to load the order and update it's
 * status
 */
$order_id = $payment->metadata->order_id;

if ($payment->isPaid())
{
    /*
     * At this point you'd probably want to start the process of delivering the product
     * to the customer.
     */
}
elseif (! $payment->isOpen())
{
    /*
     * The payment isn't paid and isn't open anymore. We can assume it was aborted.
     */
}
# Webhook requests should be processed with server side languages.
# Select PHP or Ruby from the dropdown above, for example.

Response