@antelopejs/interface-payment 0.0.0-stage → 0.0.1
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/LICENSE +190 -0
- package/README.md +127 -2
- package/dist/antelope.test.d.ts +2 -0
- package/dist/antelope.test.js +10 -0
- package/dist/antelope.test.js.map +1 -0
- package/dist/errors.d.ts +78 -0
- package/dist/errors.js +101 -0
- package/dist/errors.js.map +1 -0
- package/dist/functions.d.ts +228 -0
- package/dist/functions.js +232 -0
- package/dist/functions.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +20 -0
- package/dist/index.js.map +1 -0
- package/dist/tests/payment-charges.test.d.ts +1 -0
- package/dist/tests/payment-charges.test.js +188 -0
- package/dist/tests/payment-charges.test.js.map +1 -0
- package/dist/tests/payment.test.d.ts +1 -0
- package/dist/tests/payment.test.js +115 -0
- package/dist/tests/payment.test.js.map +1 -0
- package/dist/tests/support.d.ts +63 -0
- package/dist/tests/support.js +149 -0
- package/dist/tests/support.js.map +1 -0
- package/dist/types.d.ts +388 -0
- package/dist/types.js +87 -0
- package/dist/types.js.map +1 -0
- package/docs/1.introduction.md +91 -0
- package/docs/2.payments.md +233 -0
- package/docs/3.customers-and-methods.md +133 -0
- package/docs/4.webhooks.md +170 -0
- package/docs/5.provider-capability-matrix.md +147 -0
- package/docs/tsconfig.json +14 -0
- package/package.json +79 -4
- package/skills/taking-payments/SKILL.md +232 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"extends": "../tsconfig.json",
|
|
3
|
+
"compilerOptions": {
|
|
4
|
+
"noEmit": true,
|
|
5
|
+
"composite": false,
|
|
6
|
+
"incremental": false,
|
|
7
|
+
"rootDir": "..",
|
|
8
|
+
"baseUrl": "..",
|
|
9
|
+
"paths": {
|
|
10
|
+
"@antelopejs/interface-payment": ["src/index.ts"]
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"include": ["../src", "./**/*.ts"]
|
|
14
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,81 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-payment",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"description": "Provider-agnostic AntelopeJS payment interface: hosted checkout, direct payments with auth/capture, refunds, saved payment methods, and normalised webhook events",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"antelopejs",
|
|
7
|
+
"checkout",
|
|
8
|
+
"interface",
|
|
9
|
+
"payment",
|
|
10
|
+
"refund",
|
|
11
|
+
"webhook"
|
|
12
|
+
],
|
|
13
|
+
"homepage": "https://github.com/AntelopeJS/interface-payment/tree/main/docs",
|
|
14
|
+
"bugs": {
|
|
15
|
+
"url": "https://github.com/AntelopeJS/interface-payment/issues"
|
|
16
|
+
},
|
|
17
|
+
"license": "Apache-2.0",
|
|
18
|
+
"repository": {
|
|
19
|
+
"type": "git",
|
|
20
|
+
"url": "git+https://github.com/AntelopeJS/interface-payment.git"
|
|
21
|
+
},
|
|
22
|
+
"files": [
|
|
23
|
+
"dist",
|
|
24
|
+
"docs",
|
|
25
|
+
"skills"
|
|
26
|
+
],
|
|
27
|
+
"main": "dist/index.js",
|
|
28
|
+
"types": "dist/index.d.ts",
|
|
29
|
+
"exports": {
|
|
30
|
+
".": {
|
|
31
|
+
"types": "./dist/index.d.ts",
|
|
32
|
+
"default": "./dist/index.js"
|
|
33
|
+
},
|
|
34
|
+
"./tests/*": {
|
|
35
|
+
"types": "./dist/tests/*.d.ts",
|
|
36
|
+
"default": "./dist/tests/*.js"
|
|
37
|
+
},
|
|
38
|
+
"./package.json": "./package.json"
|
|
39
|
+
},
|
|
40
|
+
"publishConfig": {
|
|
41
|
+
"access": "public",
|
|
42
|
+
"provenance": false
|
|
43
|
+
},
|
|
44
|
+
"scripts": {
|
|
45
|
+
"build": "rimraf dist && tsc",
|
|
46
|
+
"test": "pnpm build && ajs module test .",
|
|
47
|
+
"format": "oxfmt .",
|
|
48
|
+
"lint:fix": "oxlint --fix",
|
|
49
|
+
"lint": "oxlint",
|
|
50
|
+
"prepack": "pnpm run build",
|
|
51
|
+
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
52
|
+
"format:check": "oxfmt --check .",
|
|
53
|
+
"knip": "knip"
|
|
54
|
+
},
|
|
55
|
+
"devDependencies": {
|
|
56
|
+
"@antelopejs/core": "1.16.0",
|
|
57
|
+
"@antelopejs/interface-core": ">=0.0.3 <1.0.0",
|
|
58
|
+
"@antelopejs/tooling-configs": "^0.0.8",
|
|
59
|
+
"@types/mocha": "^10.0.10",
|
|
60
|
+
"@types/node": "^22.19.15",
|
|
61
|
+
"eslint-plugin-perfectionist": "^5.11.0",
|
|
62
|
+
"knip": "^6.34.0",
|
|
63
|
+
"oxfmt": "^0.66.0",
|
|
64
|
+
"oxlint": "1.81.0",
|
|
65
|
+
"oxlint-tsgolint": "^7.0.2001",
|
|
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
|
+
"peerDependencies": {
|
|
72
|
+
"@antelopejs/interface-core": ">=0.0.3 <1.0.0"
|
|
73
|
+
},
|
|
74
|
+
"packageManager": "pnpm@10.6.5",
|
|
75
|
+
"antelopeJs": {
|
|
76
|
+
"test": "src/antelope.test.ts",
|
|
77
|
+
"skills": [
|
|
78
|
+
"./skills"
|
|
79
|
+
]
|
|
80
|
+
}
|
|
81
|
+
}
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: taking-payments
|
|
3
|
+
description: Takes and refunds AntelopeJS payments and verifies settlement. Use when adding checkout, saved payment methods, payment webhooks, or a payment provider implementation.
|
|
4
|
+
category: antelopejs-interface
|
|
5
|
+
tags: [payment, checkout, refund, webhook, stripe, antelopejs]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# payment interface
|
|
9
|
+
|
|
10
|
+
## Task workflow
|
|
11
|
+
|
|
12
|
+
1. Read `README.md` for the task entry point and peer requirements.
|
|
13
|
+
2. Choose hosted checkout or direct payment in `docs/2.payments.md`; use
|
|
14
|
+
`docs/3.customers-and-methods.md` when saving a method or charging off-session.
|
|
15
|
+
3. Persist one operation key and returned provider IDs. Replay only within the
|
|
16
|
+
provider-defined replay window. After expiration, reconcile uncertain payments
|
|
17
|
+
before retrying; the same key can create another charge.
|
|
18
|
+
4. Verify raw webhook bytes using `docs/4.webhooks.md`, deduplicate events, and
|
|
19
|
+
fulfil only after authenticated settlement. Completion means duplicate and
|
|
20
|
+
out-of-order deliveries cannot fulfil twice.
|
|
21
|
+
5. For provider work, run `pnpm test` for local contracts, then run the shipped
|
|
22
|
+
conformance suites against the configured provider; report skipped fixtures.
|
|
23
|
+
|
|
24
|
+
Use Stripe native subscriptions for Stripe recurring billing. Choose
|
|
25
|
+
`@antelopejs/payment-subscriptions` explicitly for a generic renewal clock;
|
|
26
|
+
assign one owner per subscription.
|
|
27
|
+
|
|
28
|
+
Provider-agnostic payments. Every call is an `InterfaceFunction` declaration,
|
|
29
|
+
so it is async and queues until a provider module attaches. This package
|
|
30
|
+
declares the contract and contains no provider logic.
|
|
31
|
+
|
|
32
|
+
For anything beyond this contract, use the provider's own interface
|
|
33
|
+
(`@antelopejs/interface-stripe`) alongside it. This interface has no escape
|
|
34
|
+
hatch by design — one would hand back a provider-shaped object and undo the
|
|
35
|
+
portability.
|
|
36
|
+
|
|
37
|
+
## Imports
|
|
38
|
+
|
|
39
|
+
Add `@antelopejs/interface-payment` to the module's `dependencies`:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import {
|
|
43
|
+
CreateCheckoutSession,
|
|
44
|
+
GetCheckoutSession,
|
|
45
|
+
CreatePayment,
|
|
46
|
+
GetPayment,
|
|
47
|
+
CapturePayment,
|
|
48
|
+
CancelPayment,
|
|
49
|
+
RefundPayment,
|
|
50
|
+
GetRefund,
|
|
51
|
+
CreateCustomer,
|
|
52
|
+
GetCustomer,
|
|
53
|
+
DeleteCustomer,
|
|
54
|
+
ListPaymentMethods,
|
|
55
|
+
DetachPaymentMethod,
|
|
56
|
+
VerifyWebhook,
|
|
57
|
+
isTerminalPaymentStatus,
|
|
58
|
+
PaymentError,
|
|
59
|
+
PaymentNotFoundError,
|
|
60
|
+
CustomerNotFoundError,
|
|
61
|
+
InvalidPaymentStateError,
|
|
62
|
+
WebhookVerificationError,
|
|
63
|
+
UnsupportedOperationError,
|
|
64
|
+
PAYMENT_STATUSES,
|
|
65
|
+
PAYMENT_EVENT_TYPES,
|
|
66
|
+
} from "@antelopejs/interface-payment";
|
|
67
|
+
import type {
|
|
68
|
+
Amount,
|
|
69
|
+
Payment,
|
|
70
|
+
PaymentRequest,
|
|
71
|
+
PaymentStatus,
|
|
72
|
+
PaymentFailure,
|
|
73
|
+
CheckoutSession,
|
|
74
|
+
CheckoutSessionRequest,
|
|
75
|
+
Refund,
|
|
76
|
+
RefundRequest,
|
|
77
|
+
Customer,
|
|
78
|
+
PaymentMethod,
|
|
79
|
+
PaymentEvent,
|
|
80
|
+
WebhookRequest,
|
|
81
|
+
Dispute,
|
|
82
|
+
} from "@antelopejs/interface-payment";
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Four rules that are easy to get wrong
|
|
86
|
+
|
|
87
|
+
1. **Amounts are integer minor units.** `{ value: 1050, currency: "EUR" }` is
|
|
88
|
+
€10.50. Never a float. `JPY` has no subunit; `KWD` has three decimals.
|
|
89
|
+
2. **Every mutating call takes an idempotency key**, positionally, right after
|
|
90
|
+
the request. Derive it from your own record so a retry reuses it.
|
|
91
|
+
3. **A decline is not a throw.** `CreatePayment` resolves with
|
|
92
|
+
`status: "failed"` and a `failure`. It rejects only if the call could not be
|
|
93
|
+
made.
|
|
94
|
+
4. **The payer's return is not proof.** Fulfil from the webhook, not from
|
|
95
|
+
`successUrl`.
|
|
96
|
+
|
|
97
|
+
## Taking a payment (hosted checkout)
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
const session = await CreateCheckoutSession(
|
|
101
|
+
{
|
|
102
|
+
amount: { value: 4999, currency: "EUR" },
|
|
103
|
+
reference: orderId,
|
|
104
|
+
successUrl: `https://shop.example/orders/${orderId}/thanks`,
|
|
105
|
+
cancelUrl: `https://shop.example/orders/${orderId}/cart`,
|
|
106
|
+
},
|
|
107
|
+
idempotencyKey,
|
|
108
|
+
);
|
|
109
|
+
response.redirect(session.redirectUrl);
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
On return: `GetCheckoutSession(id)` → `session.payment` → `GetPayment(...)`.
|
|
113
|
+
|
|
114
|
+
## Status
|
|
115
|
+
|
|
116
|
+
`pending` · `requires_action` · `authorized` · `succeeded` · `failed` ·
|
|
117
|
+
`canceled`. The last three are terminal (`isTerminalPaymentStatus`).
|
|
118
|
+
|
|
119
|
+
`redirectUrl` is set exactly when `requires_action`; `failure` exactly when
|
|
120
|
+
`failed`. Branch on the status alone.
|
|
121
|
+
|
|
122
|
+
## Authorize then capture
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
const auth = await CreatePayment({ ...request, authorizeOnly: true }, key);
|
|
126
|
+
const captured = await CapturePayment(auth.id, captureKey, {
|
|
127
|
+
value: 3999,
|
|
128
|
+
currency: "EUR",
|
|
129
|
+
});
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Capturing less than authorized releases the rest — there is no second capture
|
|
133
|
+
against one authorization. `CancelPayment` voids an uncaptured payment.
|
|
134
|
+
|
|
135
|
+
## Saved methods and recurring
|
|
136
|
+
|
|
137
|
+
Subscriptions are deliberately not modelled. Run your own cycle:
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
const [method] = await ListPaymentMethods(customerId);
|
|
141
|
+
await CreatePayment(
|
|
142
|
+
{
|
|
143
|
+
amount,
|
|
144
|
+
reference: `sub-${userId}-${period}`,
|
|
145
|
+
customer: customerId,
|
|
146
|
+
paymentMethod: method.id,
|
|
147
|
+
offSession: true,
|
|
148
|
+
},
|
|
149
|
+
`renewal-${userId}-${period}`,
|
|
150
|
+
);
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
A method is saved as a side effect of a payment — `savePaymentMethod: true` with
|
|
154
|
+
a `customer` set, on either a checkout session or a `CreatePayment`. It appears
|
|
155
|
+
in `ListPaymentMethods` once the payment reaches `succeeded` or `authorized`,
|
|
156
|
+
not as soon as the call returns.
|
|
157
|
+
|
|
158
|
+
`Customer` guarantees only `id`. PayPal and Adyen store no email or name; keep
|
|
159
|
+
the payer's details in your own records.
|
|
160
|
+
|
|
161
|
+
## Webhooks
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
const event = await VerifyWebhook({ body: rawBuffer, headers });
|
|
165
|
+
if (!event) return new HTTPResult(200, "Ignored");
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
- A `PaymentEvent` — handle it.
|
|
169
|
+
- `undefined` — genuine but unmodelled. Respond 200; providers send many.
|
|
170
|
+
- Throws `WebhookVerificationError` — respond 403, act on nothing.
|
|
171
|
+
|
|
172
|
+
Not necessarily a signature check: providers that do not sign (Mollie,
|
|
173
|
+
Mangopay) send a bare record id and the implementation confirms it by reading
|
|
174
|
+
that record back. Both satisfy the same contract.
|
|
175
|
+
|
|
176
|
+
**If you implement a re-fetch provider, the body is a pointer and nothing else.**
|
|
177
|
+
A signature authenticates the whole body; a re-fetch authenticates one record and
|
|
178
|
+
proves nothing about any other field in the body. Derive the event's `type`, the
|
|
179
|
+
kind of record it is, and every field of `payment`/`refund`/`dispute` from the
|
|
180
|
+
record you read back — never from a type field in the body. Taking
|
|
181
|
+
Mangopay's `EventType` from the body after re-fetching `RessourceId` accepts a
|
|
182
|
+
forged payment state from anyone who can reach the endpoint.
|
|
183
|
+
|
|
184
|
+
Body must be **raw bytes**, not re-serialised JSON.
|
|
185
|
+
|
|
186
|
+
Types: `payment.pending|authorized|succeeded|failed|canceled`,
|
|
187
|
+
`refund.succeeded|failed`, `dispute.opened`.
|
|
188
|
+
|
|
189
|
+
De-duplicate on `event.id`, and do not assume an event is newer than the state
|
|
190
|
+
you hold — deliveries repeat and arrive out of order.
|
|
191
|
+
|
|
192
|
+
## Implementing this interface
|
|
193
|
+
|
|
194
|
+
Declare `"antelopeJs": { "implements": ["@antelopejs/interface-payment"] }` and
|
|
195
|
+
attach the whole module, the way `@antelopejs/mongodb` does:
|
|
196
|
+
|
|
197
|
+
```ts
|
|
198
|
+
import { ImplementInterface } from "@antelopejs/interface-core";
|
|
199
|
+
import * as payment from "@antelopejs/interface-payment";
|
|
200
|
+
|
|
201
|
+
await ImplementInterface(payment, await import("./implementations/payment"));
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
Export one function per declared call, named **exactly** as the call is —
|
|
205
|
+
`CreatePayment`, `GetPayment`, `CapturePayment` and so on. The names a consumer
|
|
206
|
+
calls are the attachment points; there is no separate lowercase proxy.
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
export async function CreatePayment(request, idempotencyKey, provider) {
|
|
210
|
+
/* ... */
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Extra exports alongside them are fine, so the implementation can be split across
|
|
215
|
+
files and re-exported from a barrel.
|
|
216
|
+
|
|
217
|
+
Then run the shipped conformance suite against your module, with
|
|
218
|
+
`ANTELOPE_PAYMENT_TEST_METHOD` set to a chargeable provider test token:
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
// src/test/conformance.test.ts
|
|
222
|
+
import "@antelopejs/interface-payment/tests/payment.test";
|
|
223
|
+
import "@antelopejs/interface-payment/tests/payment-charges.test";
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Conformance fixtures
|
|
227
|
+
|
|
228
|
+
| Variable | Purpose |
|
|
229
|
+
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
230
|
+
| `ANTELOPE_PAYMENT_TEST_METHOD` | A provider test token `CreatePayment` charges successfully. Without it the charge, capture and refund blocks skip by name. |
|
|
231
|
+
| `ANTELOPE_PAYMENT_TEST_METHOD_DECLINED` | A provider test token that declines. Without it the decline block skips. |
|
|
232
|
+
| `ANTELOPE_PAYMENT_TEST_CURRENCY` | ISO-4217 code to run against. Defaults to `EUR`; set it when the test account cannot settle euros. |
|