@antelopejs/interface-payment 0.0.2 → 0.2.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.
- package/README.md +74 -46
- package/dist/tests/payment-charges.test.js +3 -3
- package/dist/tests/payment-charges.test.js.map +1 -1
- package/dist/tests/payment.test.js +1 -1
- package/dist/tests/payment.test.js.map +1 -1
- package/dist/tests/support.d.ts +10 -1
- package/dist/tests/support.js +11 -2
- package/dist/tests/support.js.map +1 -1
- package/dist/types.d.ts +14 -2
- package/dist/types.js +49 -1
- package/dist/types.js.map +1 -1
- package/docs/1.introduction.md +58 -43
- package/docs/2.payments.md +180 -124
- package/docs/3.customers-and-methods.md +106 -65
- package/docs/4.webhooks.md +103 -88
- package/docs/5.provider-capability-matrix.md +85 -74
- package/docs/tsconfig.json +2 -0
- package/package.json +23 -5
package/docs/4.webhooks.md
CHANGED
|
@@ -1,16 +1,20 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Webhooks and events
|
|
3
|
+
description: Verify a webhook delivery with VerifyWebhook, learn the normalised event set, and handle repeated and out-of-order events.
|
|
4
|
+
mode: how-to
|
|
5
|
+
---
|
|
2
6
|
|
|
3
7
|
Every provider this interface targets settles some payments asynchronously. A
|
|
4
|
-
backend that reads only what its own calls return
|
|
5
|
-
|
|
6
|
-
only way to learn a terminal state.
|
|
8
|
+
backend that reads only what its own calls return can report a payment as
|
|
9
|
+
pending twenty minutes after it succeeded. Webhooks are required here, because
|
|
10
|
+
they are the only way to learn a terminal state.
|
|
7
11
|
|
|
8
12
|
## Verifying a delivery
|
|
9
13
|
|
|
10
14
|
In an `@antelopejs/interface-api` controller, read all headers from the request
|
|
11
|
-
context. `handle`
|
|
15
|
+
context. In the example, `handle` is your application's idempotent event handler.
|
|
12
16
|
|
|
13
|
-
```ts
|
|
17
|
+
```ts fragment
|
|
14
18
|
import { Context, HTTPResult, Post, RawBody } from "@antelopejs/interface-api";
|
|
15
19
|
import type { RequestContext } from "@antelopejs/interface-api";
|
|
16
20
|
import { VerifyWebhook, WebhookVerificationError } from "@antelopejs/interface-payment";
|
|
@@ -32,21 +36,21 @@ async webhook(@RawBody() body: Buffer, @Context() context: RequestContext) {
|
|
|
32
36
|
}
|
|
33
37
|
```
|
|
34
38
|
|
|
35
|
-
`WebhookRequest.body`
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
Node `Buffer` is a `Uint8Array`, and
|
|
39
|
-
it straight through.
|
|
39
|
+
`WebhookRequest.body` has the type `Uint8Array`, not `Buffer`, so the published
|
|
40
|
+
types of this package need no ambient Node.js types. Without that choice, a
|
|
41
|
+
consumer that compiles without `@types/node` would fail inside `node_modules`. A
|
|
42
|
+
Node.js `Buffer` is a `Uint8Array`, and an HTTP handler gives you a `Buffer`, so
|
|
43
|
+
pass it straight through.
|
|
40
44
|
|
|
41
|
-
**The body must be the raw bytes.**
|
|
42
|
-
|
|
45
|
+
**The body must be the raw bytes.** A signature covers the bytes as sent. A body
|
|
46
|
+
that has been through `JSON.parse` and serialised again does not verify, because
|
|
43
47
|
key order and whitespace change. Use a raw body handler on this route.
|
|
44
48
|
|
|
45
|
-
Node
|
|
46
|
-
`string | string[] | undefined`
|
|
47
|
-
|
|
49
|
+
Node.js gives `rawRequest.headers` lowercase names, and its values have the
|
|
50
|
+
`string | string[] | undefined` type that `WebhookRequest.headers` accepts.
|
|
51
|
+
The API interface has no `@Headers()` decorator.
|
|
48
52
|
|
|
49
|
-
|
|
53
|
+
`VerifyWebhook` has three distinct outcomes:
|
|
50
54
|
|
|
51
55
|
| Outcome | Meaning | Respond |
|
|
52
56
|
| -------------------------- | ------------------------------------------ | ------------------- |
|
|
@@ -54,22 +58,23 @@ Three outcomes, and they are distinct on purpose:
|
|
|
54
58
|
| `undefined` | Genuine, but not one of the modelled types | 200 |
|
|
55
59
|
| `WebhookVerificationError` | Could not be established as genuine | 403, act on nothing |
|
|
56
60
|
|
|
57
|
-
**"Genuine" is not always a signature check.** Stripe, Adyen and PayPal sign
|
|
58
|
-
verification
|
|
59
|
-
sign
|
|
60
|
-
establishes it by reading that record back from the provider.
|
|
61
|
-
record, or
|
|
62
|
-
|
|
63
|
-
the same
|
|
61
|
+
**"Genuine" is not always a signature check.** Stripe, Adyen, and PayPal sign
|
|
62
|
+
their deliveries, so verification checks the signature over the raw bytes.
|
|
63
|
+
Mollie and Mangopay do not sign. Their delivery is a bare record identifier, and
|
|
64
|
+
the implementation establishes it by reading that record back from the provider.
|
|
65
|
+
On those providers, a body that names no record, or a record the provider does
|
|
66
|
+
not confirm, raises `WebhookVerificationError`, just as a bad signature does on
|
|
67
|
+
the others. Your handler is the same for both kinds of provider, and that is the
|
|
68
|
+
reason for the design.
|
|
64
69
|
|
|
65
70
|
### Where an event's fields may come from
|
|
66
71
|
|
|
67
|
-
This is
|
|
68
|
-
|
|
72
|
+
This rule is for implementations, not for callers, and it is the easiest one to
|
|
73
|
+
get wrong.
|
|
69
74
|
|
|
70
75
|
**Every field of the returned event must come from data the implementation has
|
|
71
|
-
authenticated.** Establishing a delivery and populating an event are two steps
|
|
72
|
-
|
|
76
|
+
authenticated.** Establishing a delivery and populating an event are two steps.
|
|
77
|
+
The first step proves different things on different providers:
|
|
73
78
|
|
|
74
79
|
| Style | What establishing proves | What the event may be built from |
|
|
75
80
|
| ------------------------------ | ---------------------------- | -------------------------------- |
|
|
@@ -77,94 +82,104 @@ and the first proves different things on different providers:
|
|
|
77
82
|
| Re-fetched (Mollie, Mangopay) | A record with that id exists | **The record read back, only** |
|
|
78
83
|
|
|
79
84
|
A re-fetch proves the identifier. It proves nothing about any other field in the
|
|
80
|
-
body
|
|
81
|
-
provider the body is a pointer and nothing else
|
|
82
|
-
record
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
The failure mode is
|
|
86
|
-
|
|
87
|
-
`RessourceId`, `EventType
|
|
88
|
-
`PaymentEvent.type
|
|
89
|
-
delivery and then reads `EventType` from the body accepts an
|
|
90
|
-
payment
|
|
91
|
-
with a succeeded event type
|
|
92
|
-
passes
|
|
93
|
-
pending or failed.
|
|
94
|
-
|
|
95
|
-
Mollie
|
|
96
|
-
`id=tr_xxx`, so there is nothing else
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
The `undefined`
|
|
100
|
-
account updates, payout notifications, report completions
|
|
101
|
-
threw on all of them
|
|
102
|
-
|
|
103
|
-
|
|
85
|
+
body: not the event type, not the amount, and not the status. On a re-fetch
|
|
86
|
+
provider, the body is a pointer and nothing else. The event's `type`, the kind of
|
|
87
|
+
record, and every field of `payment`, `refund`, or `dispute` come from the record
|
|
88
|
+
that the implementation read.
|
|
89
|
+
|
|
90
|
+
The failure mode is an implementation for a re-fetch provider written by analogy
|
|
91
|
+
with a signed one, and a careful implementer can make this mistake. A Mangopay
|
|
92
|
+
delivery carries `RessourceId`, `EventType`, and `Date`, and `EventType` maps
|
|
93
|
+
neatly onto `PaymentEvent.type`. Suppose an implementation re-fetches to
|
|
94
|
+
establish the delivery and then reads `EventType` from the body. It accepts an
|
|
95
|
+
unauthenticated forgery of the payment state. Anyone who can reach the endpoint
|
|
96
|
+
posts a real payment id with a succeeded event type. The read confirms that the
|
|
97
|
+
id exists, and verification passes. The backend then ships goods for a payment
|
|
98
|
+
that the provider's own record says is pending or failed.
|
|
99
|
+
|
|
100
|
+
Mollie avoids this problem by accident, not by design. Its body is only
|
|
101
|
+
`id=tr_xxx`, so there is nothing else for an implementer to trust. Mangopay is
|
|
102
|
+
the real case, and any provider added later is the general case.
|
|
103
|
+
|
|
104
|
+
The `undefined` outcome is the common one. Providers send dozens of event types,
|
|
105
|
+
such as account updates, payout notifications, and report completions. If the
|
|
106
|
+
interface threw on all of them, every implementation would reject genuine
|
|
107
|
+
traffic, and providers answer a rejection by retrying for days. A verified but
|
|
108
|
+
unmodelled delivery is a normal result.
|
|
104
109
|
|
|
105
110
|
## The event set
|
|
106
111
|
|
|
107
|
-
```
|
|
112
|
+
```text
|
|
108
113
|
"payment.pending" "payment.authorized" "payment.succeeded"
|
|
109
114
|
"payment.failed" "payment.canceled" "refund.succeeded"
|
|
110
115
|
"refund.failed" "dispute.opened"
|
|
111
116
|
```
|
|
112
117
|
|
|
113
|
-
The `payment.*` types are exactly the `PaymentStatus` values a backend
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
118
|
+
The `payment.*` types are exactly the `PaymentStatus` values that a backend
|
|
119
|
+
learns asynchronously. `requires_action` has no event, because the call that
|
|
120
|
+
created the payment returns it synchronously. No provider tells you later that a
|
|
121
|
+
payer needs to authenticate.
|
|
117
122
|
|
|
118
|
-
`payment.canceled` covers abandonment and expiry
|
|
123
|
+
`payment.canceled` covers abandonment and expiry as well as a `CancelPayment` you
|
|
119
124
|
made yourself. An abandoned checkout is the most common outcome of a hosted
|
|
120
|
-
session
|
|
125
|
+
session. Without this event, a backend keeps orders pending forever.
|
|
121
126
|
|
|
122
|
-
`payment.authorized`
|
|
123
|
-
|
|
124
|
-
a
|
|
127
|
+
`payment.authorized` tells a backend that authorizes and then captures that the
|
|
128
|
+
hold is in place. Without it, the authorize and capture flow would work only
|
|
129
|
+
synchronously. On a provider that redirects first, it would not work at all.
|
|
125
130
|
|
|
126
|
-
Exactly one of `payment`, `refund
|
|
127
|
-
prefix
|
|
131
|
+
Exactly one of `payment`, `refund`, and `dispute` is set, matching the type
|
|
132
|
+
prefix. It carries the object's state at the moment the provider sent the event,
|
|
133
|
+
which may already be stale.
|
|
128
134
|
|
|
129
135
|
## Handling
|
|
130
136
|
|
|
131
|
-
```ts
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
"
|
|
141
|
-
|
|
137
|
+
```ts fragment
|
|
138
|
+
import type {
|
|
139
|
+
PaymentEvent,
|
|
140
|
+
PaymentEventType,
|
|
141
|
+
} from "@antelopejs/interface-payment";
|
|
142
|
+
|
|
143
|
+
const HANDLERS: Record<PaymentEventType, (event: PaymentEvent) => unknown> = {
|
|
144
|
+
"payment.succeeded": ({ payment }) =>
|
|
145
|
+
payment && orders.fulfil(payment.reference),
|
|
146
|
+
"payment.failed": ({ payment }) =>
|
|
147
|
+
payment && orders.declined(payment.reference),
|
|
148
|
+
"payment.canceled": ({ payment }) =>
|
|
149
|
+
payment && orders.release(payment.reference),
|
|
150
|
+
"payment.authorized": ({ payment }) =>
|
|
151
|
+
payment && orders.readyToShip(payment.reference),
|
|
152
|
+
"payment.pending": ({ payment }) =>
|
|
153
|
+
payment && orders.awaitingSettlement(payment.reference),
|
|
154
|
+
"refund.succeeded": ({ refund }) => refund && refunds.settled(refund.id),
|
|
155
|
+
"refund.failed": ({ refund }) => refund && refunds.retry(refund.id),
|
|
156
|
+
"dispute.opened": ({ dispute }) => dispute && disputes.open(dispute),
|
|
142
157
|
};
|
|
143
158
|
|
|
144
|
-
async function handle(event) {
|
|
159
|
+
async function handle(event: PaymentEvent) {
|
|
145
160
|
if (await events.seen(event.id)) return;
|
|
146
|
-
await HANDLERS[event.type]
|
|
161
|
+
await HANDLERS[event.type](event);
|
|
147
162
|
await events.record(event.id);
|
|
148
163
|
}
|
|
149
164
|
```
|
|
150
165
|
|
|
151
|
-
|
|
166
|
+
Follow two rules. Production traffic breaks both if you ignore them.
|
|
152
167
|
|
|
153
|
-
**De-duplicate on `event.id`.** Providers redeliver. A delivery your handler
|
|
154
|
-
acknowledged can arrive again because the acknowledgement was lost
|
|
155
|
-
|
|
168
|
+
**De-duplicate on `event.id`.** Providers redeliver. A delivery that your handler
|
|
169
|
+
acknowledged can arrive again because the acknowledgement was lost. A handler
|
|
170
|
+
that ships an order twice loses real money.
|
|
156
171
|
|
|
157
172
|
**Do not assume an event is newer than what you hold.** Providers deliver out of
|
|
158
|
-
order, and a `payment.pending` can
|
|
159
|
-
same payment. Guard on your own record's state, or
|
|
160
|
-
before
|
|
173
|
+
order, and a `payment.pending` can arrive after the `payment.succeeded` for the
|
|
174
|
+
same payment. Guard on your own record's state, or read the payment again with
|
|
175
|
+
`GetPayment` before you act on a backwards transition.
|
|
161
176
|
|
|
162
177
|
## Disputes
|
|
163
178
|
|
|
164
|
-
`dispute.opened` reports that a payer has challenged a captured payment
|
|
165
|
-
backend can react
|
|
179
|
+
`dispute.opened` reports that a payer has challenged a captured payment. A
|
|
180
|
+
backend can then react: hold the goods, notify someone, or flag the account.
|
|
166
181
|
|
|
167
|
-
|
|
168
|
-
format, the deadlines and the appeal path
|
|
182
|
+
The interface does not model the response to a dispute. Providers differ so much
|
|
183
|
+
in the evidence they want, its format, the deadlines, and the appeal path that an
|
|
169
184
|
abstraction would be a thin wrapper nobody could use portably. Respond through
|
|
170
185
|
the provider's own interface or its dashboard.
|
|
@@ -1,16 +1,21 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Provider capability matrix
|
|
3
|
+
description: How each provider family implements each call in the contract, where the contract changed to fit them, and why some features stay out.
|
|
4
|
+
mode: explanation
|
|
5
|
+
---
|
|
2
6
|
|
|
3
7
|
This interface is not the lowest common denominator, and it is not Stripe with
|
|
4
|
-
the names changed. It is the set of flows a typical backend needs
|
|
5
|
-
provider families can plausibly implement each one.
|
|
8
|
+
the names changed. It is the set of flows a typical backend needs, chosen so that
|
|
9
|
+
all four provider families can plausibly implement each one.
|
|
6
10
|
|
|
7
|
-
The bar
|
|
8
|
-
decline a flow and throw `UnsupportedOperationError`, but the
|
|
9
|
-
chosen so that declining is uncommon.
|
|
11
|
+
The bar is that a backend on this interface can change provider. An
|
|
12
|
+
implementation may decline a flow and throw `UnsupportedOperationError`, but the
|
|
13
|
+
feature set is chosen so that declining is uncommon.
|
|
10
14
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
API before
|
|
15
|
+
`@antelopejs/stripe` is the public AntelopeJS module that implements this
|
|
16
|
+
interface. For the other families, the authors checked each one against its
|
|
17
|
+
public API before they added a function, and the design expects full coverage
|
|
18
|
+
from none of them.
|
|
14
19
|
|
|
15
20
|
## The four families
|
|
16
21
|
|
|
@@ -23,7 +28,8 @@ API before a proxy was added, and full coverage is expected of none of them.
|
|
|
23
28
|
|
|
24
29
|
## What is in, and what each family does behind it
|
|
25
30
|
|
|
26
|
-
✅ native
|
|
31
|
+
The table uses three marks: ✅ native, ⚠️ implementable with work, and ❌ would
|
|
32
|
+
have to decline.
|
|
27
33
|
|
|
28
34
|
| Contract | Stripe | PayPal | Adyen | Mollie | Mangopay |
|
|
29
35
|
| ---------------------------------- | --------------------------- | ------------------------- | ------------------------- | ------------------------------- | --------------------- |
|
|
@@ -43,105 +49,110 @@ API before a proxy was added, and full coverage is expected of none of them.
|
|
|
43
49
|
| `DeleteCustomer` | ✅ | ⚠️ detach all tokens | ⚠️ disable all | ✅ | ⚠️ deactivate user |
|
|
44
50
|
| `VerifyWebhook` | ✅ signed | ✅ verify-signature call | ✅ HMAC | ⚠️ unsigned; re-fetch | ⚠️ re-fetch |
|
|
45
51
|
|
|
46
|
-
|
|
47
|
-
|
|
52
|
+
No call in the contract is ❌ for any family. The feature set was chosen to pass
|
|
53
|
+
that test.
|
|
48
54
|
|
|
49
55
|
## The two places the contract bent to fit
|
|
50
56
|
|
|
51
|
-
|
|
57
|
+
The four-family audit caused these two design changes.
|
|
52
58
|
|
|
53
59
|
### Customers are an identifier, not a profile
|
|
54
60
|
|
|
55
|
-
PayPal and Adyen have no first-class customer object. PayPal's vault
|
|
56
|
-
|
|
57
|
-
choose. Neither stores an email or a name you can read back.
|
|
61
|
+
PayPal and Adyen have no first-class customer object. PayPal's vault attaches
|
|
62
|
+
tokens to a `customer_id` that you create yourself. Adyen's `shopperReference` is
|
|
63
|
+
a string you choose. Neither stores an email or a name that you can read back.
|
|
58
64
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
else
|
|
63
|
-
conformance suite asserts only that the identifier
|
|
65
|
+
If `Customer` were a record with attributes you could read back, two of five
|
|
66
|
+
implementations would return a mostly empty object. Backends that read
|
|
67
|
+
`customer.email` would break without an error. So `Customer` guarantees the
|
|
68
|
+
identifier and nothing else. The TSDoc says that `email` and `name` are stored
|
|
69
|
+
where supported, and the conformance suite asserts only that the identifier
|
|
70
|
+
round-trips.
|
|
64
71
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
72
|
+
Here, a customer _is_ a container for saved payment methods, which is exactly
|
|
73
|
+
what `shopperReference` is. The flow survived the audit, but the data model had
|
|
74
|
+
to shrink.
|
|
68
75
|
|
|
69
76
|
### Unsigned webhooks still verify
|
|
70
77
|
|
|
71
78
|
Mollie does not sign webhooks. The delivery is a payment identifier and nothing
|
|
72
|
-
else, and
|
|
73
|
-
state. Mangopay
|
|
79
|
+
else, and Mollie documents one way to trust it: call the API and read the current
|
|
80
|
+
state. Mangopay works the same way.
|
|
74
81
|
|
|
75
|
-
`VerifyWebhook`
|
|
76
|
-
can trust
|
|
77
|
-
payment inside `VerifyWebhook` and returns a full event
|
|
82
|
+
So the contract specifies `VerifyWebhook` by its _outcome_, a normalised event
|
|
83
|
+
you can trust, and not as a signature check. A Mollie implementation fetches the
|
|
84
|
+
payment inside `VerifyWebhook` and returns a full event. A Stripe implementation
|
|
78
85
|
checks the HMAC and reads the body. Both satisfy the same contract, and a backend
|
|
79
86
|
writes one handler.
|
|
80
87
|
|
|
81
|
-
|
|
82
|
-
|
|
88
|
+
With a contract of `VerifyWebhookSignature(body, signature) => boolean`, Mollie
|
|
89
|
+
would have had to decline.
|
|
83
90
|
|
|
84
|
-
The
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
only
|
|
90
|
-
written by analogy with the Stripe one accepts a forged payment
|
|
91
|
+
The remaining risk is that establishing a delivery and populating an event prove
|
|
92
|
+
different things. A signature authenticates the whole body. A re-fetch
|
|
93
|
+
authenticates one record and says nothing about the rest of the body. So the
|
|
94
|
+
contract requires that, on a re-fetch provider, every field of the event comes
|
|
95
|
+
from the record read back, and that the implementation treats the body as a
|
|
96
|
+
pointer only. [Webhooks](./4.webhooks.md) covers the details. Without that rule,
|
|
97
|
+
a Mangopay module written by analogy with the Stripe one accepts a forged payment
|
|
98
|
+
state.
|
|
91
99
|
|
|
92
|
-
|
|
93
|
-
delivery is not portable across providers, and the suite has no
|
|
94
|
-
|
|
95
|
-
|
|
100
|
+
The contract **specifies this rule, but the conformance suite does not enforce
|
|
101
|
+
it**. Forging a delivery is not portable across providers, and the suite has no
|
|
102
|
+
endpoint where a genuine delivery could arrive. As a result, the suite does not
|
|
103
|
+
test the success path of `VerifyWebhook` at all. Review of each implementation
|
|
104
|
+
holds the rule.
|
|
96
105
|
|
|
97
106
|
## What is out, and why
|
|
98
107
|
|
|
99
108
|
### Subscriptions, invoicing, proration, dunning, tax, coupons
|
|
100
109
|
|
|
101
|
-
|
|
102
|
-
than any other area
|
|
103
|
-
dunning schedules and tax engines
|
|
104
|
-
equivalent at all.
|
|
105
|
-
decline.
|
|
110
|
+
This was the largest single judgement call. Provider subscription objects differ
|
|
111
|
+
more than any other area. Billing anchors, proration arithmetic, trial handling,
|
|
112
|
+
dunning schedules, and tax engines all differ, and several families have no
|
|
113
|
+
equivalent at all. Most implementations would decline an interface over them.
|
|
106
114
|
|
|
107
|
-
|
|
108
|
-
off-session on your own schedule. A backend
|
|
109
|
-
cycle on `ListPaymentMethods`
|
|
110
|
-
|
|
111
|
-
|
|
115
|
+
The portable part is the mechanism underneath: save a payment method, then charge
|
|
116
|
+
it off-session on your own schedule. A backend that sells recurring access runs
|
|
117
|
+
its own cycle on `ListPaymentMethods` and `CreatePayment`, and that works on all
|
|
118
|
+
five providers. The portable subset lives in a separate interface,
|
|
119
|
+
`@antelopejs/interface-subscriptions`. `@antelopejs/payment-subscriptions`
|
|
120
|
+
implements it on saved methods and off-session charges, not on provider
|
|
121
|
+
subscription objects.
|
|
112
122
|
|
|
113
123
|
### Marketplace and split payments
|
|
114
124
|
|
|
115
|
-
Stripe Connect, PayPal Commerce Platform, Adyen for Platforms and Mangopay's
|
|
116
|
-
wallets are incompatible models, not different spellings of one. Connect
|
|
117
|
-
charge
|
|
118
|
-
merchants. A backend
|
|
119
|
-
that provider's own interface.
|
|
125
|
+
Stripe Connect, PayPal Commerce Platform, Adyen for Platforms, and Mangopay's
|
|
126
|
+
wallets are incompatible models, not different spellings of one model. Connect
|
|
127
|
+
splits a charge. Mangopay moves money between wallets it holds. PayPal routes
|
|
128
|
+
payments to merchants. A backend that does this depends deeply on one provider's
|
|
129
|
+
model, and should use that provider's own interface.
|
|
120
130
|
|
|
121
131
|
### Dispute management
|
|
122
132
|
|
|
123
|
-
|
|
124
|
-
that a portable submission call would be a
|
|
125
|
-
tells a backend to react
|
|
133
|
+
A dispute is an event here, with no API to respond. Evidence formats, deadlines,
|
|
134
|
+
and appeal paths differ so much that a portable submission call would be a
|
|
135
|
+
wrapper nobody could use. `dispute.opened` tells a backend to react, and the
|
|
136
|
+
response goes through the provider.
|
|
126
137
|
|
|
127
138
|
### Payment links and in-person terminals
|
|
128
139
|
|
|
129
|
-
Payment links are a dashboard feature
|
|
130
|
-
integrations
|
|
140
|
+
Payment links are mostly a dashboard feature, not an API feature. Terminal
|
|
141
|
+
integrations depend on hardware and on one provider.
|
|
131
142
|
|
|
132
143
|
## How this is kept honest
|
|
133
144
|
|
|
134
|
-
`src/tests
|
|
135
|
-
provider module is wired in. It
|
|
136
|
-
|
|
145
|
+
The conformance suite in `src/tests` ships in the package and runs against
|
|
146
|
+
whichever provider module is wired in. It tests the contract, not Stripe's
|
|
147
|
+
behavior, and every provider implementation must pass it.
|
|
137
148
|
|
|
138
|
-
Most of
|
|
139
|
-
session creation, customer lifecycle, idempotency replay,
|
|
140
|
-
errors, webhook signature rejection.
|
|
149
|
+
Most of the suite needs no fixture, and cannot pass without a live provider. That
|
|
150
|
+
part covers session creation, the customer lifecycle, idempotency replay,
|
|
151
|
+
unknown-identifier errors, and webhook signature rejection.
|
|
141
152
|
|
|
142
|
-
The charge tests need a chargeable test payment method,
|
|
143
|
-
to
|
|
144
|
-
token instead. The provider module supplies one through
|
|
145
|
-
`ANTELOPE_PAYMENT_TEST_METHOD
|
|
146
|
-
|
|
147
|
-
in for provider
|
|
153
|
+
The charge tests need a chargeable test payment method, and there is no portable
|
|
154
|
+
way to create one. A payer enters a real card, and every provider publishes its
|
|
155
|
+
own test token instead. The provider module supplies one through
|
|
156
|
+
`ANTELOPE_PAYMENT_TEST_METHOD`. When it is absent, those tests skip, visibly and
|
|
157
|
+
by name. The token is test _data_ supplied at the boundary, not a stub that
|
|
158
|
+
stands in for provider behavior.
|
package/docs/tsconfig.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-payment",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Provider-agnostic AntelopeJS payment interface: hosted checkout, direct payments with auth/capture, refunds, saved payment methods, and normalised webhook events",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -26,6 +26,12 @@
|
|
|
26
26
|
],
|
|
27
27
|
"main": "dist/index.js",
|
|
28
28
|
"types": "dist/index.d.ts",
|
|
29
|
+
"imports": {
|
|
30
|
+
"#built": {
|
|
31
|
+
"types": "./src/index.ts",
|
|
32
|
+
"default": "./dist/index.js"
|
|
33
|
+
}
|
|
34
|
+
},
|
|
29
35
|
"exports": {
|
|
30
36
|
".": {
|
|
31
37
|
"types": "./dist/index.d.ts",
|
|
@@ -48,18 +54,27 @@
|
|
|
48
54
|
"lint:fix": "oxlint --fix",
|
|
49
55
|
"lint": "oxlint",
|
|
50
56
|
"prepack": "pnpm run build",
|
|
51
|
-
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
57
|
+
"release": "pnpm run lint && pnpm run test && pnpm run prepack && release-it",
|
|
52
58
|
"format:check": "oxfmt --check .",
|
|
53
|
-
"knip": "knip"
|
|
59
|
+
"knip": "knip",
|
|
60
|
+
"prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
|
|
61
|
+
"checks": "antelopejs-checks",
|
|
62
|
+
"size": "antelopejs-check-size",
|
|
63
|
+
"sync": "antelopejs-sync",
|
|
64
|
+
"sync:check": "antelopejs-sync --check",
|
|
65
|
+
"typecheck": "tsc --noEmit",
|
|
66
|
+
"suppressions": "antelopejs-suppressions",
|
|
67
|
+
"suppressions:update": "antelopejs-suppressions --update"
|
|
54
68
|
},
|
|
55
69
|
"devDependencies": {
|
|
56
70
|
"@antelopejs/core": "1.16.0",
|
|
57
71
|
"@antelopejs/interface-core": ">=0.0.3 <1.0.0",
|
|
58
|
-
"@antelopejs/tooling-configs": "^0.
|
|
72
|
+
"@antelopejs/tooling-configs": "^0.2.17",
|
|
59
73
|
"@types/mocha": "^10.0.10",
|
|
60
74
|
"@types/node": "^22.19.15",
|
|
61
75
|
"eslint-plugin-perfectionist": "^5.11.0",
|
|
62
76
|
"knip": "^6.34.0",
|
|
77
|
+
"lefthook": "^2.2.2",
|
|
63
78
|
"oxfmt": "^0.66.0",
|
|
64
79
|
"oxlint": "1.81.0",
|
|
65
80
|
"oxlint-tsgolint": "^7.0.2001",
|
|
@@ -76,6 +91,9 @@
|
|
|
76
91
|
"test": "src/antelope.test.ts",
|
|
77
92
|
"skills": [
|
|
78
93
|
"./skills"
|
|
79
|
-
]
|
|
94
|
+
],
|
|
95
|
+
"docs": {
|
|
96
|
+
"standard": true
|
|
97
|
+
}
|
|
80
98
|
}
|
|
81
99
|
}
|