@antelopejs/mollie 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/LICENSE +190 -0
  2. package/README.md +123 -2
  3. package/dist/accounts.d.ts +17 -0
  4. package/dist/accounts.js +41 -0
  5. package/dist/accounts.js.map +1 -0
  6. package/dist/implementations/payment/checkout.d.ts +3 -0
  7. package/dist/implementations/payment/checkout.js +129 -0
  8. package/dist/implementations/payment/checkout.js.map +1 -0
  9. package/dist/implementations/payment/customers.d.ts +6 -0
  10. package/dist/implementations/payment/customers.js +79 -0
  11. package/dist/implementations/payment/customers.js.map +1 -0
  12. package/dist/implementations/payment/errors.d.ts +10 -0
  13. package/dist/implementations/payment/errors.js +71 -0
  14. package/dist/implementations/payment/errors.js.map +1 -0
  15. package/dist/implementations/payment/index.d.ts +5 -0
  16. package/dist/implementations/payment/index.js +27 -0
  17. package/dist/implementations/payment/index.js.map +1 -0
  18. package/dist/implementations/payment/instruments.d.ts +19 -0
  19. package/dist/implementations/payment/instruments.js +138 -0
  20. package/dist/implementations/payment/instruments.js.map +1 -0
  21. package/dist/implementations/payment/mapping.d.ts +10 -0
  22. package/dist/implementations/payment/mapping.js +202 -0
  23. package/dist/implementations/payment/mapping.js.map +1 -0
  24. package/dist/implementations/payment/payments.d.ts +12 -0
  25. package/dist/implementations/payment/payments.js +270 -0
  26. package/dist/implementations/payment/payments.js.map +1 -0
  27. package/dist/implementations/payment/refunds.d.ts +3 -0
  28. package/dist/implementations/payment/refunds.js +76 -0
  29. package/dist/implementations/payment/refunds.js.map +1 -0
  30. package/dist/implementations/payment/saved-method.d.ts +5 -0
  31. package/dist/implementations/payment/saved-method.js +83 -0
  32. package/dist/implementations/payment/saved-method.js.map +1 -0
  33. package/dist/implementations/payment/webhooks.d.ts +2 -0
  34. package/dist/implementations/payment/webhooks.js +72 -0
  35. package/dist/implementations/payment/webhooks.js.map +1 -0
  36. package/dist/implementations/shared/subscription-of-payment.d.ts +7 -0
  37. package/dist/implementations/shared/subscription-of-payment.js +47 -0
  38. package/dist/implementations/shared/subscription-of-payment.js.map +1 -0
  39. package/dist/implementations/subscriptions/calendar.d.ts +20 -0
  40. package/dist/implementations/subscriptions/calendar.js +160 -0
  41. package/dist/implementations/subscriptions/calendar.js.map +1 -0
  42. package/dist/implementations/subscriptions/changes.d.ts +5 -0
  43. package/dist/implementations/subscriptions/changes.js +140 -0
  44. package/dist/implementations/subscriptions/changes.js.map +1 -0
  45. package/dist/implementations/subscriptions/creation.d.ts +4 -0
  46. package/dist/implementations/subscriptions/creation.js +235 -0
  47. package/dist/implementations/subscriptions/creation.js.map +1 -0
  48. package/dist/implementations/subscriptions/errors.d.ts +7 -0
  49. package/dist/implementations/subscriptions/errors.js +42 -0
  50. package/dist/implementations/subscriptions/errors.js.map +1 -0
  51. package/dist/implementations/subscriptions/events.d.ts +9 -0
  52. package/dist/implementations/subscriptions/events.js +74 -0
  53. package/dist/implementations/subscriptions/events.js.map +1 -0
  54. package/dist/implementations/subscriptions/index.d.ts +7 -0
  55. package/dist/implementations/subscriptions/index.js +26 -0
  56. package/dist/implementations/subscriptions/index.js.map +1 -0
  57. package/dist/implementations/subscriptions/mapping.d.ts +3 -0
  58. package/dist/implementations/subscriptions/mapping.js +133 -0
  59. package/dist/implementations/subscriptions/mapping.js.map +1 -0
  60. package/dist/implementations/subscriptions/records.d.ts +40 -0
  61. package/dist/implementations/subscriptions/records.js +225 -0
  62. package/dist/implementations/subscriptions/records.js.map +1 -0
  63. package/dist/index.d.ts +9 -0
  64. package/dist/index.js +57 -0
  65. package/dist/index.js.map +1 -0
  66. package/dist/mollie/amounts.d.ts +5 -0
  67. package/dist/mollie/amounts.js +85 -0
  68. package/dist/mollie/amounts.js.map +1 -0
  69. package/dist/mollie/client.d.ts +26 -0
  70. package/dist/mollie/client.js +136 -0
  71. package/dist/mollie/client.js.map +1 -0
  72. package/dist/mollie/errors.d.ts +16 -0
  73. package/dist/mollie/errors.js +35 -0
  74. package/dist/mollie/errors.js.map +1 -0
  75. package/dist/mollie/fields.d.ts +6 -0
  76. package/dist/mollie/fields.js +25 -0
  77. package/dist/mollie/fields.js.map +1 -0
  78. package/dist/mollie/guards.d.ts +16 -0
  79. package/dist/mollie/guards.js +63 -0
  80. package/dist/mollie/guards.js.map +1 -0
  81. package/dist/mollie/ids.d.ts +20 -0
  82. package/dist/mollie/ids.js +51 -0
  83. package/dist/mollie/ids.js.map +1 -0
  84. package/dist/mollie/json.d.ts +3 -0
  85. package/dist/mollie/json.js +31 -0
  86. package/dist/mollie/json.js.map +1 -0
  87. package/dist/mollie/metadata.d.ts +21 -0
  88. package/dist/mollie/metadata.js +121 -0
  89. package/dist/mollie/metadata.js.map +1 -0
  90. package/dist/mollie/resources.d.ts +13 -0
  91. package/dist/mollie/resources.js +132 -0
  92. package/dist/mollie/resources.js.map +1 -0
  93. package/dist/mollie/types.d.ts +119 -0
  94. package/dist/mollie/types.js +3 -0
  95. package/dist/mollie/types.js.map +1 -0
  96. package/docs/1.introduction.md +52 -0
  97. package/docs/2.payments.md +160 -0
  98. package/docs/3.webhooks.md +55 -0
  99. package/docs/4.subscriptions.md +109 -0
  100. package/docs/5.testing.md +67 -0
  101. package/package.json +86 -4
  102. package/skills/mollie/SKILL.md +55 -0
  103. package/skills/mollie/cases.json +49 -0
@@ -0,0 +1,55 @@
1
+ ---
2
+ title: Webhooks
3
+ description: Why the Mollie module verifies a delivery by reading the payment back, which events it raises, and why it raises no refund or dispute events.
4
+ mode: explanation
5
+ ---
6
+
7
+ ## What Mollie sends to your route
8
+
9
+ For payments, Mollie uses "classic" webhooks. Mollie calls the `webhookUrl` that the module gave when it made the payment, or the subscription that created the payment. The body is form-encoded with one field, `id=tr_…`, and nothing else. Mollie does not sign the delivery. Mollie's own guidance is to read the payment back and act on what the API says, never on the request (Mollie: _Webhooks_).
10
+
11
+ Mollie calls the same URL when the payment changes status, when one of its refunds reaches `processing`, `refunded` or `failed`, and when Mollie receives a chargeback. Every one of those deliveries carries the payment's id.
12
+
13
+ ## How `VerifyWebhook` establishes a delivery
14
+
15
+ 1. `VerifyWebhook` reads the body as a form and takes only `id`. A body without a `tr_…` id rejects with `WebhookVerificationError`.
16
+ 2. `VerifyWebhook` reads the payment back from Mollie with the account's key. The `provider` argument chooses the account. If Mollie has no such payment on the account, the delivery rejects with `WebhookVerificationError`.
17
+ 3. If Mollie cannot be reached, or answers with any other error, the call rejects with a plain `PaymentError`. Your route then answers with a server error and Mollie delivers again. A 403 would read an outage as a forgery.
18
+
19
+ **Every field of the event comes from the payment read back.** That covers the type, the payment, its status, its amounts and its metadata. The body only points at a payment. A body that also claims `status=paid` changes nothing, and a forged delivery that names a real payment yields that payment's real state. The payment interface sets this rule for providers that verify by reading the record back instead of by signature.
20
+
21
+ ## Which events
22
+
23
+ | Payment status at Mollie | Event | Event id |
24
+ | ------------------------ | -------------------- | ------------------------- |
25
+ | `pending` | `payment.pending` | `<payment id>:pending` |
26
+ | `authorized` | `payment.authorized` | `<payment id>:authorized` |
27
+ | `paid` | `payment.succeeded` | `<payment id>:paid` |
28
+ | `failed` | `payment.failed` | `<payment id>:failed` |
29
+ | `canceled` | `payment.canceled` | `<payment id>:canceled` |
30
+ | `expired` | `payment.canceled` | `<payment id>:expired` |
31
+ | `open` | none (`undefined`) | |
32
+
33
+ The module derives the event id from the payment and its status, so every delivery of one state carries the same id, and de-duplicating on the id is enough. `createdAt` is when Mollie recorded that status, from `authorizedAt`, `paidAt`, `failedAt`, `canceledAt` or `expiredAt`. For `pending`, it is when Mollie created the payment.
34
+
35
+ A payment made for a subscription is either the first period, whose metadata names the subscription under `antelope.subscription`, or a renewal, which Mollie links to the subscription with `subscriptionId`. Its delivery also raises the subscription's `payment_succeeded` or `payment_failed` event (see [Subscriptions](./4.subscriptions.md)). If a subscription handler throws, `VerifyWebhook` rejects, and Mollie delivers again.
36
+
37
+ ## What is not raised, and why
38
+
39
+ **The module never raises `refund.succeeded`, `refund.failed` or `dispute.opened`.** A classic delivery for a refund or a chargeback names the payment, not the refund or the chargeback, and nothing in it says which of the payment's changes caused it. `VerifyWebhook` returns one event per delivery. Picking a refund out of the payment read back would be a guess. One delivery can follow a refund settling, a chargeback arriving, or the payment's own status changing, and a wrong guess swallows the payment's own event. So the module reports the delivery that follows a refund as the payment's own state, under the same id as before, and de-duplication drops it.
40
+
41
+ Read a refund's outcome with `GetRefund`, and a payment's refunded total with `GetPayment`.
42
+
43
+ ### Why not Mollie's next-gen webhooks
44
+
45
+ Mollie also has signed "next-gen" webhooks (`X-Mollie-Signature`, an HMAC-SHA256 of the body), with event types for refunds and chargebacks. They do not fit this module today (Mollie: _Next-gen webhooks_):
46
+
47
+ - Mollie itself recommends classic webhooks for payment updates.
48
+ - Creating a next-gen webhook through the API needs an advanced access token or OAuth, and this module uses API keys only. A next-gen webhook created in the dashboard delivers a _simple_ payload, with ids and a type but without the record. A refund cannot be read without its payment's id.
49
+ - Mollie marks the refund and chargeback event types as beta, and does not document whether next-gen events cover subscription payments.
50
+
51
+ When those facts change, signed deliveries for refunds and chargebacks are the way to raise `refund.*` and `dispute.opened`.
52
+
53
+ ## Testing a webhook route
54
+
55
+ Mollie refuses a `localhost` webhook URL. In test mode, Mollie still delivers, to a public URL. To receive deliveries on your machine, expose your route through a tunnel such as ngrok.
@@ -0,0 +1,109 @@
1
+ ---
2
+ title: Subscriptions
3
+ description: How the Mollie module maps the subscriptions interface onto Mollie's Subscriptions API, from creation and the first charge to time, statuses, cancellation and events.
4
+ mode: reference
5
+ ---
6
+
7
+ Subscriptions are Mollie's own. Mollie keeps the schedule and creates each renewal payment against the subscription's mandate. This module maps the subscriptions interface onto Mollie's Subscriptions API, and reads Mollie's renewal payments back through the payment webhook.
8
+
9
+ ## Creating
10
+
11
+ `CreateSubscription` checks the request with the interface's `ValidateSubscriptionRequest`, and refuses an interval that Mollie cannot bill (see [Intervals](#intervals)). Then it does the following:
12
+
13
+ 1. It reads the payment method's mandate. The mandate must belong to the request's customer, be `valid`, and be usable without the payer. Otherwise the request is invalid (`InvalidSubscriptionRequestError`), and the module creates nothing.
14
+ 2. It looks for a subscription of this customer that was created with the same idempotency key, and resumes it if there is one.
15
+ 3. Otherwise it creates the Mollie subscription.
16
+ 4. Without a trial or a billing anchor, it charges the first period itself and records the charge on the subscription.
17
+
18
+ ### The first period
19
+
20
+ Mollie creates subscription payments on the schedule's dates, after the call that made the subscription has returned. The interface wants the first period charged before `CreateSubscription` resolves. So without a trial or an anchor, Mollie's schedule starts one period from today, and the module charges the first period as an ordinary recurring payment whose metadata names the subscription under the module's own key, `antelope.subscription`. That charge is the subscription's `latestPayment` until Mollie's first renewal.
21
+
22
+ Mollie settles that charge after the call returns (see [Payments](./2.payments.md)), so the subscription is created `active` with the charge still pending. If the charge later fails, the subscription is `past_due` and the module raises `subscription.payment_failed`. Mollie retries the payments it creates. Mollie does not know about this one, so **nothing retries a failed first charge**. The subscription stays `past_due` until Mollie's first renewal succeeds, or until you cancel it. If Mollie declines the charge in the creating response itself, the module cancels the subscription at Mollie and hides it from the interface, and `CreateSubscription` rejects with `SubscriptionPaymentError`. A replay of its key rejects the same way, and first cancels the subscription at Mollie if that cancel had failed. The module hides the subscription only once Mollie has canceled it. If the call fails before that, Mollie still bills the subscription, so the interface lists and reads it as `past_due`, with the declined charge as its latest payment. A replay of the key, or `CancelSubscription`, cancels it.
23
+
24
+ Only the call that receives Mollie's answer to the charge can tell a decline from a later failure. A replay that finds the first charge already failed reads the subscription again. If a call has recorded the charge by then, the replay returns the subscription, `past_due`. Otherwise it cancels the subscription at Mollie and rejects with `SubscriptionPaymentError`. If no call recorded the decline either, the cancelled subscription stays listed as `canceled`. That happens when the call that charged failed before it could record the decline, and also when it was still running: its record of the decline then reaches a subscription the replay already cancelled, which Mollie no longer lets anyone update. Mollie bills neither.
25
+
26
+ ### Replays
27
+
28
+ Mollie keeps an idempotency key for one hour. `CreateSubscription` does not depend on that. The module stores the key on the subscription, so a replay at any later time finds the subscription instead of creating it again. The replay also finds the first charge among the customer's 250 most recent payments, instead of charging again.
29
+
30
+ A creation can fail partway, because of the network, Mollie or the process. **Replay a failed creation with the same key.** The Mollie subscription may already exist, and Mollie will charge it from the next period. A caller that gives up instead, or retries under a new key, leaves a subscription that charges and that no one asked for.
31
+
32
+ Replay only after the call you repeat has failed. A replay that runs while that call is still recording the first charge can cancel the subscription that call returns, if the charge fails in between. The subscription then stays listed, as `canceled`.
33
+
34
+ ## Time
35
+
36
+ Mollie's `startDate` and `nextPaymentDate` are calendar dates, and Mollie charges at some point on that day. The module reads them as days in Europe/Amsterdam, because Mollie's documentation names no time zone:
37
+
38
+ - The module rounds a **trial end** or **billing anchor** up to the start of the next Amsterdam day, so nothing is charged before the time asked for. The subscription reports that rounded time as `trialEnd` and `currentPeriodEnd`. A time that already falls on an Amsterdam midnight stays as it is.
39
+ - A **period** runs from one Amsterdam midnight to the midnight of the next schedule date. Across a daylight-saving change, a period is an hour longer or shorter than whole days.
40
+ - Month periods keep the anchor's day of the month and clamp to the last day of a shorter month, as Mollie does ("we will charge on the last date of the month").
41
+
42
+ ## Intervals
43
+
44
+ | Interface | Mollie | Longest |
45
+ | ----------- | ----------- | ------- |
46
+ | `day` × n | `n days` | 365 |
47
+ | `week` × n | `n weeks` | 52 |
48
+ | `month` × n | `n months` | 12 |
49
+ | `year` × 1 | `12 months` | 1 |
50
+
51
+ The module refuses a longer period with `InvalidSubscriptionRequestError`. It stores the interval and its count with the subscription, so a year reads back as a year.
52
+
53
+ Anything holding the API key can change that stored interval. When it holds an interval or a count the module could not have written, such as a count of 0, -1, 1.5 or past the longest above, the subscription reads with the interval Mollie bills instead: `n days` as `day` × n, `n weeks` as `week` × n and `n months` as `month` × n. Mollie documents only these forms, within the longest above. If Mollie ever reports another, such as `0 days` or `1 year`, while the stored interval was changed too, the module cannot tell the period: `GetSubscription`, `CancelSubscription` and a replay of its `CreateSubscription` reject with a `SubscriptionError` that names the subscription, and `ListSubscriptions` leaves it out so the customer's other subscriptions still list. A stored cancellation end that is not a whole number of milliseconds from 1970 to the last day of 9999 drops the cancellation record, and the subscription then reads as ended when Mollie cancelled it.
54
+
55
+ ## Statuses
56
+
57
+ | Situation | Status |
58
+ | ----------------------------------------------------------------------- | ---------- |
59
+ | Mollie `active` or `pending`, before a trial ends, nothing charged | `trialing` |
60
+ | Mollie `active` or `pending`, latest payment not failed | `active` |
61
+ | Latest payment `failed`, `canceled` or `expired`, or Mollie `suspended` | `past_due` |
62
+ | Mollie `canceled` or `completed` | `canceled` |
63
+
64
+ After a failed renewal, Mollie retries up to five times, then cancels the subscription. Some SEPA reasons cancel it at once (Mollie: _Recurring payments_). A subscription that Mollie ended that way reports `endReason: "payment_failed"`. A subscription ended by a cancellation, by revoking its mandate or by deleting the customer reports `"requested"`. At Mollie, revoking a mandate cancels every subscription that charges it, and deleting a customer cancels all of the customer's subscriptions.
65
+
66
+ `vendorData` holds the raw Mollie status, start date, next payment date and interval.
67
+
68
+ ## Cancelling
69
+
70
+ Mollie cancels a subscription at once, and nobody can change a cancelled subscription afterwards. Before cancelling, the module records on the subscription how it was cancelled and under which idempotency key. That record takes room in the subscription's metadata, which creation keeps for a key of up to 64 bytes (see [Metadata](#metadata)).
71
+
72
+ - **`now`.** The module cancels the subscription at Mollie. It reports `canceled`, with `endedAt` from Mollie and `endReason: "requested"`.
73
+ - **`period_end`.** The module cancels the subscription at Mollie at once, so nothing more is charged, and records it as ending when the current period ends. Until then the subscription reports its status and `cancelAtPeriodEnd: true`. From then on, it reports `canceled` with `endedAt` at that period end. Asking again is not an error.
74
+ - **`now` after `period_end`.** Mollie no longer accepts changes to the subscription, so the module records the early end on the customer, in the customer's metadata beside your own, and `GetCustomer` returns the same metadata before and after. Metadata another writer set keeps its keys. If that writer stored a string, a number or a list, which is not an object, the module moves the value into its own record, under `antelope.kept`, so Mollie still holds it but the other writer now finds an object. A string stays a string there even when it holds a JSON object, and `GetCustomer` reads it as it read it before. If that writer's object holds a `metadata` object of its own, the module marks its record `antelope.foreign`, so `GetCustomer` keeps returning the object's own string entries. Each subscription ended this way takes one entry of about 40 bytes, with its end time and a short hash of the idempotency key, and the module never removes it. Mollie keeps about 1 kB of metadata per customer, so a customer has room for about twenty such cancellations, fewer when the customer carries metadata of its own, and fewer still when the module has to move that metadata under `antelope.kept` or mark it `antelope.foreign`, which adds its size and a few bytes more. Before it writes, the module counts the UTF-8 bytes of the metadata that would result, and when they pass 1,024 it rejects `CancelSubscription` with a `SubscriptionError` that says the customer's metadata leaves no room to record the early end, and sends nothing: the customer's metadata stays as it is and the subscription keeps reporting its scheduled end. Free room by shortening the customer's own metadata, then cancel again. Mollie documents "approximately 1kB" and, in test mode, refused a write of 1,096 bytes with 422 "The metadata storage is currently limited to 1024 bytes" and accepted one of 1,000. Whether it counts bytes or characters, and what it does within a few bytes of 1,024, is not documented, so the module counts UTF-8 bytes against 1,024. Removing an entry would make that subscription report its scheduled end instead of its early one. Each early end rewrites the customer's metadata from a read just before it, and Mollie has no conditional update. So the module records one customer's early ends one at a time, but only within one process. Two processes, such as two replicas of your app, that end subscriptions of the same customer early at the same moment can still erase one of the two entries, and that subscription then reports its scheduled end.
75
+ - **Repeats.** A repeated cancellation under the same key returns the subscription. Under another key, on an ended subscription, it rejects with `InvalidSubscriptionStateError`.
76
+
77
+ Changing the payment method of a subscription set to end at period end rejects with `InvalidSubscriptionStateError`. Mollie will not change it, and nothing will be charged again.
78
+
79
+ ## Events
80
+
81
+ | Event | Raised by | Event id |
82
+ | -------------------------------- | --------------------------------------------------------- | -------------------------------------- |
83
+ | `subscription.created` | `CreateSubscription`, and its replays | `<subscription>:subscription.created` |
84
+ | `subscription.canceled` | `CancelSubscription` (`now`, or `now` after `period_end`) | `<subscription>:subscription.canceled` |
85
+ | `subscription.payment_succeeded` | the webhook of a paid charge | `<subscription>:<payment>:paid` |
86
+ | `subscription.payment_failed` | the webhook of a failed, cancelled or expired charge | `<subscription>:<payment>:<status>` |
87
+ | `subscription.canceled` | the webhook of a failed charge after Mollie gave up | `<subscription>:subscription.canceled` |
88
+
89
+ Mollie sends no webhook about a subscription itself, only about its payments. That has three consequences:
90
+
91
+ - A call raises its own `created` or `canceled` event, to the handlers registered in that instance. A handler that throws makes the call reject. Replaying the call's idempotency key raises the event again, under the same id.
92
+ - **A `period_end` cancellation raises nothing when the period runs out.** Nothing happens at Mollie then, and this module has no clock. Read the subscription, or act on `cancelAtPeriodEnd` and `currentPeriodEnd` yourself.
93
+ - A subscription that Mollie cancels without a failed payment to report it, such as after a revoked mandate or a deleted customer, raises no `canceled` event.
94
+
95
+ A payment event carries the subscription as read when the module verifies the delivery, which can be later than the state the event is about.
96
+
97
+ ## Metadata
98
+
99
+ Mollie keeps 1,024 bytes of metadata per subscription, counted as the bytes of its JSON text. In test mode it accepted a subscription's metadata of 1,024 bytes and refused one of 1,025, with an HTTP 500 that says "The service is currently unavailable", not an error that names the metadata. The module's own record (reference, idempotency key, interval, first charge, cancellation) shares those bytes with a subscription's own `metadata`, and the module adds the first charge and the cancellation after creating the subscription. So `CreateSubscription` counts, before it creates anything at Mollie, the metadata the subscription would hold after its widest later writes: a first charge with a payment id of up to 32 characters (Mollie's test mode gives 24), and a cancellation at the period end under an idempotency key of up to 64 bytes. When that passes 1,024 bytes, it rejects with `InvalidSubscriptionRequestError`, whose message gives the bytes your `metadata` takes and the most it may take with this reference and idempotency key. 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, at least 600 bytes are left for your `metadata`, as JSON text; with 36-character UUIDs, 660. A replay of a creation that already happened returns that subscription without counting again.
100
+
101
+ A cancellation under an idempotency key longer than 64 bytes may not fit. Then, and for a subscription created with more metadata before the module kept this room, `CancelSubscription` rejects with a `SubscriptionError` that names the subscription and says its metadata leaves no room to record the cancellation, and sends nothing: the subscription stays as it was, and Mollie keeps billing it. Cancel again with a shorter key. A subscription that has no room even then needs its metadata shortened at Mollie, or cancelling in Mollie's dashboard.
102
+
103
+ ## Renewal payments
104
+
105
+ Mollie forwards a subscription's metadata to every payment it creates for it (Mollie: _Create subscription_, `metadata`). So a renewal reports the subscription's `reference` and the subscription's own metadata. The module ties a renewal to its subscription through the `subscriptionId` Mollie sets on the payment.
106
+
107
+ ## Only this module's subscriptions
108
+
109
+ A subscription counts as this module's when it carries the module's own record in its metadata. Others on the account may come from the dashboard, a plugin or other code. The module does not list them, `GetSubscription` does not find them, and the interface cannot cancel or change them. They raise no events, and the module does not treat their payments as subscription charges.
@@ -0,0 +1,67 @@
1
+ ---
2
+ title: Testing
3
+ description: What the Mollie module's test run covers, how it switches between the stand-in and Mollie's test mode, and which conformance tests Mollie cannot pass.
4
+ mode: reference
5
+ ---
6
+
7
+ `pnpm test` builds the module and runs `ajs module test .`. That runs the interface-payment and interface-subscriptions conformance suites, and this module's own tests.
8
+
9
+ ## Against the stand-in, or against Mollie
10
+
11
+ | `MOLLIE_API_KEY` | The suite runs against |
12
+ | ---------------- | --------------------------------------------------------------- |
13
+ | unset | a local stand-in for Mollie's API, started by the test config |
14
+ | a `test_…` key | Mollie's test mode at `api.mollie.com`, with no other change |
15
+ | a `live_…` key | nothing, because the suite refuses to run against live payments |
16
+
17
+ `MOLLIE_SECOND_API_KEY`, a second test-mode account, enables the multi-account tests against Mollie. The stand-in always has two accounts.
18
+
19
+ The **stand-in** (`src/test/stand-in`) answers the part of Mollie's API that the module uses, as Mollie's OpenAPI specification and documentation describe it. [`SOURCES.md`](../src/test/stand-in/SOURCES.md) lists every behaviour it models and what that behaviour rests on: the specification, a documentation page, a response observed from Mollie, another project's tests, or an assumption. A green run against the stand-in shows that the module agrees with that reading of the documentation. A first run against Mollie checks the assumptions.
20
+
21
+ ## The test payer
22
+
23
+ Mollie's test mode settles nothing on its own. A payer-present payment waits on a test-mode checkout page where the tester picks the outcome. An off-session charge waits on its `changePaymentState` page (Mollie: _Testing_). The suites expect a charge to settle within 30 seconds, so the test config starts a **test payer** that does what a tester would. It watches recent payments. For every open `first` or `recurring` payment, it opens the page, picks the method if asked, and submits a final state:
24
+
25
+ - A `first` payment, which saves a card, gets `paid`.
26
+ - A charge against a mandate that the test marked as declining gets `failed`.
27
+ - A held charge (`captureMode: manual`) gets `authorized`.
28
+ - Any other charge gets `paid`.
29
+
30
+ The payer leaves hosted one-off payments alone, because the checkout tests expect them to stay open.
31
+
32
+ Against the stand-in, the payer posts the pages' forms over plain HTTP. Against Mollie, it drives the pages in headless Chromium through Playwright, because Mollie asks for a card in a Mollie Components iframe before it shows the test-mode page. The payer fills that form with the test card `2223 0000 1047 9399`, then picks the final state. Install the browser once before a live run with `pnpm exec playwright install chromium-headless-shell`.
33
+
34
+ A live run in November 2026 showed that Mollie's test mode no longer waits on an off-session card charge: the creating call already answers `paid`, and the charge's page offers only a refund or a chargeback. The payer leaves such a page alone. So against Mollie, a charge on the declining card is paid too.
35
+
36
+ Before the suites load, the test config uses the payer to save two cards through real first payments. Charges on the first card succeed (`ANTELOPE_PAYMENT_TEST_METHOD`), and the payer declines charges on the second (`ANTELOPE_PAYMENT_TEST_METHOD_DECLINED`). The subscriptions suite saves its own cards, with `ANTELOPE_PAYMENT_TEST_METHOD` set to `creditcard`. A Mollie saved method belongs to one customer, and that suite saves a method for each customer it creates.
37
+
38
+ ## What the conformance suites cannot check here
39
+
40
+ Every run reports these conformance tests as pending, by name and with the reason:
41
+
42
+ | Test | Why it cannot pass on Mollie |
43
+ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
44
+ | payment: _saves a method against a customer and lists it back_ | It charges one test token for a brand-new customer. Mollie's saved methods are mandates that belong to one customer. |
45
+ | payment: _authorizes without capturing, then captures in part_ | Mollie creates an off-session payment `open` and authorizes it afterwards. The test reads `authorized` from the creating call. |
46
+ | payment: _releases an authorization on cancel_ | The same. |
47
+ | payment: _resolves a decline instead of throwing_ | Mollie reports a declined off-session payment after the creating call. The test reads `failed` from that call. |
48
+ | subscriptions: _starts a trial without charging anything_ | Mollie schedules by date. The trial end comes back rounded up to the next Amsterdam midnight, not to the second. |
49
+ | subscriptions: _defers the first charge to a billing anchor_ | The same, for the anchor. |
50
+
51
+ One more test is pending only when the coming month crosses a daylight-saving change in Europe/Amsterdam:
52
+
53
+ | Test | Why it cannot pass on Mollie |
54
+ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
55
+ | subscriptions: _charges the first period at once and reports it active_ | Its period runs from one Amsterdam midnight to another, an hour off whole days. The test allows at most 31 days of exactly 24 hours. |
56
+
57
+ The suite skips its own `a declined first period` tests as well. They need a card that saves on-session and is declined off-session, and Mollie reports that decline after `CreateSubscription` returns.
58
+
59
+ This module's own tests cover each of these flows instead, settled the way Mollie settles them: held and then captured, declined after the call, and trials rounded to the day.
60
+
61
+ ## What only a live run can show
62
+
63
+ The live run checks the assumptions in [`SOURCES.md`](../src/test/stand-in/SOURCES.md). It also shows the following:
64
+
65
+ - **Webhooks.** A test container cannot receive Mollie's deliveries, so against Mollie the event tests are skipped. The test config sets `ANTELOPE_SUBSCRIPTIONS_TEST_EVENTS` only for the stand-in, which delivers in-process. The tests call `VerifyWebhook` directly with the deliveries Mollie would send.
66
+ - **Subscription renewals.** Mollie fires renewals on their dates and has no test clock. So only the stand-in tests renewals, retries, and cancellation after failed retries.
67
+ - **Timing.** A live run shows when in the day Mollie charges on a subscription date, and in which time zone Mollie reads that date.
package/package.json CHANGED
@@ -1,6 +1,88 @@
1
1
  {
2
2
  "name": "@antelopejs/mollie",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
4
+ "description": "A Mollie payment module that implements the payment and subscriptions interfaces of antelopejs",
5
+ "keywords": [
6
+ "antelopejs",
7
+ "billing",
8
+ "mollie",
9
+ "payment",
10
+ "subscription"
11
+ ],
12
+ "homepage": "https://github.com/AntelopeJS/mollie#readme",
13
+ "license": "Apache-2.0",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/AntelopeJS/mollie.git"
17
+ },
18
+ "files": [
19
+ "dist",
20
+ "!dist/test",
21
+ "docs",
22
+ "skills"
23
+ ],
24
+ "main": "dist/index.js",
25
+ "publishConfig": {
26
+ "access": "public",
27
+ "provenance": true
28
+ },
29
+ "scripts": {
30
+ "build": "rimraf dist && tsc",
31
+ "format": "oxfmt .",
32
+ "lint": "oxlint",
33
+ "lint:fix": "oxlint --fix",
34
+ "prepack": "pnpm run build",
35
+ "release": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run prepack && release-it",
36
+ "test": "pnpm run build && ajs module test .",
37
+ "typecheck": "tsc --noEmit",
38
+ "format:check": "oxfmt --check .",
39
+ "knip": "knip",
40
+ "prepare": "if [ -e .git ] && command -v git >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1 && GIT_DIR=.git GIT_WORK_TREE=. git rev-parse --git-dir >/dev/null 2>&1; then GIT_DIR=.git GIT_WORK_TREE=. lefthook install; fi",
41
+ "checks": "antelopejs-checks",
42
+ "size": "antelopejs-check-size",
43
+ "sync": "antelopejs-sync",
44
+ "sync:check": "antelopejs-sync --check",
45
+ "suppressions": "antelopejs-suppressions",
46
+ "suppressions:update": "antelopejs-suppressions --update"
47
+ },
48
+ "dependencies": {
49
+ "@antelopejs/interface-core": ">=0.0.5 <1.0.0",
50
+ "@antelopejs/interface-payment": ">=0.2.0 <0.3.0",
51
+ "@antelopejs/interface-subscriptions": ">=0.1.0 <0.2.0"
52
+ },
53
+ "devDependencies": {
54
+ "@antelopejs/core": "^1.21.0",
55
+ "@antelopejs/tooling-configs": "^0.5.1",
56
+ "@types/mocha": "^10.0.10",
57
+ "@types/node": "^22.19.15",
58
+ "eslint-plugin-perfectionist": "^5.11.0",
59
+ "fast-check": "4.3.0",
60
+ "knip": "^6.34.0",
61
+ "lefthook": "^2.2.2",
62
+ "oxfmt": "^0.66.0",
63
+ "oxlint": "1.81.0",
64
+ "oxlint-tsgolint": "^7.0.2001",
65
+ "playwright": "^1.65.0",
66
+ "release-it": "^19.2.4",
67
+ "release-it-changelogen": "^0.1.0",
68
+ "rimraf": "^6.1.3",
69
+ "typescript": "^5.9.3"
70
+ },
71
+ "packageManager": "pnpm@10.6.5",
72
+ "antelopeJs": {
73
+ "implements": [
74
+ "@antelopejs/interface-payment",
75
+ "@antelopejs/interface-subscriptions"
76
+ ],
77
+ "defaultConfig": {
78
+ "apiKey": "your_mollie_api_key"
79
+ },
80
+ "test": "src/test/antelope.test.ts",
81
+ "skills": [
82
+ "./skills"
83
+ ],
84
+ "docs": {
85
+ "standard": true
86
+ }
87
+ }
88
+ }
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: mollie
3
+ description: The AntelopeJS Mollie module — implements @antelopejs/interface-payment and, on Mollie's own subscriptions, @antelopejs/interface-subscriptions. Use when wiring "@antelopejs/mollie" into a project, configuring its API key, webhook URL or extra accounts, writing the route that passes Mollie's webhooks to VerifyWebhook, or debugging a Mollie payment that stays pending, a hold that was captured at once, a capture that came back pending, a missing refund event, or a subscription whose status, period or renewal looks wrong.
4
+ category: antelopejs-module
5
+ tags: [payment, subscriptions, mollie, webhooks, recurring, antelopejs]
6
+ ---
7
+
8
+ # mollie
9
+
10
+ Implements the payment and subscriptions interfaces on Mollie. Consumers code against `@antelopejs/interface-payment` and `@antelopejs/interface-subscriptions` (see their skills); this module is what you wire.
11
+
12
+ ## Wiring
13
+
14
+ ```ts
15
+ modules: {
16
+ payments: {
17
+ source: { type: "package", package: "@antelopejs/mollie" },
18
+ config: { apiKey: "test_…", webhookUrl: "https://shop.example.org/payments/mollie" },
19
+ },
20
+ }
21
+ ```
22
+
23
+ No other module is needed. To use `@antelopejs/payment-subscriptions` for subscriptions instead, add `disabledExports: ["@antelopejs/interface-subscriptions"]` to this entry.
24
+
25
+ ## Config
26
+
27
+ | Field | Required | Meaning |
28
+ | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
29
+ | `apiKey` | Yes | `test_…` or `live_…` |
30
+ | `webhookUrl` | No | Public route calling `VerifyWebhook`; without it no event is ever raised |
31
+ | `accounts` | No | `{ name: { apiKey, webhookUrl } }`, chosen by the `provider` argument |
32
+ | `apiUrl` | No | Defaults to `https://api.mollie.com` |
33
+ | `settleTimeoutMs` | No | How long `CapturePayment` waits for Mollie to apply a capture; default 10000, `0` does not wait; a finite number, 0 or more, or the module refuses to start |
34
+
35
+ ## The webhook route
36
+
37
+ Pass the raw body and the headers to `VerifyWebhook`. Mollie posts `id=tr_…`, unsigned; the module reads the payment back and builds the event from that read only. `WebhookVerificationError` → answer 403. A `PaymentError` (Mollie unreachable) or a subscription handler that throws → answer 5xx, Mollie retries. `undefined` → answer 200.
38
+
39
+ ## Facts to reason from when debugging
40
+
41
+ - **Payer-present payments are redirects**: `requires_action` with Mollie's checkout URL. A checkout session's id is its payment's id.
42
+ - **The hosted page language** comes from the checkout `locale`: a language gets the region Mollie offers it in (`fr` is `fr_FR`, `en` is `en_US`, `pt-BR` is `pt_PT`), and a language Mollie does not offer (`ja`, `zh`, …) or `auto` sends none, so Mollie picks from the browser. The table is in `docs/2.payments.md`.
43
+ - **Off-session charges come back `pending`**; the outcome (`succeeded`, `authorized`, `failed`) arrives later through the webhook. In test mode nothing settles until someone submits the test-mode page.
44
+ - **Saved methods are mandates**, id `cst_…:mdt_…`, belonging to one customer. A saved card is listed once its payment reads `succeeded`: `GetPayment` and `VerifyWebhook` wait up to 5 seconds for Mollie to turn the mandate valid. Detaching one revokes the mandate, and Mollie cancels the subscriptions that charge it.
45
+ - **`authorizeOnly`** only for cards, Klarna, Billie, Riverty, Vipps, MobilePay, PayPal, Billink; anything else is refused before Mollie is called.
46
+ - **No `refund.*` or `dispute.opened` events**: a Mollie delivery names a payment, never its refund or chargeback. Read refunds with `GetRefund`.
47
+ - **Idempotency keys last one hour** at Mollie; `RefundPayment`, `CapturePayment` and `CreateSubscription` find their earlier result by key at any time.
48
+ - **Captures settle after the call**: Mollie answers a capture `pending` and applies it about a second later. `CapturePayment` waits up to `settleTimeoutMs`, then returns `succeeded`, or `pending` with `amountCaptured` already set; `GetPayment` reads a payment with a capture in flight the same way. A read that fails after Mollie accepted the capture also returns `pending`; a capture Mollie fails rejects with `PaymentError` `capture_failed`. Mollie takes one capture per authorization, so a second capture under another key, or `CancelPayment`, while a capture is in flight or applied is `InvalidPaymentStateError` and never reaches Mollie.
49
+ - **State errors come from the module reading the payment first.** A Mollie 422 is a `PaymentError`: it also means a suspended account. A capture Mollie refuses with 422 is read again, and a capture another caller made meanwhile turns it into `InvalidPaymentStateError`.
50
+ - **Subscriptions**: the first period is charged by `CreateSubscription` and not retried if it fails; Mollie's schedule starts one period later and Mollie retries its own renewals five times, then cancels. Dates are Europe/Amsterdam days; trial ends and anchors round up to the next midnight. `period_end` cancels at Mollie at once and is reported as running until the period ends, with no event when it does. `now` after `period_end` records the early end in the customer's metadata, one call at a time within a process, and `GetCustomer` returns the same metadata after it (a string, even one holding a JSON object, a number or a list another writer set moves under `antelope.kept`); when the customer's metadata leaves no room for the entry within Mollie's 1 kB, it rejects with `SubscriptionError` and writes nothing; two processes ending one customer's subscriptions early at once can lose one, which then reports its scheduled end. `CreateSubscription` rejects with `InvalidSubscriptionRequestError`, creating nothing, when the subscription's metadata would leave no room within Mollie's 1,024 bytes for the first charge and a cancellation under a key of up to 64 bytes; with a reference and 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 caller metadata as JSON always fit. A cancellation whose record would not fit (a longer key, or a subscription created before that check) rejects with `SubscriptionError` and sends nothing. Subscriptions not created by this module are invisible to it. A stored interval or count the module could not have written reads as the interval Mollie bills; when Mollie's interval is not a documented one either, reads, cancels and the creation's replay reject with a `SubscriptionError` naming it, and `ListSubscriptions` leaves it out.
51
+ - **A failed `CreateSubscription` must be replayed with its key**: Mollie may already hold the subscription and will charge it. Replay once the call has failed, not while it runs: an overlapping replay can cancel the subscription the call returns if the first charge fails in between.
52
+
53
+ ## Not in this module
54
+
55
+ Mollie Connect, OAuth, next-gen (signed) webhooks, Orders API, payment links, terminals, chargeback handling beyond what `GetPayment` shows.
@@ -0,0 +1,49 @@
1
+ {
2
+ "version": 1,
3
+ "cases": [
4
+ {
5
+ "id": "mollie-webhook-route",
6
+ "area": "modules",
7
+ "style": "clean",
8
+ "prompt": "How do I write the route that receives Mollie's webhooks and passes them to VerifyWebhook in my AntelopeJS project?",
9
+ "expect": {
10
+ "skills": ["mollie"],
11
+ "acceptable": ["antelopejs", "taking-payments", "api-interface"],
12
+ "mustMention": ["VerifyWebhook"]
13
+ }
14
+ },
15
+ {
16
+ "id": "mollie-hosted-page-language-casual",
17
+ "area": "modules",
18
+ "style": "casual",
19
+ "prompt": "mollie checkout page shows up in english even though i passed locale ja, why",
20
+ "expect": {
21
+ "skills": ["mollie"],
22
+ "acceptable": ["antelopejs", "taking-payments"],
23
+ "mustMention": ["browser"]
24
+ }
25
+ },
26
+ {
27
+ "id": "mollie-hosted-page-language",
28
+ "area": "modules",
29
+ "style": "clean",
30
+ "prompt": "With @antelopejs/mollie, which language does Mollie's hosted checkout page show when I call CreateCheckoutSession with locale pt-BR?",
31
+ "expect": {
32
+ "skills": ["mollie"],
33
+ "acceptable": ["antelopejs", "taking-payments"],
34
+ "mustMention": ["pt_PT"]
35
+ }
36
+ },
37
+ {
38
+ "id": "mollie-taking-payments-neighbour",
39
+ "area": "modules",
40
+ "style": "clean",
41
+ "prompt": "In my AntelopeJS module, how do I refund a payment through the payment interface without caring which provider is wired?",
42
+ "expect": {
43
+ "skills": ["taking-payments"],
44
+ "acceptable": ["antelopejs", "ajs-consume-interface"],
45
+ "avoid": ["mollie"]
46
+ }
47
+ }
48
+ ]
49
+ }