Provider capability matrix
This interface is not the lowest common denominator, and it is not Stripe with the names changed. It is the set of flows a typical backend needs, chosen so that all four provider families can plausibly implement each one.
The bar is that a backend on this interface can change provider. An
implementation may decline a flow and throw UnsupportedOperationError, but the
feature set is chosen so that declining is uncommon.
@antelopejs/stripe is the public AntelopeJS module that implements this
interface. For the other families, the authors checked each one against its
public API before they added a function, and the design expects full coverage
from none of them.
The four families
| Family | Model | What it pulls the design towards |
|---|---|---|
| Stripe | Intent-based | The reference for the feature set |
| PayPal | Order-based, not intent-based; different capture semantics | The strongest test of whether the abstraction is real |
| Adyen / Checkout.com | Closest to Stripe | shopperReference-style recurring rather than first-class customer objects |
| Mollie / Mangopay | Lighter, redirect-first | Mangopay is wallet-based and the likeliest to decline a flow |
What is in, and what each family does behind it
The table uses three marks: ✅ native, ⚠️ implementable with work, and ❌ would have to decline.
| Contract | Stripe | PayPal | Adyen | Mollie | Mangopay |
|---|---|---|---|---|---|
CreateCheckoutSession | ✅ Checkout Session | ✅ Orders + approve link | ✅ Sessions | ✅ Payments (_links.checkout) | ✅ Web PayIn |
GetCheckoutSession | ✅ retrieve | ✅ get order | ✅ payment details | ✅ get payment | ✅ get PayIn |
CreatePayment (on-session) | ✅ PaymentIntent | ✅ Order + capture | ✅ /payments | ✅ Payments | ✅ Direct PayIn |
CreatePayment (off-session) | ✅ off_session | ✅ vault token | ✅ ContAuth | ✅ sequenceType: recurring | ✅ recurring PayIn |
authorizeOnly + CapturePayment | ✅ capture_method: manual | ✅ authorize then capture | ✅ manual capture | ✅ authorize + capture | ⚠️ PreAuthorization |
| Partial capture | ✅ | ✅ | ✅ | ✅ | ⚠️ lower-amount PayIn |
CancelPayment | ✅ cancel | ✅ void | ✅ /cancels | ✅ cancel | ✅ cancel PreAuth |
RefundPayment full + partial | ✅ | ✅ | ✅ | ✅ | ✅ |
GetRefund | ✅ | ✅ | ⚠️ read from notification | ✅ | ✅ |
CreateCustomer | ✅ Customers | ⚠️ identifier only | ⚠️ shopperReference | ✅ Customers | ✅ Users |
GetCustomer | ✅ | ⚠️ identifier only | ⚠️ identifier only | ✅ | ✅ |
ListPaymentMethods | ✅ PaymentMethods | ✅ Vault tokens | ✅ stored methods | ✅ Mandates | ✅ Cards |
DetachPaymentMethod | ✅ detach | ✅ delete token | ✅ disable | ✅ revoke mandate | ✅ deactivate |
DeleteCustomer | ✅ | ⚠️ detach all tokens | ⚠️ disable all | ✅ | ⚠️ deactivate user |
VerifyWebhook | ✅ signed | ✅ verify-signature call | ✅ HMAC | ⚠️ unsigned; re-fetch | ⚠️ re-fetch |
No call in the contract is ❌ for any family. The feature set was chosen to pass that test.
The two places the contract bent to fit
The four-family audit caused these two design changes.
Customers are an identifier, not a profile
PayPal and Adyen have no first-class customer object. PayPal's vault attaches
tokens to a customer_id that you create yourself. Adyen's shopperReference is
a string you choose. Neither stores an email or a name that you can read back.
If Customer were a record with attributes you could read back, two of five
implementations would return a mostly empty object. Backends that read
customer.email would break without an error. So Customer guarantees the
identifier and nothing else. The TSDoc says that email and name are stored
where supported, and the conformance suite asserts only that the identifier
round-trips.
Here, a customer is a container for saved payment methods, which is exactly
what shopperReference is. The flow survived the audit, but the data model had
to shrink.
Unsigned webhooks still verify
Mollie does not sign webhooks. The delivery is a payment identifier and nothing else, and Mollie documents one way to trust it: call the API and read the current state. Mangopay works the same way.
So the contract specifies VerifyWebhook by its outcome, a normalised event
you can trust, and not as a signature check. A Mollie implementation fetches the
payment inside VerifyWebhook and returns a full event. A Stripe implementation
checks the HMAC and reads the body. Both satisfy the same contract, and a backend
writes one handler.
With a contract of VerifyWebhookSignature(body, signature) => boolean, Mollie
would have had to decline.
The remaining risk is that establishing a delivery and populating an event prove different things. A signature authenticates the whole body. A re-fetch authenticates one record and says nothing about the rest of the body. So the contract requires that, on a re-fetch provider, every field of the event comes from the record read back, and that the implementation treats the body as a pointer only. Webhooks covers the details. Without that rule, a Mangopay module written by analogy with the Stripe one accepts a forged payment state.
The contract specifies this rule, but the conformance suite does not enforce
it. Forging a delivery is not portable across providers, and the suite has no
endpoint where a genuine delivery could arrive. As a result, the suite does not
test the success path of VerifyWebhook at all. Review of each implementation
holds the rule.
What is out, and why
Subscriptions, invoicing, proration, dunning, tax, coupons
This was the largest single judgement call. Provider subscription objects differ more than any other area. Billing anchors, proration arithmetic, trial handling, dunning schedules, and tax engines all differ, and several families have no equivalent at all. Most implementations would decline an interface over them.
The portable part is the mechanism underneath: save a payment method, then charge
it off-session on your own schedule. A backend that sells recurring access runs
its own cycle on ListPaymentMethods and CreatePayment, and that works on all
five providers. The portable subset lives in a separate interface,
@antelopejs/interface-subscriptions. @antelopejs/payment-subscriptions
implements it on saved methods and off-session charges, not on provider
subscription objects.
Marketplace and split payments
Stripe Connect, PayPal Commerce Platform, Adyen for Platforms, and Mangopay's wallets are incompatible models, not different spellings of one model. Connect splits a charge. Mangopay moves money between wallets it holds. PayPal routes payments to merchants. A backend that does this depends deeply on one provider's model, and should use that provider's own interface.
Dispute management
A dispute is an event here, with no API to respond. Evidence formats, deadlines,
and appeal paths differ so much that a portable submission call would be a
wrapper nobody could use. dispute.opened tells a backend to react, and the
response goes through the provider.
Payment links and in-person terminals
Payment links are mostly a dashboard feature, not an API feature. Terminal integrations depend on hardware and on one provider.
How this is kept honest
The conformance suite in src/tests ships in the package and runs against
whichever provider module is wired in. It tests the contract, not Stripe's
behavior, and every provider implementation must pass it.
Most of the suite needs no fixture, and cannot pass without a live provider. That part covers session creation, the customer lifecycle, idempotency replay, unknown-identifier errors, and webhook signature rejection.
The charge tests need a chargeable test payment method, and there is no portable
way to create one. A payer enters a real card, and every provider publishes its
own test token instead. The provider module supplies one through
ANTELOPE_PAYMENT_TEST_METHOD. When it is absent, those tests skip, visibly and
by name. The token is test data supplied at the boundary, not a stub that
stands in for provider behavior.
Webhooks and events
Verify a webhook delivery with VerifyWebhook, learn the normalised event set, and handle repeated and out-of-order events.
Use the shared Redis client
Get the project's ioredis client with GetClient, then cache values, publish and receive messages, and run lists, sets, and transactions on it.