The Mollie provider for AntelopeJS. It implements portable payments and subscriptions on the Mollie API.
A Mollie payment module for AntelopeJS. It implements the payment interface, and it implements the subscriptions interface on Mollie's own subscriptions.
ajs project modules add @antelopejs/mollieThis module implements two interfaces. You import each one separately, so a module that takes payments does not depend on subscriptions.
| Name | Install command | |
|---|---|---|
| Payment | ajs module imports add payment |
Documentation |
| Subscriptions | ajs module imports add subscriptions |
Documentation |
It needs no other module. It uses no Redis, no database and no API module.
{
"apiKey": "test_…",
"webhookUrl": "https://shop.example.org/payments/mollie"
}apiKey(required) is a Mollie API key. Atest_…key works against Mollie's test mode.webhookUrlis the public URL of your route that passes Mollie's deliveries toVerifyWebhook. The module sends it with every payment and subscription it creates. Without it, Mollie calls nothing, so the module raises no payment event and reports no subscription renewal. Mollie refuses alocalhostURL.accountsholds further Mollie accounts, each with its ownapiKeyandwebhookUrl. The key of each entry is the name that callers pass as the trailingproviderargument of an interface function. The top-level account is the default.apiUrlis the base URL of the Mollie API. It defaults tohttps://api.mollie.com. The test suite points it at a local stand-in.settleTimeoutMsis how longCapturePaymentwaits for Mollie to apply a capture, in every account. It defaults to 10 seconds.0returns as soon as Mollie accepts the capture. Any value but a finite number, 0 or more, makes the module refuse to start.
The module uses API keys only. It does not support Mollie Connect or OAuth.
For payments, Mollie recommends its classic webhooks. A classic delivery posts id=tr_… and nothing else, and Mollie does not sign it. VerifyWebhook reads that payment back from Mollie, and every field of the event comes from that read. A delivery that names no payment, or names a payment that Mollie does not have on the account, rejects with WebhookVerificationError. When Mollie cannot be reached, VerifyWebhook rejects with a plain PaymentError, so your route answers with an error and Mollie delivers again.
import { createServer } from "node:http";
import { buffer } from "node:stream/consumers";
import {
type PaymentEvent,
VerifyWebhook,
WebhookVerificationError,
} from "@antelopejs/interface-payment";
async function handle(event: PaymentEvent): Promise<void> {
console.log(`${event.type} ${event.id}`);
}
// Serve this at `webhookUrl`.
createServer(async (request, response) => {
try {
const event = await VerifyWebhook({
body: await buffer(request),
headers: request.headers,
});
if (event) await handle(event); // undefined: a genuine delivery with nothing to report
response.writeHead(200).end();
} catch (error) {
response
.writeHead(error instanceof WebhookVerificationError ? 403 : 500)
.end();
}
}).listen(8080);VerifyWebhook takes the unparsed body, so the route reads it raw. The route answers 403 only for a delivery that VerifyWebhook could not establish as genuine. Any other failure answers 500, and Mollie delivers again.
The module raises only payment.* events. A classic delivery names a payment, never the refund or chargeback that caused it, so the module never raises refund.succeeded, refund.failed or dispute.opened. Read a refund back with GetRefund, and a payment's refunded total with GetPayment. Webhooks explains why.
- Every payer-present payment is a redirect.
CreatePaymentandCreateCheckoutSessionreturnrequires_actionwith Mollie's checkout URL. A checkout session and its payment share one identifier. - Saved methods are Mollie mandates. A payment with
savePaymentMethodcreates one, as Mollie'sfirstpayment. A saved card is listed once its payment readssucceeded: the module waits up to 5 seconds for Mollie to turn the mandate valid. A saved method belongs to one customer. Detaching it revokes the mandate, and Mollie then cancels every subscription that charges it. - Off-session charges settle later. A charge against a saved method comes back
pending. Mollie reportssucceeded,authorizedorfailedafterwards, through the webhook. A decline is then afailedpayment, not the result of the creating call. - Holding funds works only for some methods.
authorizeOnlyneeds a method that Mollie can capture by hand: cards, Klarna, Billie, Riverty, Vipps, MobilePay, PayPal and Billink. The module refuses any other method instead of letting Mollie capture at once, and a hosted page offers only those methods. - Captures settle after the call. Mollie accepts a capture as
pendingand applies it about a second later.CapturePaymentwaits for that up tosettleTimeoutMs. If Mollie has not applied the capture by then,CapturePaymentreturns the paymentpending, withamountCapturedset to the amount being captured. A failed read while it waits returnspendingthe same way. A capture Mollie fails rejects with aPaymentErrorwhoseproviderCodeiscapture_failed. A second capture of the same payment, or a cancellation, while the first capture is in flight or applied rejects withInvalidPaymentStateErrorbefore it reaches Mollie. - Idempotency keys last one hour at Mollie.
RefundPayment,CapturePaymentandCreateSubscriptionfind their earlier result by key at any time. For other calls, a replay within the hour returns the original result. After the hour, Mollie treats the same key as a new request. - No
refund.*ordispute.openedevents. See Webhooks.
Subscriptions are Mollie's own. Mollie holds the schedule and creates every renewal payment. Subscriptions has the full mapping. In short:
CreateSubscriptioncharges the first period. It charges a payment whose metadata names the subscription underantelope.subscription, and Mollie's own schedule starts one period later. Mollie reports a declined charge after the call returns, so the subscription is createdactiveand goespast_dueif that charge fails. Nothing retries that first charge.- Mollie schedules by calendar date. The module rounds a trial end or a billing anchor up to the start of the next day in Europe/Amsterdam, and reports that time. A period runs from one such midnight to the next.
- Mollie owns the retries. Mollie retries a failed renewal up to five times, then cancels the subscription. The module reports it
canceledwithendReason: "payment_failed". - Cancelling at period end stops Mollie at once. The module reports the subscription as running until the end of the period it paid for. Mollie raises nothing when that period ends, so neither does this module.
- Events. The call that causes
subscription.createdorsubscription.canceledraises it. A handler that throws makes that call reject, and replaying the call's idempotency key raises the event again. The payment webhook raisessubscription.payment_succeededandsubscription.payment_failed. - About 600 bytes of subscription metadata. Mollie keeps 1,024 bytes of metadata per subscription, and the module keeps room in them to record the first charge and a cancellation.
CreateSubscriptionrejects metadata that would leave no such room withInvalidSubscriptionRequestError. With a reference and an idempotency key of up to 64 bytes each as JSON text, where a character JSON escapes, such as"or\, counts as its escape, 600 bytes of metadata as JSON always fit. - Only this module's subscriptions. The module does not list, read, change or raise events for subscriptions made in the dashboard or by other code on the account, and it does not mark their charges.
- Replay a failed creation with its idempotency key. The subscription may already exist at Mollie, and Mollie will charge it from the next period. Replay once the call has failed, not while it runs: a replay that overlaps it can cancel the subscription it returns if the first charge fails in between.
Wire @antelopejs/payment-subscriptions, and add disabledExports: ["@antelopejs/interface-subscriptions"] to this module's entry.
| Package | Supported | Tested with |
|---|---|---|
@antelopejs/interface-core |
>=0.5.1 <0.6.0 |
0.5.1 |
@antelopejs/interface-payment |
>=0.2.0 <0.3.0 |
0.2.1 |
@antelopejs/interface-subscriptions |
>=0.1.0 <0.2.0 |
0.1.2 |
This package belongs to AntelopeJS, the TypeScript framework where modules depend on contracts and the application chooses the provider. The open-source back office AntelopeJS DMS is built on it.
| Area | Contracts | Providers |
|---|---|---|
| API | interface-api · interface-api-util · interface-data-api |
api |
| Auth | interface-auth |
auth-jwt |
| Database | interface-database · interface-database-decorators · interface-database-catalog · interface-mongodb · interface-rethinkdb |
postgres · mysql · mongodb · rethinkdb |
| Redis | interface-redis · interface-redis-scheduler |
redis |
interface-email |
nodemailer · brevo |
|
| File storage | interface-file-storage |
file-storage-local · file-storage-s3 |
| Payments | interface-payment · interface-subscriptions · interface-stripe |
stripe · mollie · checkout-com · payment-subscriptions |
This project is licensed under the Apache License 2.0. See the LICENSE file for details.