Skip to content

Hear that a payment changed

A payment finishes after your code has returned: the customer pays later, a bank settles later, a recurring charge runs on the provider’s schedule. The provider tells you by calling a webhook, and the webhook tells your code through IPaymentWebhookHandler.

MapMolliePaymentWebhook maps POST /webhooks/mollie. The callback Mollie sends carries only a payment id, not the payment. The endpoint therefore reads the payment back from Mollie before anything else: a forged callback can name a payment but never change what it says. It then calls your handler with a PaymentUpdate.

public class SubscriptionPayments : IPaymentWebhookHandler
{
public async Task Handle(PaymentUpdate update, CancellationToken cancellationToken)
{
var payment = update.Payment;
if (payment is { Status: PaymentStatus.Paid, Sequence: PaymentSequence.First })
{
// Activate what the customer bought. Metadata carries your own identifiers.
}
}
}

Register it with builder.Services.AddScoped<IPaymentWebhookHandler, SubscriptionPayments>().

Branch on Payment.Status and Payment.Sequence:

Situation Check
The customer paid for the first time Status is Paid and Sequence is First. The MandateId is now set, so you can charge them again.
A one-off purchase was paid Status is Paid and Sequence is OneOff
A subscription or mandate charge was paid Status is Paid and Sequence is Recurring; SubscriptionId is set for a subscription
A payment did not go through Status is Failed, Canceled or Expired

The same update can arrive more than once, so handling must be idempotent. Key your work on Payment.Id and the status, and do nothing when you already applied it.

Throw to have Mollie deliver the update again. Mollie delivers again on anything but a 2xx answer.

Answer When
200 Your handler completed.
400 The callback carried no id.
404 Mollie is not configured: there is no API key.
500 Your handler threw.
502 Mollie could not be read yet.

Keep webhook addresses you already gave Mollie

Section titled “Keep webhook addresses you already gave Mollie”

Anything after the route is handed on as update.Scope. MapMolliePaymentWebhook() also accepts POST /webhooks/mollie/{scope}, which lets an application keep webhook addresses it already gave Mollie and tell them apart in the handler. Scope is null when nothing follows the route.