@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.
@@ -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.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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. |