@antelopejs/interface-payment 0.1.0 → 0.2.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/README.md CHANGED
@@ -1,15 +1,18 @@
1
- # @antelopejs/interface-payment
1
+ # `@antelopejs/interface-payment`
2
2
 
3
3
  <div align="center">
4
- <a href="https://www.npmjs.com/package/@antelopejs/interface-payment"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-payment?style=for-the-badge&labelColor=000000&color=000000"></a>
5
- <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-payment?style=for-the-badge&labelColor=000000&color=000000"></a>
6
- <a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
7
- <a href="./docs/1.introduction.md"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
4
+ <a href="https://www.npmjs.com/package/@antelopejs/interface-payment"><img data-illustration alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-payment?style=for-the-badge&labelColor=000000&color=000000"></a>
5
+ <a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-payment?style=for-the-badge&labelColor=000000&color=000000"></a>
6
+ <a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
7
+ <a href="./docs/1.introduction.md"><img data-illustration alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
8
8
  </div>
9
9
 
10
- Provider-agnostic payment interface for AntelopeJS. Take payments, refund them,
11
- save payment methods and react to settlement events without naming a provider —
12
- and change provider by swapping the module wired underneath.
10
+ The provider-agnostic payment interface for AntelopeJS. You take payments,
11
+ refund them, save payment methods, and react to settlement events without naming
12
+ a provider. To change provider, you swap the module that implements the
13
+ interface.
14
+
15
+ Part of [AntelopeJS](https://github.com/AntelopeJS/antelopejs), the TypeScript framework where modules depend on contracts and the application chooses the provider. Built by the team behind [AntelopeJS DMS](https://github.com/AntelopeJS/dms).
13
16
 
14
17
  ## Installation
15
18
 
@@ -18,7 +21,8 @@ pnpm add @antelopejs/interface-payment
18
21
  ```
19
22
 
20
23
  This package declares the contract and ships no provider logic. Wire a module
21
- that implements it — `@antelopejs/stripe` — in your Antelope config.
24
+ that implements it, such as `@antelopejs/stripe`, in your AntelopeJS project
25
+ config.
22
26
 
23
27
  ## What it covers
24
28
 
@@ -30,9 +34,9 @@ that implements it — `@antelopejs/stripe` — in your Antelope config.
30
34
  | Customers and saved methods | `CreateCustomer`, `GetCustomer`, `DeleteCustomer`, `ListPaymentMethods`, `DetachPaymentMethod` |
31
35
  | Webhooks | `VerifyWebhook` |
32
36
 
33
- Subscriptions, marketplace split payments, dispute management, payment links and
34
- in-person terminals are deliberately out of scope — they are where providers
35
- diverge most. For anything beyond this contract, use the provider's own interface
37
+ Subscriptions, marketplace split payments, dispute management, payment links,
38
+ and in-person terminals are out of scope on purpose. Providers differ most in
39
+ those areas. For anything beyond this contract, use the provider's own interface
36
40
  (`@antelopejs/interface-stripe`) alongside this one.
37
41
 
38
42
  ## Quick start
@@ -53,17 +57,19 @@ export async function startCheckout(orderId: string, idempotencyKey: string) {
53
57
  }
54
58
  ```
55
59
 
56
- Generate and persist one idempotency key per checkout attempt, and reuse it on
57
- retries. Call `startCheckout` from your authenticated checkout route, persist the
58
- returned session ID against the order, and redirect the payer to `redirectUrl`.
59
- Use your own return URLs and configure the provider credentials and webhook route.
60
+ Generate one idempotency key per checkout attempt, persist it, and reuse it on
61
+ retries. Call `startCheckout` from your authenticated checkout route. Persist the
62
+ returned session ID against the order, then redirect the payer to
63
+ `redirectUrl`. Use your own return URLs, and configure the provider credentials
64
+ and the webhook route.
60
65
 
61
66
  Fulfil the order from the `payment.succeeded` webhook, not from the payer's
62
- return — the browser is not a trustworthy reporter.
67
+ return. The payer's browser can reach `successUrl` without a payment behind it.
63
68
 
64
69
  Replay protection lasts only for the provider-defined replay window. Persist
65
- operation keys and provider IDs; after expiration, reconcile uncertain payments
66
- with provider records before retrying. A reused key can otherwise charge again.
70
+ operation keys and provider IDs. After the window expires, reconcile uncertain
71
+ payments with the provider's records before you retry. Otherwise a reused key
72
+ can charge the payer again.
67
73
 
68
74
  ## Choose a task
69
75
 
@@ -71,52 +77,55 @@ with provider records before retrying. A reused key can otherwise charge again.
71
77
  - Save a method or charge off-session: [customers and methods](./docs/3.customers-and-methods.md).
72
78
  - Confirm settlement safely: [webhooks](./docs/4.webhooks.md).
73
79
  - Add a provider: [capabilities and conformance](./docs/5.provider-capability-matrix.md).
74
- - Add recurring billing: use Stripe's native subscriptions through
75
- `@antelopejs/interface-subscriptions` when using Stripe. Choose
76
- `@antelopejs/payment-subscriptions` explicitly when you want a generic renewal
77
- clock instead; do not run both clocks for the same subscription.
80
+ - Add recurring billing with Stripe: use Stripe's native subscriptions through
81
+ `@antelopejs/interface-subscriptions`. To run a generic renewal clock instead,
82
+ choose `@antelopejs/payment-subscriptions` explicitly. Do not run both clocks
83
+ for the same subscription.
78
84
 
79
85
  ## Compatibility
80
86
 
81
- <!-- docs-compat: ./package.json#peerDependencies -->
87
+ <!-- antelopejs-docs-compat:start -->
88
+
89
+ | Package | Supported | Tested with |
90
+ | ---------------------------- | ---------------- | ----------- |
91
+ | `@antelopejs/interface-core` | `>=0.0.3 <1.0.0` | `0.0.12` |
82
92
 
83
- | Package | Range |
84
- | ---------------------------- | ---------------- |
85
- | `@antelopejs/interface-core` | `>=0.0.3 <1.0.0` |
93
+ <!-- antelopejs-docs-compat:end -->
86
94
 
87
- These are the peer requirements in `package.json`, not development or test-tool
88
- ranges. The implementing module may impose additional requirements.
95
+ The table lists the peer requirements in `package.json`, not the development or
96
+ test-tool ranges. The implementing module can add requirements of its own.
89
97
 
90
98
  ## Conventions
91
99
 
92
100
  - **Integer minor units.** `{ value: 1050, currency: "EUR" }` is €10.50, never a float.
93
- - **An idempotency key on every mutating call**, positionally after the request.
101
+ - **An idempotency key on every mutating call.** The key is the positional argument after the request.
94
102
  - **Opaque provider identifiers.** Do not parse them.
95
103
  - **A decline is a result, not an exception.** `CreatePayment` resolves with
96
- `status: "failed"`; it rejects only when the call could not be made.
97
- - **An optional trailing `provider`** selects between configured accounts.
104
+ `status: "failed"`. It rejects only when the call itself could not be made.
105
+ - **An optional trailing `provider` argument.** It selects one of several configured accounts.
98
106
 
99
107
  ## Documentation
100
108
 
101
- | Document | Contents |
102
- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
103
- | [Introduction](./docs/1.introduction.md) | Scope, conventions, installation |
104
- | [Payments](./docs/2.payments.md) | Checkout, direct payments, authorize/capture, errors |
105
- | [Customers and methods](./docs/3.customers-and-methods.md) | Saved methods, off-session and recurring charges |
106
- | [Webhooks](./docs/4.webhooks.md) | Verification, the event set, handling |
107
- | [Provider capability matrix](./docs/5.provider-capability-matrix.md) | What each provider family does behind each call, and why the scope is what it is |
109
+ | Document | Contents |
110
+ | -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
111
+ | [Introduction](./docs/1.introduction.md) | Scope, conventions, and installation |
112
+ | [Payments](./docs/2.payments.md) | Checkout, direct payments, authorize and capture, refunds, and errors |
113
+ | [Customers and methods](./docs/3.customers-and-methods.md) | Saved methods, and off-session and recurring charges |
114
+ | [Webhooks](./docs/4.webhooks.md) | Verification, the event set, and handling |
115
+ | [Provider capability matrix](./docs/5.provider-capability-matrix.md) | What each provider family does behind each call, and why the scope is set |
108
116
 
109
117
  ## Conformance suite
110
118
 
111
- `src/tests/payment.test.ts` ships in the package and runs against whichever
112
- provider module is wired in. It is written against the contract, not against any
113
- one provider's behaviour, and it is what a new provider implementation is held
114
- to.
119
+ The package ships a conformance suite, `src/tests/payment.test.ts` and
120
+ `src/tests/payment-charges.test.ts`. The build publishes it as
121
+ `@antelopejs/interface-payment/tests/*`, and it runs against whichever provider
122
+ module is wired in. The suite tests the contract, not one provider's behavior. A
123
+ new provider implementation must pass it.
115
124
 
116
- Session creation, customer lifecycle, idempotency replay, unknown-identifier
117
- errors and webhook rejection need no fixture and cannot pass without a live
118
- provider — with nothing implementing the interface the proxies queue and the
119
- suite times out rather than reporting green.
125
+ Session creation, the customer lifecycle, idempotency replay, unknown-identifier
126
+ errors, and webhook rejection need no fixture. They also cannot pass without a
127
+ live provider. With nothing implementing the interface, the calls queue and the
128
+ suite times out instead of reporting green.
120
129
 
121
130
  The charge tests need a provider test token, because there is no portable way to
122
131
  mint a chargeable payment method:
@@ -129,7 +138,8 @@ mint a chargeable payment method:
129
138
 
130
139
  ## Contributing
131
140
 
132
- Read [CONTRIBUTING.md](./CONTRIBUTING.md). Use Node.js 24 and pnpm 10.6.5:
141
+ Read [CONTRIBUTING.md](./CONTRIBUTING.md). Use the Node.js version in `.nvmrc`
142
+ and the pnpm version in the `packageManager` field of `package.json`:
133
143
 
134
144
  ```bash
135
145
  pnpm install --frozen-lockfile
@@ -139,7 +149,9 @@ pnpm format:check
139
149
  pnpm knip
140
150
  ```
141
151
 
142
- `pnpm test` runs local contract tests through the AntelopeJS runner without a payment provider or credentials. The provider conformance suite described above is a separate integration check.
152
+ `pnpm test` runs the local contract tests through the AntelopeJS runner, with no
153
+ payment provider and no credentials. The provider conformance suite above is a
154
+ separate integration check.
143
155
 
144
156
  ## License
145
157
 
@@ -22,6 +22,7 @@ const index_1 = require("../index");
22
22
  exports.SUITE_TIMEOUT = 60_000;
23
23
  const SETTLE_TIMEOUT = 30_000;
24
24
  const SETTLE_INTERVAL = 1_000;
25
+ const SETTLE_FIRST_POLL = 50;
25
26
  exports.CHARGE_VALUE = 2500;
26
27
  exports.PARTIAL_VALUE = 1000;
27
28
  exports.REFUND_VALUE = 700;
@@ -99,6 +100,36 @@ function assertPaymentContract(payment, expected) {
99
100
  strict_1.default.equal(payment.redirectUrl !== undefined, payment.status === "requires_action", "redirectUrl is present exactly when the payer must act");
100
101
  strict_1.default.equal(payment.failure !== undefined, payment.status === "failed", "failure is present exactly when the payment failed");
101
102
  }
103
+ /**
104
+ * Reads the payment until `done` holds or the settle deadline passes.
105
+ *
106
+ * A fixed poll reads one second after each read ends, and so does this one.
107
+ * Most payments settle within milliseconds, so extra reads come after the
108
+ * previous read ends, 50 ms first and twice as long each time, whenever one
109
+ * fits, at the last read's latency, before the next one-second read. With a
110
+ * steady read latency, a payment is never seen later than the fixed poll would
111
+ * have seen it.
112
+ */
113
+ async function pollPayment(id, done) {
114
+ const deadline = Date.now() + SETTLE_TIMEOUT;
115
+ let gap = SETTLE_FIRST_POLL;
116
+ let readStart = Date.now();
117
+ let payment = await (0, index_1.GetPayment)(id);
118
+ let readEnd = Date.now();
119
+ let intervalReadAt = readEnd + SETTLE_INTERVAL;
120
+ while (!done(payment) && Date.now() < deadline) {
121
+ const earlyAt = readEnd + gap;
122
+ const isEarly = earlyAt + (readEnd - readStart) <= intervalReadAt;
123
+ gap *= 2;
124
+ await (0, promises_1.setTimeout)(Math.max(0, (isEarly ? earlyAt : intervalReadAt) - Date.now()));
125
+ readStart = Date.now();
126
+ payment = await (0, index_1.GetPayment)(id);
127
+ readEnd = Date.now();
128
+ if (!isEarly)
129
+ intervalReadAt = readEnd + SETTLE_INTERVAL;
130
+ }
131
+ return payment;
132
+ }
102
133
  /**
103
134
  * Polls until the payment leaves the states it can leave on its own.
104
135
  *
@@ -107,14 +138,7 @@ function assertPaymentContract(payment, expected) {
107
138
  * promises a terminal state is reachable without payer action for these flows.
108
139
  */
109
140
  async function settle(id, expected) {
110
- const deadline = Date.now() + SETTLE_TIMEOUT;
111
- let payment = await (0, index_1.GetPayment)(id);
112
- while (payment.status !== expected &&
113
- !(0, index_1.isTerminalPaymentStatus)(payment.status) &&
114
- Date.now() < deadline) {
115
- await (0, promises_1.setTimeout)(SETTLE_INTERVAL);
116
- payment = await (0, index_1.GetPayment)(id);
117
- }
141
+ const payment = await pollPayment(id, (read) => read.status === expected || (0, index_1.isTerminalPaymentStatus)(read.status));
118
142
  strict_1.default.equal(payment.status, expected, `payment ${id} reached ${payment.status}, not ${expected}`);
119
143
  return payment;
120
144
  }
@@ -146,12 +170,7 @@ async function charge() {
146
170
  * the deadline is the failure this exists to catch.
147
171
  */
148
172
  async function settleRefundedTotal(id) {
149
- const deadline = Date.now() + SETTLE_TIMEOUT;
150
- let payment = await (0, index_1.GetPayment)(id);
151
- while (payment.amountRefunded.value === 0 && Date.now() < deadline) {
152
- await (0, promises_1.setTimeout)(SETTLE_INTERVAL);
153
- payment = await (0, index_1.GetPayment)(id);
154
- }
173
+ const payment = await pollPayment(id, (read) => read.amountRefunded.value !== 0);
155
174
  strict_1.default.notEqual(payment.amountRefunded.value, 0, `payment ${id} still reports nothing refunded after a settled refund`);
156
175
  return payment.amountRefunded;
157
176
  }
@@ -1 +1 @@
1
- {"version":3,"file":"support.js","sourceRoot":"","sources":["../../src/tests/support.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"support.js","sourceRoot":"","sources":["../../src/tests/support.ts"],"names":[],"mappings":"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"}
package/dist/types.d.ts CHANGED
@@ -150,6 +150,18 @@ export interface PaymentRequest {
150
150
  /** Round-tripped opaque key/value pairs. */
151
151
  metadata?: Record<string, string>;
152
152
  }
153
+ /**
154
+ * Every value {@link PaymentLocale} can take: the hosted page languages
155
+ * Stripe Checkout accepts. `auto` lets the provider pick from the payer's
156
+ * browser.
157
+ */
158
+ export declare const PAYMENT_LOCALES: readonly ["auto", "bg", "cs", "da", "de", "el", "en", "en-GB", "es", "es-419", "et", "fi", "fil", "fr", "fr-CA", "hr", "hu", "id", "it", "ja", "ko", "lt", "lv", "ms", "mt", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sk", "sl", "sv", "th", "tr", "vi", "zh", "zh-HK", "zh-TW"];
159
+ /**
160
+ * Language of a hosted checkout page. Providers that name their languages
161
+ * differently map each value to their own code, and fall back to their own
162
+ * default where they have no match.
163
+ */
164
+ export type PaymentLocale = (typeof PAYMENT_LOCALES)[number];
153
165
  /**
154
166
  * Parameters for {@link CreateCheckoutSession}.
155
167
  */
@@ -178,8 +190,8 @@ export interface CheckoutSessionRequest {
178
190
  savePaymentMethod?: boolean;
179
191
  /** Shown to the payer where supported. */
180
192
  description?: string;
181
- /** BCP-47 language tag for the hosted page, where supported. */
182
- locale?: string;
193
+ /** Language of the hosted page, where supported. */
194
+ locale?: PaymentLocale;
183
195
  /** Round-tripped opaque key/value pairs. */
184
196
  metadata?: Record<string, string>;
185
197
  }
package/dist/types.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.PAYMENT_EVENT_TYPES = exports.PAYMENT_METHOD_TYPES = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.PAYMENT_FAILURE_CODES = exports.TERMINAL_PAYMENT_STATUSES = exports.PAYMENT_STATUSES = void 0;
3
+ exports.PAYMENT_EVENT_TYPES = exports.PAYMENT_METHOD_TYPES = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.PAYMENT_LOCALES = exports.PAYMENT_FAILURE_CODES = exports.TERMINAL_PAYMENT_STATUSES = exports.PAYMENT_STATUSES = void 0;
4
4
  exports.isTerminalPaymentStatus = isTerminalPaymentStatus;
5
5
  /**
6
6
  * Every value {@link PaymentStatus} can take, in lifecycle order.
@@ -45,6 +45,54 @@ exports.PAYMENT_FAILURE_CODES = Object.freeze([
45
45
  "expired",
46
46
  "processing_error",
47
47
  ]);
48
+ /**
49
+ * Every value {@link PaymentLocale} can take: the hosted page languages
50
+ * Stripe Checkout accepts. `auto` lets the provider pick from the payer's
51
+ * browser.
52
+ */
53
+ exports.PAYMENT_LOCALES = Object.freeze([
54
+ "auto",
55
+ "bg",
56
+ "cs",
57
+ "da",
58
+ "de",
59
+ "el",
60
+ "en",
61
+ "en-GB",
62
+ "es",
63
+ "es-419",
64
+ "et",
65
+ "fi",
66
+ "fil",
67
+ "fr",
68
+ "fr-CA",
69
+ "hr",
70
+ "hu",
71
+ "id",
72
+ "it",
73
+ "ja",
74
+ "ko",
75
+ "lt",
76
+ "lv",
77
+ "ms",
78
+ "mt",
79
+ "nb",
80
+ "nl",
81
+ "pl",
82
+ "pt",
83
+ "pt-BR",
84
+ "ro",
85
+ "ru",
86
+ "sk",
87
+ "sl",
88
+ "sv",
89
+ "th",
90
+ "tr",
91
+ "vi",
92
+ "zh",
93
+ "zh-HK",
94
+ "zh-TW",
95
+ ]);
48
96
  /** Normalised refund lifecycle. */
49
97
  exports.REFUND_STATUSES = Object.freeze([
50
98
  "pending",
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAwDA,0DAEC;AA3CD;;GAEG;AACU,QAAA,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,SAAS;IACT,iBAAiB;IACjB,YAAY;IACZ,WAAW;IACX,QAAQ;IACR,UAAU;CACF,CAAC,CAAC;AAgBZ;;GAEG;AACU,QAAA,yBAAyB,GACpC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;AAErD;;;;;;;;GAQG;AACH,SAAgB,uBAAuB,CAAC,MAAqB;IAC3D,OAAO,iCAAyB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,UAAU;IACV,oBAAoB;IACpB,cAAc;IACd,mBAAmB;IACnB,uBAAuB;IACvB,mBAAmB;IACnB,SAAS;IACT,kBAAkB;CACV,CAAC,CAAC;AAkKZ,mCAAmC;AACtB,QAAA,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,SAAS;IACT,WAAW;IACX,QAAQ;CACA,CAAC,CAAC;AAUZ;;GAEG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,WAAW;IACX,YAAY;IACZ,uBAAuB;IACvB,OAAO;CACC,CAAC,CAAC;AAwEZ,gDAAgD;AACnC,QAAA,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,MAAM;IACN,QAAQ;IACR,cAAc;IACd,OAAO;CACC,CAAC,CAAC;AAyDZ;;;;;;GAMG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;IACnB,gBAAgB;IAChB,kBAAkB;IAClB,kBAAkB;IAClB,eAAe;IACf,gBAAgB;CACR,CAAC,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAwDA,0DAEC;AA3CD;;GAEG;AACU,QAAA,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,SAAS;IACT,iBAAiB;IACjB,YAAY;IACZ,WAAW;IACX,QAAQ;IACR,UAAU;CACF,CAAC,CAAC;AAgBZ;;GAEG;AACU,QAAA,yBAAyB,GACpC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;AAErD;;;;;;;;GAQG;AACH,SAAgB,uBAAuB,CAAC,MAAqB;IAC3D,OAAO,iCAAyB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,UAAU;IACV,oBAAoB;IACpB,cAAc;IACd,mBAAmB;IACnB,uBAAuB;IACvB,mBAAmB;IACnB,SAAS;IACT,kBAAkB;CACV,CAAC,CAAC;AA0GZ;;;;GAIG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,MAAM;IACN,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,QAAQ;IACR,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,OAAO;IACP,OAAO;CACC,CAAC,CAAC;AAiEZ,mCAAmC;AACtB,QAAA,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,SAAS;IACT,WAAW;IACX,QAAQ;CACA,CAAC,CAAC;AAUZ;;GAEG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,WAAW;IACX,YAAY;IACZ,uBAAuB;IACvB,OAAO;CACC,CAAC,CAAC;AAwEZ,gDAAgD;AACnC,QAAA,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,MAAM;IACN,QAAQ;IACR,cAAc;IACd,OAAO;CACC,CAAC,CAAC;AAyDZ;;;;;;GAMG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;IACnB,gBAAgB;IAChB,kBAAkB;IAClB,kBAAkB;IAClB,eAAe;IACf,gBAAgB;CACR,CAAC,CAAC"}
@@ -1,9 +1,13 @@
1
- # Introduction
1
+ ---
2
+ title: Introduction
3
+ description: What the payment interface covers, what it leaves out and why, and the conventions every function follows.
4
+ mode: explanation
5
+ ---
2
6
 
3
7
  `@antelopejs/interface-payment` defines a provider-agnostic payment interface for
4
8
  AntelopeJS applications. A backend written against it takes payments, refunds
5
- them, saves payment methods and reacts to settlement events without naming a
6
- provider, and can change provider by swapping the module wired underneath.
9
+ them, saves payment methods, and reacts to settlement events without naming a
10
+ provider. To change provider, it swaps the module that implements the interface.
7
11
 
8
12
  ## What it covers
9
13
 
@@ -17,24 +21,28 @@ provider, and can change provider by swapping the module wired underneath.
17
21
 
18
22
  ## What it deliberately does not cover
19
23
 
20
- Subscriptions, invoicing, proration, dunning, tax and coupons; marketplace split
21
- payments; dispute _management_; payment links; in-person terminals.
24
+ The interface leaves out these areas:
22
25
 
23
- These are where providers diverge most, and modelling them would mean an
24
- interface most implementations could only decline. For recurring access, use
25
- `@antelopejs/interface-subscriptions`: Stripe native billing is recommended with
26
- Stripe. Choose `@antelopejs/payment-subscriptions` explicitly when you need a
27
- generic clock on saved methods and off-session charges. Each subscription must
28
- have one renewal owner; provider-specific billing features remain outside the
29
- portable contract.
30
- [Provider capability matrix](./5.provider-capability-matrix.md) has the reasoning
31
- per feature.
26
+ - subscriptions, invoicing, proration, dunning, tax, and coupons
27
+ - marketplace split payments
28
+ - dispute _management_
29
+ - payment links
30
+ - in-person terminals
31
+
32
+ Providers differ most in these areas. Modelling them would produce an interface
33
+ that most implementations could only decline. For recurring access, use
34
+ `@antelopejs/interface-subscriptions`. With Stripe, use Stripe's native billing.
35
+ Choose `@antelopejs/payment-subscriptions` explicitly when you need a generic
36
+ renewal clock on saved methods and off-session charges. Give each subscription
37
+ one renewal owner. Billing features specific to one provider stay outside the
38
+ portable contract. The [provider capability matrix](./5.provider-capability-matrix.md)
39
+ gives the reasoning for each feature.
32
40
 
33
41
  When a backend needs something beyond this contract, it uses the provider's own
34
- interface — `@antelopejs/interface-stripe` for Stripe — alongside this one. That
35
- is the escape hatch, and it is why this interface does not have one of its own:
36
- an escape hatch here would hand back a provider-shaped object and quietly undo
37
- the portability the interface exists for.
42
+ interface alongside this one, such as `@antelopejs/interface-stripe` for Stripe.
43
+ That is the way out of the contract, so this interface has no escape hatch of
44
+ its own. An escape hatch here would return an object shaped by one provider, and
45
+ code that used it would no longer be portable.
38
46
 
39
47
  ## Installation
40
48
 
@@ -42,50 +50,57 @@ the portability the interface exists for.
42
50
  pnpm add @antelopejs/interface-payment
43
51
  ```
44
52
 
45
- Add a module that implements it to your Antelope config; this package declares
46
- the contract and ships no provider logic.
53
+ This package declares the contract and ships no provider logic. Add a module that
54
+ implements it to your AntelopeJS project config.
47
55
 
48
56
  ## Conventions
49
57
 
50
- These hold across every function, and an implementation that breaks one is
51
- non-conformant.
58
+ These conventions hold for every function. An implementation that breaks one
59
+ does not conform to the contract.
52
60
 
53
61
  **Amounts are integer minor units.** `{ value: 1050, currency: "EUR" }` is €10.50.
54
- Never a float: binary floating point cannot represent most decimal amounts, and
55
- providers round differently when you hand them one. `JPY` has no subunit, so
62
+ Never use a float. Binary floating point cannot represent most decimal amounts,
63
+ and providers round a float differently. `JPY` has no subunit, so
56
64
  `{ value: 1050, currency: "JPY" }` is ¥1050. `KWD` has three decimal places.
57
- Every derived amount on a `Payment` — `amountCaptured`, `amountRefunded` — is in
65
+ The derived amounts on a `Payment`, `amountCaptured` and `amountRefunded`, are in
58
66
  the same currency as `amount`.
59
67
 
60
- **Every mutating call takes an idempotency key.** Payments are the canonical case
61
- where a retried request must not do the work twice. Generate one key per
62
- logical operation, store it with your own record, and reuse it on retry: the
63
- provider returns the original result within its provider-defined replay window.
64
- Reads take no key. After expiration, applications must reconcile uncertain
65
- payments with provider records before retrying; a reused key can charge again.
68
+ **Every mutating call takes an idempotency key.** A retried payment request must
69
+ not do the work twice. Generate one key per logical operation, store it with your
70
+ own record, and reuse it on retry. Within its provider-defined replay window, the
71
+ provider returns the original result. Reads take no key. After the window
72
+ expires, reconcile uncertain payments with the provider's records before you
73
+ retry, because a reused key can charge again.
66
74
 
67
75
  **Provider identifiers are opaque.** `Payment.id`, `Refund.id`, `Customer.id`,
68
- `PaymentMethod.id` and `CheckoutSession.id` are the provider's own strings. Do
69
- not parse them, do not infer a type from a prefix, and do not assume two
70
- providers shape them alike. Correlate with your own records through
76
+ `PaymentMethod.id`, and `CheckoutSession.id` are the provider's own strings. Do
77
+ not parse them, do not infer a type from a prefix, and do not assume that two
78
+ providers shape them alike. Correlate them with your own records through
71
79
  `reference` and `metadata`.
72
80
 
73
81
  **A failed payment is not a thrown error.** `CreatePayment` resolves with a
74
- `Payment` whose status is `failed`; it rejects only when the call itself could
82
+ `Payment` whose status is `failed`. It rejects only when the call itself could
75
83
  not be made. See [Payments](./2.payments.md).
76
84
 
77
85
  **Settlement is asynchronous.** Every provider this interface targets settles
78
- some payments after the call returns, and some after the payer has left. A
79
- terminal state is learned from `VerifyWebhook`, not from the payer's return to
80
- your `successUrl`. See [Webhooks](./4.webhooks.md).
86
+ some payments after the call returns, and some after the payer has left. Your
87
+ backend learns a terminal state from `VerifyWebhook`, not from the payer's return
88
+ to your `successUrl`. See [Webhooks](./4.webhooks.md).
81
89
 
82
90
  ## Multi-account setups
83
91
 
84
- Every function takes an optional trailing `provider` argument naming which
85
- configured account to use, for a backend running more than one merchant account
86
- or more than one provider at once. Omit it for the default.
92
+ Every function takes an optional trailing `provider` argument. It names the
93
+ configured account to use, for a backend that runs more than one merchant
94
+ account or more than one provider at once. Omit it for the default account.
87
95
 
88
96
  ```ts
89
- await CreatePayment(request, key); // default account
90
- await CreatePayment(request, key, "marketplace"); // a named one
97
+ import {
98
+ CreatePayment,
99
+ type PaymentRequest,
100
+ } from "@antelopejs/interface-payment";
101
+
102
+ export async function charge(request: PaymentRequest, key: string) {
103
+ await CreatePayment(request, key); // default account
104
+ await CreatePayment(request, key, "marketplace"); // a named one
105
+ }
91
106
  ```